Creating crypto payment

Preparation

Before you can start accepting payments automatically, you need to make settings and specify callback URL. Also you need get API token

Creating an invoice

Request at crypto currency

An example of a request to create an invoice in processing

Production

POST https://api.xamax.io/v1/transaction/invoice HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
    "txId": "400",
    "code": "usdt",
    "amount": "20000000"
}

Sandbox

POST https://api.sandbox.xamax.io/v1/transaction/invoice HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
    "txId": "400",
    "code": "usdt",
    "amount": "20000000"
}

SwaggerAPI documentationHow to get access tokenContact to support

Parameter	Type	Description	Default value	Example
txId *	string	Unique end-to-end transaction identifier of the merchant (platform). Used to map a transaction in processing to a transaction in the merchant system		100
code *	string	Crypto code		usdt
amount *	string	Requested amount in blockchain units 1 ETH = 1000000000000000000 wei 1 BTC = 100000000 satoshi 1 USDT = 1000000 units There are restrictions on the minimum replenishment amount		100000000
expiredAt	string	The maximum lifetime of a transaction. It is recommended to do no more than 30 minutes to avoid a sharp change in cryptocurrency rates	30 minutes	2022-12-01T11:31:30.685Z

* - Required parameter

Response

Parameter	Type	Description
txId	string	Merchant internal transaction id
walletAddress	string	Wallet address
walletType	string	Allowed values: wallet_type_unknown wallet_type_operation wallet_type_user wallet_type_invoice wallet_type_cold wallet_type_system Default:wallet_type_unknown
codeRequested	string	Cryptocurrency code requested
amountRequired	string	Merchant transaction required amount. Your amount should be greater then amountRequired. Check the minimum limit
amountRequiredUnit	string	Merchant transaction required amount. Your amountUnit should be greater then amountRequiredUnit. Check the minimum limit
expiredAt	string	Transaction expiration date. RFC3339 format. It is empty for invoice_type_user
status	string	Transaction status
txHash *	string	Transaction hash
amount *	string	Received amount from client
amountUnit *	string	Received amount from client. Human readable
confirmations *	string	Transaction confirmation in blockchain
createdAt	string	Transaction creation date. RFC3339 format
processingFeePercent	string	Processing fee in percent
processingFee	string	Processing fee
ExchangeRate.currency	string	Currency name
ExchangeRate.exchangeRate	string	Exchange rate from currency to crypto
ExchangeRate.currencyAmount	string	Multiply exchange rate to cryptocurrency
ExchangeRate.code	string	Cryptocurrency code
ExchangeRate *	string	Merchant internal transaction id
Link *	string	Merchant internal transaction id
Link.wallet	string	Wallet address for this transaction
Link.payment_link	string	Generated payment link for client's payment of the transaction
Link.onramp_link	string	Generated link to "Pay by card" for client's payment of the transaction. Available only for Bitcoin, Ethereum, Tether USD (ERC-20 and TRC-20), BSCUSD (BEP-20), Litecoin, Tron, Bitcoin Cash
id *	string	Internal ID

* - Returns only at waiting or completed transactions

Request at fiat currency

An example of a request to create an invoice in processing

Production

POST https://api.xamax.io/v1/transaction/invoice HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "txId": "150201",
  "code": "eth",
  "type": "invoice_type_default",
  "fiat": { 
      "amount": 1000,
      "currnecy": "usd"
    }
}

Sandbox

POST https://api.sandbox.xamax.io/v1/transaction/invoice HTTP/1.1
Authorization: Bearer {ACCESS_TOKEN}

{
  "txId": "150201",
  "code": "eth",
  "type": "invoice_type_default",
  "fiat": { 
      "amount": 1000,
      "currnecy": "usd"
    }
}

SwaggerAPI documentationHow to get access tokenContact to support

Parameter	Type	Description	Default value	Example
txId *	string	Unique end-to-end transaction identifier of the merchant (platform). Used to map a transaction in processing to a transaction in the merchant system		100
code *	string	Crypto code of currency, which You want to receive		usdt
type *	string	Type of invoice. More details is here	invoice_type_default
Fiat.Amount *	string	Requested amount in FIAT currency		1000
Fiat.Currency *	string	Requested FIAT currency		usd

* - Required parameter

Response

Parameter	Type	Description
txId	string	Merchant internal transaction id
walletAddress	string	Wallet address
walletType	string	Allowed values: wallet_type_unknown wallet_type_operation wallet_type_user wallet_type_invoice wallet_type_cold wallet_type_system Default:wallet_type_unknown
codeRequested	string	Cryptocurrency code requested
amountRequired	string	Merchant transaction required amount. Your amount should be greater then amountRequired. Check the minimum limit
amountRequiredUnit	string	Merchant transaction required amount. Your amountUnit should be greater then amountRequiredUnit. Check the minimum limit
expiredAt	string	Transaction expiration date. RFC3339 format. It is empty for invoice_type_user
status	string	Transaction status
txHash *	string	Transaction hash
amount *	string	Received amount from client
amountUnit *	string	Received amount from client. Human readable
confirmations *	string	Transaction confirmation in blockchain
createdAt	string	Transaction creation date. RFC3339 format
processingFeePercent	string	Processing fee in percent
processingFee	string	Processing fee
ExchangeRate.currency	string	Currency name
ExchangeRate.exchangeRate	string	Exchange rate from currency to crypto
ExchangeRate.currencyAmount	string	Multiply exchange rate to cryptocurrency
ExchangeRate.code	string	Cryptocurrency code
ExchangeRate *	string	Merchant internal transaction id
Link *	string	Merchant internal transaction id
id *	string	Internal ID
Link.wallet	string	Wallet address for this transaction
Link.payment_link	string	Generated payment link for client's payment of the transaction
Link.onramp_link	string	Generated link to "Pay by card" for client's payment of the transaction. Available only for Bitcoin, Ethereum, Tether USD (ERC-20 and TRC-20), BSCUSD (BEP-20), Litecoin, Tron, Bitcoin Cash

* - Returns only at waiting or completed transactions

Transaction status

Status	Value	Description
Pending	transaction_status_pending	New transaction
Sending	transaction_status_sending	Transaction sending to blockchain
Waiting	transaction_status_waiting	Transaction in blockchain, wait confirmation
Confirmed	transaction_status_confirmed	Transaction confirmed in blockchain
Failed	transaction_status_failed	Transaction failed in blockchain. In case of problems on the part of the blockchain, the transaction from waiting can go to failed.
Processing	transaction_status_processing	Transaction processing *reserved
Cancelled	transaction_status_canceled	Transaction cancelled in processing. The cancelled status is not used, since it is necessary to catch the transaction before it goes to the blockchain, and this is a fairly short period of time. so not used yet. *reserved
Skipped	transaction_status_skipped	Transaction processing is skipped. *reserved
Dust	transaction_status_dust	Transaction incoming amount is small.
Check required	transaction_status_check_required	Need some manual check. The status of a manual check by support or a check before a refund.
Approve required	transaction_status_approve_required	Required manual approve for new transactions from merchant
Processed	transaction_status_processed	Transaction processed
Refund	transaction_status_refund	Transaction marked for refund. *reserved
Refunding	transaction_status_refunding	Transaction in refund process
Refunded	transaction_status_refunded	Transaction refunded
Expired	transaction_status_expired	Transaction expired

Customer payment

After creating an invoice, the client needs to show:

• or the address from the walletAddress field and the replenishment amount from amountRequired or amountRequiredUnit. The client must make the payment in single transaction that contains the requested amount to the last decimal place;
• or send URL of payment link and client pay the transaction
• or send URL of onramp link (if available)

After the client completes the transaction, a callback will be sent to the backend of the merchant. How to process them, see the section Transaction confirmation and callback processing

tip

The requested amount may differ from the amount specified by the processing in the amountRequired field. The amount may differ by the minimum blockchain units and may not exceed 1 cent in dollar terms.