Create Payment

POST

/payments/

Creates a new cryptocurrency payment request. This endpoint generates a unique EVM address for your customer to send ERC20 tokens to.

Authentication

Requires OAuth 2.0 authentication with read and write scopes.

Request Body

Specify the cryptocurrency using either:

pay_currency - Combined currency code (e.g., "USDTERC20")
blockchain + token - Separate fields (e.g., "ethereum" + "USDT")

Parameter	Type	Required	Description
`price_amount`	decimal	Yes	Amount to charge in price currency (e.g., 100.00)
`price_currency`	string	Yes	Currency for the price amount. Currently only "USD" supported
`pay_currency`	string	Conditional	Cryptocurrency code (e.g., "USDTERC20", "USDCERC20", "DAIERC20"). Required if blockchain/token not provided
`blockchain`	string	Conditional	Blockchain network (e.g., "ethereum", "polygon", "bsc"). Required with token if pay_currency not provided
`token`	string	Conditional	Token symbol (e.g., "USDT", "USDC", "DAI"). Required with blockchain if pay_currency not provided
`order_id`	string	No	Your internal order ID. Auto-generated if not provided. Max 100 characters
`order_description`	string	No	Description of the order/payment
`callback_url`	string	No	URL for webhook notifications about payment status changes
`success_url`	string	No	URL to redirect customer after successful payment
`cancel_url`	string	No	URL to redirect customer if payment is cancelled
`partially_payments_allow`	boolean	No	Allow partial payments. Default: false
`is_fixed_rate`	boolean	No	Use fixed exchange rate. Default: true
`is_fee_paid_by_user`	boolean	No	Whether user pays network fees. Default: true

Example Request

Using pay_currency:

curl -X POST https://api.cryptofuse.io/payments/ \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "price_amount": 100.00,
    "price_currency": "USD",
    "pay_currency": "USDTERC20",
    "order_id": "ORDER-12345",
    "order_description": "Premium subscription",
    "callback_url": "https://your-site.com/webhook/payment"
  }'

Using blockchain + token:

curl -X POST https://api.cryptofuse.io/payments/ \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "price_amount": 100.00,
    "price_currency": "USD",
    "blockchain": "ethereum",
    "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",
  "status": "waiting",
  "provider": "transaction_manager",
  "price_amount": "100.00",
  "price_currency": "USD",
  "pay_amount": "100.050000",
  "pay_currency": "USDTERC20",
  "blockchain_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f8b8E0",
  "blockchain_network": "ETH",
  "token": "USDT",
  "expiry_time": "2025-01-15T10:30:00Z",
  "order_id": "ORDER-12345",
  "order_description": "Premium subscription",
  "callback_url": "https://your-site.com/webhook/payment",
  "is_fixed_rate": true,
  "is_fee_paid_by_user": true,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

Response Fields

Field	Type	Description
`transaction_id`	uuid	Unique payment identifier. Store this for status checks
`status`	string	Current payment status. Initially "waiting"
`blockchain_address`	string	EVM address where customer should send payment
`pay_amount`	string	Exact amount customer must send (includes fees if user pays)
`pay_currency`	string	Full currency code for the payment
`expiry_time`	datetime	ISO 8601 timestamp when payment expires

Error Responses

400 Bad Request

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

422 Unprocessable Entity

{
  "error": {
    "code": "invalid_currency",
    "message": "Currency FAKECOIN is not supported",
    "details": {
      "supported_currencies": ["USDTERC20", "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

Supported Currencies

ERC20 Tokens (Ethereum)

USDTERC20 - Tether USD
USDCERC20 - USD Coin
DAIERC20 - DAI Stablecoin

Other Networks

Use blockchain + token combination for other networks:

Polygon: blockchain="polygon", token="USDT"
BSC: blockchain="bsc", token="USDT"
Arbitrum: blockchain="arbitrum", token="USDT"

Important Notes

Payments expire after 30 minutes by default
Each payment generates a unique EVM 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
All amounts are in decimal format with up to 8 decimal places

Testing

In the staging environment, use these amounts for testing:

123.45 USD - Instant success
666.66 USD - Instant failure
100.00 USD - Normal flow with confirmations