Initialize Transaction

Direct API Integration

There are two steps involved in creating a transaction via API on Basqet:

Initialize the transaction
Initiate the transaction

1. Initialize Transaction API

API Details

Field	Value
Action	Initialize Transaction
Method	`POST`
Path	`/v1/transaction`
Auth Requirement	Public key or private key

Business Summary

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.

Request Parameters

Body Parameters

Name	Type	Required	Default	Allowed Values	Description
`customer`	object	Yes	—	—	Customer’s details for the transaction.
`customer.name`	string	No	`null`	—	Customer’s full name.
`customer.email`	string	Yes	—	Any valid email, e.g. `[email protected]`	Customer’s email address.
`public_key`	string	Conditional	—	Prefixed with `pub_`	Required when the public key is not sent in the `Authorization` header.
`payment_link`	string	Conditional	—	Prefixed with `pl_`	Payment link slug. Cannot be sent alongside `public_key`.
`currency`	string	Yes	`NGN`	`USD`, `NGN`	Fiat currency slug for the transaction.
`amount`	string	Yes	—	Numeric string	Transaction amount to be paid in the specified currency, e.g. `"1500"`.
`description`	string	No	`null`	—	Transaction description.
`meta`	object	No	`null`	—	Custom data to pass with the transaction. Returned in the response.

Request Headers

Name	Type	Required	Description
`Authorization`	string	Conditional	Bearer token in the form `Bearer pub_...`. Optional if `public_key` is passed in the request body.
`Content-Type`	string	Yes	Must be `application/json`.

Request Example

cURL

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"
    }
  }'

Response Schema

Field	Type	Nullable	Description
`status`	string	No	Response status. Always `success` for `2xx` responses.
`data`	object	No	Container for the transaction details.
`data.id`	string	No	Unique internal identifier for the transaction.
`data.reference`	string	No	Transaction reference for the merchant.
`data.amount_paid`	number	Yes	Actual amount received. Remains `null` until payment is made.
`data.status`	string	No	Current transaction state. Initial value is `INITIATED`.
`data.description`	string	Yes	Transaction description provided. `null` if omitted.
`data.initialized_amount`	number	No	Fiat amount specified during the request.
`data.payment_amount`	number	Yes	Crypto amount to be paid. `null` until payment is initiated.
`data.payment_address`	string	Yes	Destination crypto payment address. `null` until payment is initiated.
`data.payment_currency`	number	Yes	Internal currency ID for the selected crypto currency. `null` until payment is initiated.
`data.initialized_currency`	number	No	Internal currency ID for the fiat currency used to initialize the transaction.
`data.is_live`	boolean	No	Indicates whether the transaction is in live mode.
`data.merchant`	object	No	Merchant account information.
`data.merchant.id`	number	No	Unique internal identifier for the merchant.
`data.merchant.name`	string	No	Merchant display name.
`meta`	object	No	Echo of the request `meta` payload, or `{}` when omitted.

Sample Response

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

Error Reference

HTTP Code	Message	Resolution
`400`	Validation 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.
`404`	Invalid Public Key	Verify that the `public_key` or `payment_link` is correct, the merchant account is active, and the fiat currency slug is supported.
`422`	Varies based on KYC status	Ensure the merchant has completed the required KYB verification for live-mode transactions before attempting to initialize.
`500`	Internal Server Error	An unexpected error occurred. Retry the request or contact Basqet support.

Notes

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.

Webhook Payload

When a transaction is initialized, Basqet sends a POST request to your webhook URL. The payload follows this format:

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

2. Initiate Transaction API

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.
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.

Request Parameters

Path Parameters

Name	Type	Required	Description
`transaction_id`	string	Yes	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`	Unique identifier of the cryptocurrency the customer wants to pay with.
`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`	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	Container for 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.
`meta`	object	No	Additional metadata.

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.

{
  "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.

{
  "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.

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

Direct API Integration

1. Initialize Transaction API

API Details

Business Summary

Request Parameters

Body Parameters

Request Headers

Request Example

cURL

Response Schema

Sample Response

Error Reference

Notes

Webhook Payload

2. Initiate Transaction API

API Details

Business Summary

Request Parameters

Path Parameters

Body Parameters

Request Headers

Request Example

cURL

Response Schema

Sample Response

Error Reference

Webhook Payloads

Payment Pending (payment.pending)

Payment Completed (payment.received)

Payment Abandoned (payment.abandoned)

Payment Pending (`payment.pending`)

Payment Completed (`payment.received`)

Payment Abandoned (`payment.abandoned`)