Top-up

Get a card upon completing a top-up. Before proceeding with a top-up, please ensure you are aware of the minimum top-up amount and the types of currencies we support. The following API will help you obtain the necessary information.

Top-up Information

Retrieve currently available product information and top-up settings. If you wish to top up cards using pre-deposited funds, please refer to the topup with wallet to enable the feature.

Request

• Path: /merchant/info
• Method: GET

Response

• 200

  Name	Type	Required	Description
  cardProducts	[Card Product]	v	An array of card product
  supportedCurrencies	[Supported Currency]	v	Supported chain info including network type and currency symbol
  maxCardValidYear	Integer	v	Setting of the maximum validity period of the card. Please note that the actual card validity period will vary depending on the card type.
  maxCardBalance	String	v	Card maximum balance.
  minCreateTopup	String	v	Minimum top-up amount when creating a new card.
  minTopup	String	v	Minimum amount to top-up an existing card.
  cardCreationFee	String	v	The card creation fee will be deducted when creating the card.
  topupFeeRate	String	v	Top-up rate.
  minCreateTopupFromWallet	String		Minimum top-up amount when creating a new card from wallet.
  minTopupFromWallet	String		Minimum amount to top-up an existing card from wallet.
  cardCreationFeeFromWallet	String		The fee for creating a card through the wallet.
  topupFeeRateFromWallet	String		Top-up rate via wallet.

• 400

  Name	Type	Required	Description
  message	String	v	Error message

Create Top-up Address

Create a new top-up address by a specified currency. ​Please note that the top-up address can be reused, and creating blank addresses repeatedly will incur additional charges. Only the supported currency in Top-up Information can be used for calling this API.

Request

• Path: /merchant/topup/address/{currency}

• Method: POST

• Path Parameters

  Name	Type	Required	Description
  currency	String	v	Specify a supported currency in Top-up Information.

Response

• 200

  Name	Type	Required	Description
  address	String	v	Cryptocurrency address
  currency	String	v	Corresponding currency
  createdAt	String	v	Creation timestamp

• 400

  Name	Type	Required	Description
  message	String	v	Error message

Query Top-up Address

Retrieve top-up addresses by currency.

Request

• Path: /merchant/topup/address/{currency}

• Method: GET

• Path Parameters

  Name	Type	Required	Description
  currency	String	v	Specify a supported currency in Top-up Information.

Response

• 200

  Name	Type	Required	Description
  items	[Top-up Address]	v	An array of top-up address
  start	Integer	v	Start position of the query
  count	Integer	v	Quantity of items
  total	Integer	v	Quantity of queries

• 400

  Name	Type	Required	Description
  message	String	v	Error message

Top-up Request

Before submitting a top-up transaction, please ensure that the network, currency, and top-up address are correct, and the top-up amount is greater than or equal to the minimum top-up limit.
Once cryptocurrency transaction is on-chain, you can use this API to submit a top-up request. If the cardId parameter is not provided in request body, a new card will be created.

• Card creation and top-up will only be processed after the transaction is confirmed on-chain and reaches the required number of confirmations.
  
• Please note that there will be a slight delay in card creation and will not be generated immediately. Please use the query function to find the associated card information.

Request

• Path: /merchant/card/topup

• Method: POST

• Request Body

  Name	Type	Required	Description
  amount	String	v	Transaction amount in base unit
  currency	String	v	Specified currency
  address	String	v	Payee address
  hash	String	v	On-chain transaction hash
  cardId	String		Specify an existing card. If cardId is not specified, a new card will be created.
  productId	String		Specify the product to be created. If no productId is included in the request, the default product will be used.

Response

• 200

  Name	Type	Required	Description
  id	String	v	Top-up ID
  createdAt	String	v	Creation timestamp
  amount	String	v	Transaction amount in base unit
  currency	String	v	Top-up currency
  address	String	v	Payee address
  hash	String	v	On-chain transaction hash
  cardId	string		The card ID associated with the request, which can be queried after the card is created.

• 400

  Name	Type	Required	Description
  message	String	v	Error message

Get Top-up Request

Obtain a single request history by a specified top-up ID.

Request

• Path: /merchant/card/topup/{topupId}

• Method: GET

• Path Parameters

  Name	Type	Required	Description
  topupId	String	v

Response

• 200

  Name	Type	Required	Description
  id	String	v	Top-up ID
  createdAt	String	v	Creation timestamp
  amount	String	v	Transaction amount in base unit
  currency	String	v	Top-up currency
  address	String		Payee address. If using wallet top-up, there will be no address or hash information.
  hash	String		On-chain transaction hash
  cardId	string		The card associated with the request.
  productId	String		The product associated with the request.

• 400

  Name	Type	Required	Description
  message	String	v	Error message

Query Top-up Requests

Get historical top-up requests

Request

• Path: /merchant/card/topup{?skip,limit}

• Method: GET

• Query Strings

  Name	Type	Required	Description
  skip	String		Quantity to skip default: 0
  limit	String		Quantity to query default: 25

Response

• 200

  Name	Type	Required	Description
  items	[Topup]	v	Array of topup
  start	Integer	v	Start position of the query
  count	Integer	v	Quantity of items
  total	Integer	v	Quantity of queries

• 400

  Name	Type	Required	Description
  message	String	v	Error message