Cryptocurrency Reference Guide

This guide covers cryptocurrency payments using the POST /api/v1/order endpoint and cryptocurrency payouts using the POST /api/v1/payouts endpoint.

Supported Cryptocurrencies Table

The table below lists all the cryptocurrencies supported by our API:

asset_code	crypto_currency_code	blockchain	cryptoTokenStandard	native	decimal_places
BTC	BTC	Bitcoin	-	true	8
BNB	BNB	BNB Chain	-	true	18
DOGE	DOGE	Dogecoin	-	true	8
ETH	ETH	Ethereum	-	true	18
LTC	LTC	Litecoin	-	true	8
MATIC	MATIC	Polygon	-	true	18
TRX	TRX	TRON	-	true	6
USDC_ERC20	USDC	Ethereum	ERC20	false	6
USDT_TRC20	USDT	TRON	TRC20	false	6
USDT_ERC20	USDT	Ethereum	ERC20	false	6
USDT_BEP20	USDT	BNB Chain	BEP20	false	18
XRP	XRP	XRP Ledger	-	true	18
TON	TON	TON	-	true	9
USDT_SPL	USDT	Solana	SPL	false	6
BCH	BCH	Bitcoin Cash	-	true	8
MATIC_ERC20	MATIC	Ethereum	ERC20	false	18
USDC_TRC20	USDC	TRON	TRC20	false	6
SOL	SOL	Solana	-	true	9

Column Descriptions

• asset_code: A unique identifier that combines the cryptocurrency code with the blockchain/token standard.
• crypto_currency_code: The symbol or abbreviation of the cryptocurrency.
• blockchain: The blockchain network on which the cryptocurrency operates.
• cryptoTokenStandard: The standard protocol for tokens on the blockchain. A dash (-) indicates that the cryptocurrency is native to the blockchain and does not use a token standard.
• native: Indicates whether the cryptocurrency is native to its blockchain (true) or a token (false).
• decimal_places: The number of decimal places used by the cryptocurrency. This defines the precision required when specifying amounts.

API Requests

When making API requests involving cryptocurrencies, you need to provide specific details based on the cryptocurrency you're using. There are two ways to specify the currency in your API requests.

For a crypto payment, the request may carry two independent currency values:

• Customer wallet currency — the cryptocurrency the customer pays with. It is defined by order.cost.currency plus, for token-based cryptocurrencies, order.cost.tokenStandard.
• Merchant balance currency — the currency in which the merchant holds funds and in which the provider denominates the operation. It is defined by recipient.merchantBalance.currency plus, for token-based cryptocurrencies, recipient.merchantBalance.tokenStandard. The merchant balance currency may be either fiat or crypto and is required only for providers that ask for it explicitly.

Method 1: Using crypto_currency_code with tokenStandard

This method specifies the cryptocurrency by its symbol and, when needed, its token standard.

Specify the Currency Code

• Use the crypto_currency_code in the order.cost.currency field of your API request.
• If the cryptocurrency is native (native is true), the order.cost.tokenStandard field is not required.
• Example for a native cryptocurrency (BTC):

  {
    "order": {
      "cost": {
        "amount": "0.005",
        "currency": "BTC"
      }
    }
  }

Include the Token Standard

• The tokenStandard field in order.cost is optional. For token-based cryptocurrencies (where native is false in the table above), you should provide it to unambiguously identify the blockchain network on which the customer will pay — otherwise the system cannot distinguish, for example, USDT on TRON from USDT on Ethereum.
• Use the value from the cryptoTokenStandard column in the table above.
• Example for USDT on TRON:

  {
    "order": {
      "cost": {
        "amount": "100.00",
        "currency": "USDT",
        "tokenStandard": "TRC20"
      }
    }
  }

Method 2: Using asset_code

Alternatively, you can use the asset_code directly in the order.cost.currency field. This method eliminates the need to specify order.cost.tokenStandard separately, as the asset code already encodes this information.

For native cryptocurrencies, Method 1 and Method 2 are identical — the asset_code is the same as the crypto_currency_code (for example, BTC), and no token standard is involved either way.

• Example for USDT on TRON:

  {
    "order": {
      "cost": {
        "amount": "1.25",
        "currency": "USDT_TRC20"
      }
    }
  }

Required Fields for Cryptocurrency Payments

When creating a cryptocurrency payment order, certain fields are mandatory to ensure successful processing:

Always Required

• shopId: Your merchant shop identifier
• order.cost.currency: The cryptocurrency you want to accept
• customer: Customer object with identification data (see below)
• paymentSettings.redirectUrls: At least one redirect URL must be provided:
  • success: URL to redirect the customer after successful payment
  • failure: URL to redirect the customer after failed payment

Customer Identification Requirements

For cryptocurrency payments, customer identification is mandatory. You must provide at least one of the following fields in the customer object:

• customerId — to use an existing customer
• email — to identify or create customer by email
• phone — to identify or create customer by phone

Conditionally Required

• recipient.merchantBalance.currency: Required only if you're using the recipient.merchantBalance object to declare the merchant balance currency. See the section below for details.

Optional Fields

• order.orderNumber: Your internal order reference number
• order.cost.amount: The payment amount (see note below about flexible amounts)
• order.cost.tokenStandard: Token standard of the cryptocurrency specified in order.cost.currency. Should be provided when using Method 1 with token cryptocurrencies (for example, USDT, USDC) to identify the blockchain network. Not applicable to native cryptocurrencies, and not needed when using Method 2 (asset_code).
• recipient.merchantBalance.tokenStandard: Token standard of the merchant balance currency. Should be provided when recipient.merchantBalance.currency is a token-based cryptocurrency; ignored for fiat currencies.
• paymentSettings.providerCode: Specific payment provider code
• paymentSettings.acquirerCode: Specific acquirer code

Note on payment amounts: While the amount field is part of the standard order structure, the actual payment amount received may differ from the specified amount. The system will automatically update the order with the actual amount received from the provider.

Additional Guidelines

Avoid Ambiguity with Tokens on Multiple Blockchains

Some tokens exist on multiple blockchains — for example, USDT is available on TRON, Ethereum, and BNB Chain. To specify unambiguously which blockchain the customer will use, either set order.cost.tokenStandard (Method 1) or use the suffixed asset_code in order.cost.currency (Method 2). The full list of supported combinations is in the Supported Cryptocurrencies Table above.

Declaring the Merchant Balance Currency (Provider-Specific)

Some payment providers require you to declare the merchant balance currency in addition to the currency the customer pays with. Use the recipient.merchantBalance object for this. The merchant balance currency may be either:

• A fiat currency (for example, USD, EUR — ISO 4217 alphabetic code format)
• A cryptocurrency (for example, BTC, ETH, USDT)

The merchantBalance object contains two fields:

• currency (required when merchantBalance is used): The merchant balance currency code.
• tokenStandard (optional): The token standard of the merchant balance currency (for example, ERC20 for Ethereum tokens). Should be provided when currency is a token-based cryptocurrency to identify the blockchain network; ignored for fiat currencies.

Example with merchantBalance (both customer wallet and merchant balance are crypto):

{
  "order": {
    "cost": {
      "amount": "20",
      "currency": "USDT",
      "tokenStandard": "TRC20"
    }
  },
  "recipient": {
    "merchantBalance": {
      "currency": "USDC",
      "tokenStandard": "TRC20"
    }
  }
}

Example with merchantBalance as fiat:

{
  "order": {
    "cost": {
      "amount": "1",
      "currency": "TON"
    }
  },
  "recipient": {
    "merchantBalance": {
      "currency": "EUR"
    }
  }
}

Note: When merchantBalance.currency is a fiat currency (for example, USD or EUR), or a native cryptocurrency without a distinct token standard, leave tokenStandard as null or omit it entirely — any value provided will be ignored.

Sample API Request Structure for Payments

Here's how a complete API request to POST /api/v1/order might look when including cryptocurrency details for payments:

Using Method 1 (crypto_currency_code with tokenStandard)

For a Native Cryptocurrency (e.g., BTC):

{
  "shopId": 12345,
  "order": {
    "orderNumber": "ORD-987654",
    "cost": {
      "amount": "0.0025",
      "currency": "BTC"
    }
  },
  "customer": {
    "customerId": "cust_001"
  },
  "paymentSettings": {
    "redirectUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    }
  }
}

For a Token Cryptocurrency (e.g., USDT on TRON):

{
  "shopId": 12345,
  "order": {
    "orderNumber": "ORD-987654",
    "cost": {
      "amount": "100.00",
      "currency": "USDT",
      "tokenStandard": "TRC20"
    }
  },
  "customer": {
    "customerId": "cust_001"
  },
  "paymentSettings": {
    "redirectUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    }
  }
}

Using Method 2 (asset_code)

For a Token Cryptocurrency (e.g., USDT on TRON):

{
  "shopId": 12345,
  "order": {
    "orderNumber": "ORD-987654",
    "cost": {
      "amount": "100.00",
      "currency": "USDT_TRC20"
    }
  },
  "customer": {
    "customerId": "cust_001"
  },
  "paymentSettings": {
    "redirectUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    }
  }
}

For a native cryptocurrency, the request is identical to the Method 1 native example above — simply use the native crypto_currency_code as the currency value.

With recipient.merchantBalance (Provider-Specific)

For providers that require the merchant balance currency to be declared:

{
  "shopId": 12345,
  "order": {
    "orderNumber": "ORD-987654",
    "cost": {
      "amount": "100.00",
      "currency": "USDT",
      "tokenStandard": "TRC20"
    }
  },
  "customer": {
    "customerId": "cust_001"
  },
  "recipient": {
    "merchantBalance": {
      "currency": "USDT",
      "tokenStandard": "ERC20"
    }
  },
  "paymentSettings": {
    "webhookUrl": "https://example.com/webhook",
    "redirectUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    }
  }
}

---

Cryptocurrency Payouts

This section covers cryptocurrency payouts using the POST /api/v1/payouts endpoint. The same cryptocurrencies listed in the Supported Cryptocurrencies Table are available for payouts.

Specifying Cryptocurrency for Payouts

When making payout requests involving cryptocurrencies, you can use the same two methods as for payments to specify the currency:

Method 1: Using crypto_currency_code with cryptoTokenStandard

This method requires specifying the cryptocurrency symbol in the cost.currency field and the token standard (if applicable) in the payout.cryptoTokenStandard field.

Specify the Currency Code

• Use the crypto_currency_code in the payout.cost.currency field of your API request.
• If the cryptocurrency is native (native is true), the cryptoTokenStandard field is not required.
• Example for a native cryptocurrency (BTC):

  {
    "payout": {
      "cost": {
        "amount": "0.005",
        "currency": "BTC"
      }
    }
  }

Include the Token Standard

• If the cryptocurrency is a token (native is false), you must include the cryptoTokenStandard field inside the payout object.
• Use the value from the cryptoTokenStandard column in the table above.
• Example for USDT on TRON:

  {
    "payout": {
      "cost": {
        "amount": "100.00",
        "currency": "USDT"
      },
      "cryptoTokenStandard": "TRC20"
    }
  }

Method 2: Using asset_code

Alternatively, you can use the asset_code directly in the cost.currency field. This method eliminates the need to specify the cryptoTokenStandard field separately, as the asset code already includes this information.

• Example for USDT on TRON:

  {
    "payout": {
      "cost": {
        "amount": "100.00",
        "currency": "USDT_TRC20"
      }
    }
  }

• Example for native cryptocurrency (BTC):

  {
    "payout": {
      "cost": {
        "amount": "0.005",
        "currency": "BTC"
      }
    }
  }

Using Source Currency (Provider-Specific)

Some payout providers require you to specify an additional sourceCurrency parameter within the payoutData object for the sender and/or recipient. This represents the currency in which the sender's or recipient's account is denominated and can be either:

• A fiat currency (e.g., "USD", "EUR" - ISO 4217 alphabetic code format)
• A cryptocurrency (e.g., "BTC", "ETH", "USDT")

The sourceCurrency parameter is used when the payout involves currency conversion or when the provider needs to know the denomination currency of the account, even if the payout is being made in a different cryptocurrency.