Balance Exchange Request

Introduction

Use this interface for initiating exchange requests between account balances

Typical scenarios:

• For payin business, the merchant needs to switch the settlement currency.
• For payout business, the merchant needs to convert to the originating currency as the available balance for remittance when the local currency balance is insufficient.

Typical applications:

• Converting 10.00 CNY to the corresponding USD

  • Parameters: currency_buy: USD, currency_sell: CNY, amount_sell: 10.00

• Convert CNY balance to 10.00 USD

  • Parameters: currency_buy: USD, currency_sell: CNY, amount_buy: 10.00

Description of returned parameters

• status: pending (when requested), succeeded (when accepted)
• fx_converted: currency_sell / currency_buy
  • For accounts of type payin: apply currency conversion fee rate for payout.
  • For accounts of type payout: apply currency conversion fee rate for payout.
• time_expired: defaults to 23:59:59 on the day of expiration.

Interface

POST /v1/balance_exchange/quote

Request Params

Field	Name	Type	Range	Example	Default	Optional	Remark	Rule
currency_buy	Currency to buy	string	[1, 64]		required
currency_sell	Currency to sell	string	[1,64]		required
amount_buy	Amount to buy	string	[1,64]		optional
amount_sell	Amount to sell	string	[1,64]		optional
description	Description	string	[1,64]		optional

Response Params

Response Example

200 success:

{
  "id": "fxqt_HWr1i",
  "livemode": true,
  "object": "fx_quote",
  "account": "acct_yz50aD",
  "currency_buy": "HKD",
  "amount_buy": "0.08",
  "currency_sell": "USD",
  "amount_sell": "0.01",
  "fx_converted": 7.58253,
  "status": "pending",
  "description": "test description",
  "type": "sell",
  "time_created": "2023-11-13T15:53:58+08:00",
  "time_expired": "2023-11-13T23:59:59+08:00"
}

400 error:

{
  "error": {
    "type": "invalid_request_error",
    "message": "The account does not have enough balance to make the transaction."
  }
}