Create Payment

POST

/payments/create

Creates a new cryptocurrency payment request. This endpoint generates a crypto payment address for your customer to send funds to and initiates payment tracking.

Request Parameters

Parameter	Type	Description
amount required	number	The payment amount in the specified currency.
currency required	string	The currency code for the payment (e.g., USDTTRC20, BTC, ETH).
wallet_id optional	string	UUID v4 of the wallet to receive the payment. If not provided, payment will go to the main balance.
callback_url optional	string	A URL that will receive payment status updates via webhooks. Must be a valid HTTPS URL.
custom_id optional	string	Your custom identifier for this payment (e.g., an order number). Max 64 characters.
description optional	string	Description of the payment for your reference.

Example Request

POST /payments/create
Content-Type: application/json
X-API-Key: your_api_key_here

{
  "amount": 100.00,
  "currency": "USDTTRC20",
  "wallet_id": "550e8400-e29b-41d4-a716-446655440000",
  "callback_url": "https://your-site.com/payment/callback",
  "custom_id": "ORDER-12345",
  "description": "Payment for order #12345"
}

Response Parameters

Parameter	Type	Description
payment_id	string	Unique UUID v4 identifier for the payment. Use this to check status or reference the payment.
amount	number	The amount of cryptocurrency to be paid.
currency	string	The currency code used for the payment.
address	string	The cryptocurrency address where funds should be sent.
expiry_time	string	ISO 8601 timestamp indicating when the payment request expires.
wallet_id	string	The UUID v4 of the wallet receiving the payment, or null for main balance.
status	string	Current status of the payment: "pending", "confirming", "completed", "expired", or "failed".
payment_url	string	Optional URL to a hosted payment page (if available).

Example Response

{
  "payment_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "amount": 100.00,
  "currency": "USDTTRC20",
  "address": "TYN2WuEqttM5JjGk4ynGkxcnMRR9SZcvVx",
  "expiry_time": "2025-04-30T14:30:25.123Z",
  "wallet_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "payment_url": "https://cryptofuse.io/payment/f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Error Codes

Status Code	Error Code	Description
400	invalid_request	The request was malformed or contained invalid parameters.
401	unauthorized	Authentication failed. Check your API key or OAuth 2.0 access token.
403	forbidden	Your API key does not have permission to create payments.
404	wallet_not_found	The specified wallet_id was not found.
422	currency_invalid	The specified currency is not supported or not enabled for your account.
429	rate_limit_exceeded	You have exceeded the rate limit for payment creation.
500	server_error	An error occurred with the payment processor. Contact support if this persists.

Notes

Payment requests typically expire after 1 hour if not completed. The exact time is indicated in the expiry_time field.
You should store the payment_id in your system to track the payment status.
If you provide a callback_url, you will receive payment status updates via webhooks. See the Implementing Callbacks guide for details.
If wallet_id is provided, the payment will be credited to that specific wallet. Otherwise, it will go to your main balance.
All UUIDs in the system follow the UUID v4 format (e.g., 550e8400-e29b-41d4-a716-446655440000).