Buy

Buy a supported quote currency by paying the equivalent amount in the base currency.

The POST /api/v1/swap/buy endpoint collects the base_currency from the caller and, once payment is completed, pays out the quote_currency to the specified beneficiary_account.

Endpoint

POST {{base_url}}/api/v1/swap/buy

Authorization

Bearer Token

Headers

Header	Required	Description
`Authorization`	Yes	Bearer authentication token
`Content-Type`	Yes	`application/json`
`x-merchant-ref`	Yes	Merchant reference

Request Body

{
  "user_ref": "UREFB71CBD5EE9BE4AEFB0A1587839EAD87D007QQ",
  "beneficiary_account": {
    "account_no": "string",
    "bank_code": "string",
    "receiver_phone": "string",
    "network": "string",
    "receiver_name": "string",
    "receiver_email": "string",
    "narration": "string",
    "to_wallet_address": "crypto-wallet-address-xxxx"
  },
  "txn_merchant_ref": "trf000001_0122",
  "base_currency": "NGN",
  "quote_currency": "EUSD:MOB",
  "amount": 10000,
  "swap_type": "CHECKOUT_LINK",
  "pay_meta_data": {},
  "notification_url": "string"
}

Request Parameters

Parameter	Type	Required	Description
`user_ref`	String	Yes	Reference of the LedgerBlock user initiating the swap.
`beneficiary_account`	Object	Yes	Details of the beneficiary who will receive the `quote_currency`. The required fields depend on the payout rail.
`txn_merchant_ref`	String	Yes	Unique transaction reference generated by the merchant.
`base_currency`	String	Yes	Currency the caller pays, e.g. `NGN`.
`quote_currency`	String	Yes	Currency the caller receives, e.g. `EUSD:MOB`.
`amount`	Number	Yes	Amount of the `base_currency` being paid.
`swap_type`	String	Yes	Determines how the payment is completed.
`pay_meta_data`	Object	No	Additional payment metadata.
`notification_url`	String	Conditional	URL where LedgerBlock sends transaction status notifications.

Beneficiary Account Parameters

The fields required inside beneficiary_account depend on the payout rail.

Parameter	Type	Required	Description
`account_no`	String	Conditional	Beneficiary bank account number. Required for bank payouts.
`bank_code`	String	Conditional	Beneficiary bank code. Required for bank payouts.
`receiver_phone`	String	Conditional	Beneficiary's phone number. Required for mobile money payouts.
`network`	String	Conditional	Mobile money network. Required for mobile money payouts.
`receiver_name`	String	Conditional	Beneficiary's name.
`receiver_email`	String	Conditional	Beneficiary's email address.
`narration`	String	Conditional	Description or narration for the transaction.
`to_wallet_address`	String	Conditional	Destination wallet address. Required for crypto payouts.

Payout Rails

Payout Rail	Required Fields
Bank	`account_no`, `bank_code`
Mobile Money	`receiver_phone`, `network`
Crypto	`to_wallet_address`

Swap Type

Value	Description
`CHECKOUT_LINK`	Creates a hosted checkout payment link where the customer pays the `base_currency`.
`SERVER_2_SERVER`	Allows the merchant to complete the payment directly through a server-to-server flow, where supported.

Amount and Currency

For a Buy transaction:

base_currency is the currency the caller pays.
quote_currency is the currency the caller receives.
amount is denominated in the base_currency.

For example:

base_currency  = NGN
quote_currency = EUSD:MOB
amount         = 10000

This means the caller pays 10,000 NGN and receives the equivalent amount of EUSD:MOB based on the applicable exchange rate.

Response

{
  "status": "success",
  "message": "Please complete payment via pay_link",
  "data": {
    "payment_ref": "fb9f49b7-fcd3-42d5-9283-3e7b5f05586b",
    "txn_merchant_ref": "trf000001_0122",
    "base_currency": "NGN",
    "quote_currency": "EUSD:MOB",
    "amount": 10000,
    "expected_quote_amount": 5.882352941176471,
    "rate_used": 1700,
    "payment_status": "AWAITING_PAYMENT",
    "pay_data": {
      "pay_link": "https://blockpay.fuspay.finance/checkout?ref=fb9f49b7-fcd3-42d5-9283-3e7b5f05586b&currency=NGN&amount=10000&txn_ref=trf000001_0122"
    }
  }
}

Response Parameters

Parameter	Type	Description
`payment_ref`	String	Unique reference generated for the payment.
`txn_merchant_ref`	String	Merchant's transaction reference.
`base_currency`	String	Currency paid by the caller.
`quote_currency`	String	Currency received by the beneficiary.
`amount`	Number	Amount of the `base_currency` being paid.
`expected_quote_amount`	Number	Expected amount of `quote_currency` to be received based on the applied rate.
`rate_used`	Number	Exchange rate used for the transaction.
`payment_status`	String	Current payment status.
`pay_data`	Object	Contains payment information required to complete the transaction.
`pay_data.pay_link`	String	Hosted checkout link used by the customer to complete payment.

Checkout Flow

When swap_type is set to CHECKOUT_LINK, LedgerBlock returns a pay_link under data.pay_data.

The merchant should redirect the customer to the returned pay_link to complete payment.

The initial response returns:

payment_status: AWAITING_PAYMENT

This indicates that the base_currency payment has not yet been completed.

Once the customer completes payment:

LedgerBlock receives and verifies the base_currency payment.
The equivalent quote_currency is calculated using the applicable exchange rate.
LedgerBlock pays out the quote_currency to the specified beneficiary_account.
Transaction status updates are sent to the configured notification_url.

Important: Always use the pay_link returned in the API response. Do not construct the checkout URL manually.