Initiate Transaction

This is the next and final step involved in 'creating' a transaction via API on Basqet.

API Details

Action: Initiate Transaction
Method: POST
Path: /v1/transaction/:transaction_id/pay
Auth Requirement: None

Business Summary

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

You can use this API to:

Select the specific 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 a 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

Query 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 transaction’s metadata.

Request Headers

Name	Type	Required	Default	Allowed Values	Description
Authorization	string	Yes	-	-	Bearer YOUR_SECRET_KEY
Content-Type	string	Yes	application/json	application/json	The media type of the resource.

Request Examples

cURL

curl \--request POST \

  --url <https://api.basqet.com/v1/transaction/BASQET\_TXN\_REF\_12345/pay> \

  --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 for the transaction details
data.id	integer	No	Unique internal identifier for the transaction
data.reference	string	No	The transaction reference for the merchant
data.description	string	Yes	The Transaction description provided during initialization
data.initialized_amount	number	No	The original fiat amount
data.initialized_currency	string	No	The fiat currency slug (e.g., USD, NGN).
data.payment_amount	number	No	The amount in crypto to be sent
data.amount_paid	number	Yes	null until payment is confirmed on-chain.
data.payment_currency	number	Yes	Internal currency ID for the selected fiat currency. It is null until payment is initiated.
data.payment_address	string	No	The destination wallet address
data.status	string	No	The current status of the transaction. 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 if the transaction is in live or test mode
data.merchant	object	No	Information about the merchant account
data.merchant.id	integer	No	Unique identifier for the merchant
data.merchant.name	string	No	The registered name of the merchant
data.meta	object	Yes	Additional configuration like 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/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 also occurs 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 the wallet address. Retry the request.

Webhook Payload

Payment Pending (`payment.pending`)

When a transaction has been initiated and is awaiting payment, we make a POST request to your webhook URL (as set up in your dashboard). This is the format of the webhook payload you will receive:

{
  "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, we make a POST request to your webhook URL (as set up in your dashboard). This is the format of the webhook payload you will receive:

{
  "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 (e.g., the checkout session expires), we make a POST request to your webhook URL (as set up in your dashboard). This is the format of the webhook payload you will receive:

{
  "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": {}
    }
  }
}