There are two steps involved in creating a transaction via API on Basqet:
Initialize the transaction Initiate the transaction
Field Value Action Initialize Transaction Method POSTPath /v1/transactionAuth Requirement Public key or private key
This endpoint serves as the entry point for processing payments through Basqet. It creates a transaction object, which can then be initiated to collect payment from your customer. Once initialized, the transaction object provides the reference and structure required to proceed with payment.
You can use this API to:
Send your customer’s details to Basqet to generate a unique transaction record before they pay.
Use the resulting transaction ID to provide your customer with the wallet address and payment information they need to complete their crypto transfer.
Name Type Required Default Allowed Values Description customerobject Yes — — Customer’s details for the transaction. customer.namestring No null— Customer’s full name. customer.emailstring Yes — Any valid email, e.g. [email protected] Customer’s email address. public_keystring Conditional — Prefixed with pub_ Required when the public key is not sent in the Authorization header. payment_linkstring Conditional — Prefixed with pl_ Payment link slug. Cannot be sent alongside public_key. currencystring Yes NGNUSD, NGNFiat currency slug for the transaction. amountstring Yes — Numeric string Transaction amount to be paid in the specified currency, e.g. "1500". descriptionstring No null— Transaction description. metaobject No null— Custom data to pass with the transaction. Returned in the response.
Name Type Required Description Authorizationstring Conditional Bearer token in the form Bearer pub_.... Optional if public_key is passed in the request body. Content-Typestring Yes Must be application/json.
Bash
curl --request POST \
--url https://api.basqet.com/v1/transaction \
--header 'Authorization: Bearer pub_live_xxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
"customer": {
"name": "Test User",
"email": "[email protected] "
},
"currency": "USD",
"amount": "1000.00",
"description": "Test Transaction #001",
"meta": {
"test_mode": true,
"cart_id": "999"
}
}'
Field Type Nullable Description statusstring No Response status. Always success for 2xx responses. dataobject No Container for the transaction details. data.idstring No Unique internal identifier for the transaction. data.referencestring No Transaction reference for the merchant. data.amount_paidnumber Yes Actual amount received. Remains null until payment is made. data.statusstring No Current transaction state. Initial value is INITIATED. data.descriptionstring Yes Transaction description provided. null if omitted. data.initialized_amountnumber No Fiat amount specified during the request. data.payment_amountnumber Yes Crypto amount to be paid. null until payment is initiated. data.payment_addressstring Yes Destination crypto payment address. null until payment is initiated. data.payment_currencynumber Yes Internal currency ID for the selected crypto currency. null until payment is initiated. data.initialized_currencynumber No Internal currency ID for the fiat currency used to initialize the transaction. data.is_liveboolean No Indicates whether the transaction is in live mode. data.merchantobject No Merchant account information. data.merchant.idnumber No Unique internal identifier for the merchant. data.merchant.namestring No Merchant display name. metaobject No Echo of the request meta payload, or {} when omitted.
JSON
{
"status": "success",
"data": {
"id": "BASQET_TXN_REF_12345",
"reference": "BASQET_TXN_REF_12345",
"amount_paid": null,
"status": "INITIATED",
"description": "Invoice #1024",
"initialized_amount": 1500,
"payment_amount": null,
"payment_address": null,
"payment_currency": null,
"initialized_currency": 1,
"is_live": true,
"merchant": {
"id": 10,
"name": "Acme Store"
}
},
"meta": {
"order_id": "order_1024",
"channel": "web"
}
}
HTTP Code Message Resolution 400Validation Error Ensure all required fields are present: customer.email, amount, and currency. The email must be valid, and the amount must be a numeric string. This can also occur if both public_key and payment_link are sent together. 404Invalid Public Key Verify that the public_key or payment_link is correct, the merchant account is active, and the fiat currency slug is supported. 422Varies based on KYC status Ensure the merchant has completed the required KYB verification for live-mode transactions before attempting to initialize. 500Internal Server Error An unexpected error occurred. Retry the request or contact Basqet support.
public_key in the body and Authorization: Bearer pub_... are interchangeable for this endpoint.Sending Authorization: Bearer sec_... currently does not create a transaction successfully because the controller still looks up the key as a public key.
When a transaction is initialized, Basqet sends a POST request to your webhook URL. The payload follows this format:
JSON
{
"event": "payment.initiated",
"data": {
"transaction": {
"reference": "bq_B09BMmXXgWMzRSmon",
"merchant_name": "Appstate",
"payment_currency": null,
"payment_currency_name": null,
"payment_currency_slug": null,
"status": "INITIATED",
"customer_email": "[email protected] ",
"customer_name": "tunde",
"payment_amount": null,
"amount_paid": null,
"description": null,
"is_live": false,
"created_at": "2022-07-14T20:17:11.000Z",
"meta": {}
}
}
}
Field Value Action Initiate Transaction Method POSTPath /v1/transaction/:transaction_id/payAuth Requirement Secret key
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.
Convert an INITIATED transaction into a live payment request.
Transition the transaction to the PENDING state.
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.
Name Type Required Description transaction_idstring Yes Unique identifier of the transaction.
Name Type Required Default Allowed Values Description currency_idstring Yes — Tether: 3, Bitcoin: 4, Quidax Token: 5, Ethereum: 6, Litecoin: 7 Unique identifier of the cryptocurrency the customer wants to pay with. refund_addressstring No — — Optional refund address stored in the transaction metadata.
Name Type Required Default Description Authorizationstring Yes — Bearer token in the form Bearer YOUR_SECRET_KEY. Content-Typestring Yes application/jsonMust be application/json.
Bash
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"
}'
Field Type Nullable Description statusstring No Status of the API request. dataobject No Container for the transaction details. data.idstring No Unique internal identifier for the transaction. data.referencestring No Transaction reference for the merchant. data.descriptionstring Yes Transaction description provided during initialization. data.initialized_amountnumber No Original fiat amount. data.initialized_currencystring No Fiat currency slug, e.g. USD or NGN. data.payment_amountnumber No Crypto amount to be sent. data.amount_paidnumber Yes null until payment is confirmed on-chain.data.payment_currencynumber/string Yes Selected crypto currency or internal currency ID, depending on response format. data.payment_addressstring No Destination wallet address. data.statusstring No Current transaction status. Becomes PENDING after successful initiation. data.qrCodestring No Base64 data URL of the QR code for the payment_address. data.is_liveboolean Yes Indicates whether the transaction is in live or test mode. data.merchantobject No Merchant account information. data.merchant.idinteger No Unique identifier for the merchant. data.merchant.namestring No Registered merchant name. metaobject No Additional metadata.
JSON
{
"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": {}
}
HTTP Code Message Resolution 400Missing or invalid payload fields Ensure currency_id is present and numeric, and that the refund_address format is valid. 404Varies Occurs if the transaction_id is invalid, the selected currency_id is not supported, or the merchant’s subaccount/processor is not configured. 422The transaction is not initiated Verify that the transaction is still in the INITIATED state. This can also occur if the merchant account is inactive. 500Internal Server Error An unexpected server-side error occurred. Retry the request or contact support. 503Varies An upstream error occurred while generating the price quote or wallet address. Retry the request.
When a transaction has been initiated and is awaiting payment, Basqet sends a POST request to your webhook URL.
JSON
{
"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": {}
}
}
}
When a transaction is successfully completed and the merchant has received payment, Basqet sends a POST request to your webhook URL.
JSON
{
"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": {}
}
}
}
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.
JSON
{
"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": {}
}
}
}
