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:

Method 1: Using crypto_currency_code with walletTokenStandard

This method uses the cryptoPayment object to specify cryptocurrency details.

Specify the Currency Code

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

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

Include the Wallet Token Standard

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

  {
    "order": {
      "cost": {
        "amount": "100.00",
        "currency": "USDT"
      }
    },
    "cryptoPayment": {
      "walletTokenStandard": "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 cryptoPayment object and walletTokenStandard separately, as the asset code already includes this information.

• Example for USDT on TRON:

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

• Example for native cryptocurrency (BTC):

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

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
• 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

Conditionally Required

• cryptoPayment.walletTokenStandard: Required only when using Method 1 with token cryptocurrencies (e.g., USDT, USDC). Not required for native cryptocurrencies or when using Method 2 (asset_code).
• cryptoPayment.accountCurrency.currency: Required only if you're using the accountCurrency object. 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)
• cryptoPayment.accountCurrency.networkTokenStandard: Token standard for the account currency
• 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 (e.g., USDT). When using Method 1, use the walletTokenStandard inside cryptoPayment to specify which blockchain you're using. Alternatively, use Method 2 with the appropriate asset_code.
• Example using Method 1:
  • For USDT on Ethereum:

    {
      "order": {
        "cost": {
          "amount": "75.00",
          "currency": "USDT"
        }
      },
      "cryptoPayment": {
        "walletTokenStandard": "ERC20"
      }
    }
  • For USDT on BNB Chain:

    {
      "order": {
        "cost": {
          "amount": "75.00",
          "currency": "USDT"
        }
      },
      "cryptoPayment": {
        "walletTokenStandard": "BEP20"
      }
    }
• Example using Method 2:
  • For USDT on Ethereum: use "currency": "USDT_ERC20"
  • For USDT on BNB Chain: use "currency": "USDT_BEP20"

Using Account Currency (Provider-Specific)

Some payment providers require you to specify an additional accountCurrency parameter within the cryptoPayment object. This represents the currency in which the merchant'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 accountCurrency object contains two fields:

• currency (required if using accountCurrency): The account currency code
• networkTokenStandard (optional): The token standard for the account currency (e.g., "ERC20" for Ethereum tokens)

Example with accountCurrency:

{
  "order": {
    "cost": {
      "amount": "100.00",
      "currency": "USDT"
    }
  },
  "cryptoPayment": {
    "walletTokenStandard": "TRC20",
    "accountCurrency": {
      "currency": "USDT",
      "networkTokenStandard": "ERC20"
    }
  }
}

Note: If you're using a fiat currency as accountCurrency.currency (such as "USD" or "EUR"), or a cryptocurrency without a distinct token standard, you can leave networkTokenStandard as null or omit it entirely.

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 walletTokenStandard)

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

{
  "shopId": "shop_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": "shop_12345",
  "order": {
    "orderNumber": "ORD-987654",
    "cost": {
      "amount": "100.00",
      "currency": "USDT"
    }
  },
  "customer": {
    "customerId": "cust_001"
  },
  "cryptoPayment": {
    "walletTokenStandard": "TRC20"
  },
  "paymentSettings": {
    "redirectUrls": {
      "success": "https://example.com/success",
      "failure": "https://example.com/failure"
    }
  }
}

Using Method 2 (asset_code)

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

{
  "shopId": "shop_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": "shop_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"
    }
  }
}

With accountCurrency (Provider-Specific)

For providers that require account currency specification:

{
  "shopId": "shop_12345",
  "order": {
    "orderNumber": "ORD-987654",
    "cost": {
      "amount": "100.00",
      "currency": "USDT"
    }
  },
  "customer": {
    "customerId": "cust_001"
  },
  "cryptoPayment": {
    "walletTokenStandard": "TRC20",
    "accountCurrency": {
      "currency": "USDT",
      "networkTokenStandard": "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.