Initiate Transaction

API Details

Field	Value
Action	Initiate Transaction
Method	`POST`
Path	`/v1/transaction/:transaction_id/pay`
Auth Requirement	Secret key

Business Summary

This endpoint updates the transaction object by assigning a cryptocurrency to it and returning the calculated crypto amount and payment address.

You can use this API to:

Select the cryptocurrency the customer wants to use to convert an INITIATED transaction into a live payment request.
Transition the transaction to the PENDING state to generate a unique wallet address and QR code for the customer.
Lock in the real-time conversion rate to determine the exact amount of crypto the customer needs to send.

Request Parameters

Path Parameters

Name	Type	Required	Default	Allowed Values	Description
`transaction_id`	string	Yes	—	—	The unique identifier of the transaction.

Body Parameters

Name	Type	Required	Default	Allowed Values	Description
`currency_id`	string	Yes	—	Tether: `3`, Bitcoin: `4`, Quidax Token: `5`, Ethereum: `6`, Litecoin: `7`	The unique identifier of the cryptocurrency the customer wishes to pay in.
`refund_address`	string	No	—	—	Optional refund address stored in the transaction metadata.

Request Headers

Name	Type	Required	Default	Description
`Authorization`	string	Yes	—	Bearer token in the form `Bearer YOUR_SECRET_KEY`.
`Content-Type`	string	Yes	`application/json`	The media type of the resource. Must be `application/json`.

Request Example

cURL

curl --request POST \
  --url https://api.basqet.com/v1/transaction/BASQET_TXN_REF_12345/pay \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "currency_id": 2,
    "refund_address": "0x4f3edf983ac636a65a842ce7c78d9aa706d3b113"
  }'

Response Schema

Field	Type	Nullable	Description
`status`	string	No	Status of the API request.
`data`	object	No	Object containing the transaction details.
`data.id`	string	No	Unique internal identifier for the transaction.
`data.reference`	string	No	Transaction reference for the merchant.
`data.description`	string	Yes	Transaction description provided during initialization.
`data.initialized_amount`	number	No	Original fiat amount.
`data.initialized_currency`	string	No	Fiat currency slug, e.g. `USD` or `NGN`.
`data.payment_amount`	number	No	Crypto amount to be sent.
`data.amount_paid`	number	Yes	`null` until payment is confirmed on-chain.
`data.payment_currency`	number/string	Yes	Selected crypto currency or internal currency ID, depending on response format.
`data.payment_address`	string	No	Destination wallet address.
`data.status`	string	No	Current transaction status. Becomes `PENDING` after successful initiation.
`data.qrCode`	string	No	Base64 data URL of the QR code for the `payment_address`.
`data.is_live`	boolean	Yes	Indicates whether the transaction is in live or test mode.
`data.merchant`	object	No	Merchant account information.
`data.merchant.id`	integer	No	Unique identifier for the merchant.
`data.merchant.name`	string	No	Registered merchant name.
`data.meta`	object	Yes	Additional configuration, such as fee bearer and refund address.

Sample Response

{
  "status": "success",
  "data": {
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "id": "BASQET_TXN_REF_12345",
    "reference": "BASQET_TXN_REF_12345",
    "amount_paid": null,
    "status": "PENDING",
    "description": "Invoice #1024",
    "initialized_amount": 1500,
    "payment_amount": 0.002357,
    "payment_address": "bc1qexampleaddress",
    "payment_currency": "BTC",
    "initialized_currency": "USD",
    "is_live": true,
    "merchant": {
      "id": 10,
      "name": "Acme Store"
    }
  },
  "meta": {}
}

Error Reference

HTTP Code	Message	Resolution
`400`	Missing or invalid payload fields	Ensure `currency_id` is present and numeric, and that the `refund_address` format is valid.
`404`	Varies	Occurs if the `transaction_id` is invalid, the selected `currency_id` is not supported, or the merchant’s subaccount/processor is not configured.
`422`	The transaction is not initiated	Verify that the transaction is still in the `INITIATED` state. This can also occur if the merchant account is inactive.
`500`	Internal Server Error	An unexpected server-side error occurred. Retry the request or contact support.
`503`	Varies	An upstream error occurred while generating the price quote or wallet address. Retry the request.

Webhook Payloads

Payment Pending (`payment.pending`)

When a transaction has been initiated and is awaiting payment, Basqet sends a POST request to your webhook URL, as set up in your dashboard.

{
  "event": "payment.pending",
  "data": {
    "transaction": {
      "reference": "bq_B09BMmXXgWMzRSmon",
      "merchant_name": "Appstate",
      "payment_currency": 6,
      "payment_currency_name": "Ethereum",
      "payment_currency_slug": "ETH",
      "status": "PENDING",
      "customer_email": "[email protected]",
      "customer_name": "tunde",
      "payment_amount": 0.001366,
      "amount_paid": null,
      "description": null,
      "is_live": false,
      "created_at": "2022-07-14T20:17:11.000Z",
      "meta": {}
    }
  }
}

Payment Completed (`payment.received`)

When a transaction is successfully completed and the merchant has received payment, Basqet sends a POST request to your webhook URL, as set up in your dashboard.

{
  "event": "payment.received",
  "data": {
    "transaction": {
      "reference": "bq_RkaUV0Zy3PGpQsT8c",
      "merchant_name": "Bar BQ Express",
      "payment_currency": 3,
      "payment_currency_name": "Bitcoin",
      "payment_currency_slug": "BTC",
      "status": "SUCCESSFUL",
      "customer_email": "[email protected]",
      "customer_name": "John Doe",
      "payment_amount": 1,
      "amount_paid": 1,
      "description": "Payment for Lamborghini",
      "is_live": false,
      "created_at": "2026-02-09T16:18:20.000Z",
      "meta": {}
    }
  }
}

Payment Abandoned (`payment.abandoned`)

When a transaction has been abandoned by the customer, for example when the checkout session expires, Basqet sends a POST request to your webhook URL, as set up in your dashboard.

{
  "event": "payment.abandoned",
  "data": {
    "transaction": {
      "reference": "bq_B09BMmXXgWMzRSmon",
      "merchant_name": "Appstate",
      "payment_currency": 6,
      "payment_currency_name": "Ethereum",
      "payment_currency_slug": "ETH",
      "status": "ABANDONED",
      "customer_email": "[email protected]",
      "customer_name": "tunde",
      "payment_amount": 0.001366,
      "amount_paid": null,
      "description": null,
      "is_live": false,
      "created_at": "2022-07-14T20:17:11.000Z",
      "meta": {}
    }
  }
}