Create Payment

POST

/payments/

Creates a new cryptocurrency payment request. This endpoint generates a unique blockchain address for your customer to send funds to.

Authentication

Requires OAuth 2.0 authentication with read and write scopes.

Request Body

Specify the cryptocurrency using either:

currency - Combined code (e.g., "USDTTRC20")
blockchain + token - Separate fields (e.g., "TRON" + "USDT")

Parameter	Type	Required	Description
`amount`	decimal	Yes	Payment amount in the price currency (e.g., 100.00)
`currency`	string	Conditional	Combined currency code (e.g., "USDTTRC20", "USDCERC20"). Required if blockchain/token not provided
`blockchain`	string	Conditional	Blockchain network (e.g., "TRON", "ETH"). Required with token if currency not provided
`token`	string	Conditional	Token symbol (e.g., "USDT", "USDC", "BTC"). Required with blockchain if currency not provided
`price_currency`	string	No	Fiat currency for the amount. Default: "USD"
`order_id`	string	No	Your internal order ID. Max 100 characters
`order_description`	string	No	Description of the order/payment
`callback_url`	string (URL)	No	URL for webhook notifications about payment status changes
`custom_id`	string	No	Your custom identifier for this payment. Max 64 characters
`is_fixed_rate`	boolean	No	Use fixed exchange rate. Default: true
`is_fee_paid_by_user`	boolean	No	Whether the customer pays network fees
`customer_email`	string (email)	No	Email address of the customer
`wallet_id`	string	No	Wallet identifier. Max 64 characters
`expiry_minutes`	integer	No	Payment expiration time in minutes. Min: 1, Max: 1440 (24 hours)

Example Request

Using currency:

curl -X POST {{BASE_URL}}/payments/ \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USDTTRC20",
    "order_id": "ORDER-12345",
    "order_description": "Premium subscription",
    "callback_url": "https://your-site.com/webhook/payment"
  }'

Using blockchain + token:

curl -X POST {{BASE_URL}}/payments/ \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "blockchain": "TRON",
    "token": "USDT",
    "order_id": "ORDER-12345",
    "callback_url": "https://your-site.com/webhook/payment"
  }'

Response

Success Response (201 Created)

{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "blockchain": "TRX",
  "currency": "USDTTRC20",
  "status": "waiting",
  "amount_usd": "100.00",
  "amount_crypto": "100.050000",
  "address": "TYN2WuEqttM5JjGk4ynGkxcnMRR9SZcvVx",
  "token": "USDT",
  "transaction_hash": null,
  "order_id": "ORDER-12345",
  "order_description": "Premium subscription",
  "callback_url": "https://your-site.com/webhook/payment",
  "expiry_time": "2026-01-15T10:30:00Z",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-15T10:00:00Z",
  "is_fixed_rate": true,
  "is_fee_paid_by_user": false
}

Response Fields

Field	Type	Description
`transaction_id`	uuid	Unique payment identifier. Store this for status checks
`blockchain`	string	Blockchain network (e.g., "TRX", "ETH")
`currency`	string	Combined currency code (e.g., "USDTTRC20")
`status`	string	Current payment status. Initially "waiting"
`amount_usd`	decimal	Amount in price currency (USD)
`amount_crypto`	string	Computed cryptocurrency amount the customer must send
`address`	string	Blockchain address where customer should send payment
`token`	string	Token symbol (e.g., "USDT", "USDC")
`transaction_hash`	string	Blockchain transaction hash (null until payment is detected)
`order_id`	string	Your order identifier
`order_description`	string	Payment description
`callback_url`	string	Webhook URL for status notifications
`expiry_time`	datetime	ISO 8601 timestamp when payment expires
`created_at`	datetime	ISO 8601 creation timestamp
`updated_at`	datetime	ISO 8601 last update timestamp
`is_fixed_rate`	boolean	Whether a fixed exchange rate was used
`is_fee_paid_by_user`	boolean	Whether the customer pays network fees

Error Responses

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": {
      "amount": ["This field is required."]
    }
  }
}

422 Unprocessable Entity

{
  "error": {
    "code": "invalid_currency",
    "message": "Currency FAKECOIN is not supported",
    "details": {
      "supported_currencies": ["USDTTRC20", "USDCERC20", "DAIERC20"]
    }
  }
}

Payment Status Values

Status	Description
`waiting`	Waiting for payment from customer
`confirming`	Payment received, waiting for blockchain confirmations
`confirmed`	Payment confirmed on blockchain
`sending`	Processing payment to merchant wallet
`completed`	Payment successfully completed
`expired`	Payment window expired without payment
`failed`	Payment failed

Important Notes

Each payment generates a unique blockchain address
Addresses are single-use and monitored only until expiry
Store the transaction_id to track payment status
Implement webhook handler for real-time status updates
Use expiry_minutes to control the payment window (defaults vary by configuration)