Sell

Sell a supported quote currency and receive the equivalent value in the base currency.

Endpoint

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

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": "{{vault:Merchant-user-ref}}",
  "txn_merchant_ref": "LGB_0033325",
  "base_currency": "NGN",
  "quote_currency": "EUSD:MOB",
  "amount": 1,
  "swap_type": "CHECKOUT_LINK",
  "beneficiary_account": {
    "account_no": "string",
    "bank_code": "string",
    "receiver_phone": "string",
    "network": "string",
    "receiver_name": "string",
    "receiver_email": "string",
    "narration": "string",
    "to_wallet_address": "string"
  },
  "notification_url": "string"
}

Request Parameters

Parameter	Type	Required	Description
`user_ref`	String	Yes	Reference of the LedgerBlock user initiating the swap.
`txn_merchant_ref`	String	Yes	Unique transaction reference generated by the merchant.
`base_currency`	String	Yes	Currency the user will receive, e.g. `NGN`.
`quote_currency`	String	Yes	Currency being sold, e.g. `EUSD:MOB`.
`amount`	Number	Yes	Amount being sold. The amount is denominated in the `quote_currency`.
`swap_type`	String	Yes	Determines how the swap is completed. Supported values are `CHECKOUT_LINK` and `SERVER_2_SERVER`.
`beneficiary_account`	Object	Conditional	Details of the beneficiary receiving the base currency.
`notification_url`	String	Conditional	URL where LedgerBlock sends transaction status notifications.

Beneficiary Account Parameters

Parameter	Type	Required	Description
`account_no`	String	Conditional	Beneficiary bank account number.
`bank_code`	String	Conditional	Beneficiary bank code.
`receiver_phone`	String	Conditional	Beneficiary's phone number.
`network`	String	Conditional	Network associated with the beneficiary.
`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 when the beneficiary receives funds in a wallet.

Swap Type

Value	Description
`CHECKOUT_LINK`	Creates a hosted checkout payment link that the customer is redirected to in order to complete the transaction.
`SERVER_2_SERVER`	Allows the merchant to complete the transaction directly through a server-to-server flow. This is only valid when `quote_currency` is a cryptocurrency, such as `EUSD:MOB`.

Amount and Currency

The amount is denominated in the quote_currency.

For example, if:

quote_currency = EUSD:MOB
base_currency = NGN
amount = 1

The transaction sells 1 EUSD:MOB and calculates the equivalent amount in NGN using the applicable exchange rate.

Response

{
  "status": "success",
  "message": "Please complete payment via pay_link",
  "data": {
    "payment_ref": "e30f645f-f6cf-465f-98db-92132329baef",
    "txn_merchant_ref": "LGB_0033325",
    "quote_currency": "EUSD:MOB",
    "base_currency": "NGN",
    "amount": 1,
    "expected_base_amount": 1490,
    "rate_used": 1490,
    "swap_type": "CHECKOUT_LINK",
    "payment_status": "AWAITING_PAYMENT",
    "pay_data": {
      "pay_link": "https://blockpay.fuspay.finance/checkout?ref=e30f645f-f6cf-465f-98db-92132329baef&currency=EUSD:MOB&amount=1&txn_ref=LGB_0033325"
    }
  }
}

Response Parameters

Parameter	Type	Description
`payment_ref`	String	Unique reference generated for the payment.
`txn_merchant_ref`	String	Merchant's transaction reference.
`quote_currency`	String	Currency being sold.
`base_currency`	String	Currency being received.
`amount`	Number	Amount of the quote currency being sold.
`expected_base_amount`	Number	Expected amount of base currency to be received based on the applied rate.
`rate_used`	Number	Exchange rate used for the transaction.
`swap_type`	String	Swap flow 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 the payment.

The initial response returns:

payment_status: AWAITING_PAYMENT

This indicates that the payment is waiting for the customer to be completed through the hosted checkout page.

Once the customer completes the payment, LedgerBlock processes the swap and sends transaction status updates to the configured notification_url.

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