Payment Links API

Payment Links API Integration

The Payment Links API allows you to programmatically create and manage payment links. This is ideal for merchants who want to generate links on demand from their own systems instead of creating them manually through the dashboard.

Payment links are reusable. A payment link can be opened and paid through multiple times, whether it is static or dynamic. Each time a customer uses a payment link, Basqet creates a new checkout session, or transaction, for that use. The link itself remains active and can be shared again.

If you need a one-time payment that expires after a single use, use the Transactions API to initialize a transaction directly instead.

A payment link is a Basqet-hosted checkout page that your customers can open to complete a payment. Links can be:

Static: A fixed amount is set when the link is created.
Dynamic: The customer enters the amount at checkout.

Create Payment Link

API Details

Field	Value
Action	Create Payment Link
Method	`POST`
Path	`/v1/payment-links`
Auth Requirement	Secret key

Business Summary

This endpoint creates a new payment link that can be shared with customers. Once created, the link generates a unique Basqet-hosted checkout URL your customers can use to complete a crypto payment.

You can use this API to:

Programmatically generate payment links for invoices, orders, or recurring billing.
Create fixed-price static links for specific products or dynamic links where the customer sets the amount.
Attach custom metadata to links for your internal tracking.

Request Parameters

Request Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Bearer token in the form `Bearer sec_...`, using your secret key.
`Content-Type`	string	Yes	Must be `application/json`.

Body Parameters

Name	Type	Required	Default	Allowed Values	Description
`title`	string	Yes	—	2–100 characters	Display name for the payment link.
`link_type`	string	Yes	—	`static`, `dynamic`	`static` requires a fixed `amount`. `dynamic` lets the customer enter the amount at checkout.
`currency`	string	Yes	—	`USD`, `NGN`, `GBP`, `EUR`	Fiat currency the payment is priced in. Must be uppercase.
`amount`	string	Conditional	—	Numeric value greater than `0`	Required when `link_type` is `static`. Omit or set to `null` for dynamic links.
`description`	string	No	`null`	Maximum 255 characters	Optional description for the link.
`metadata`	object	No	`null`	Any JSON object	Custom data to attach to the link. Returned as-is in responses.
`pass_fee_to_customer`	boolean	No	`false`	`true`, `false`	When `true`, the Basqet processing fee is passed to the customer.
`pass_settlement_fee_to_customer`	boolean	No	`false`	`true`, `false`	When `true`, the settlement fee is passed to the customer.

Request Examples

cURL — Static Link

curl --request POST \
  --url https://api.basqet.com/v1/payment-links \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Invoice #1024",
    "link_type": "static",
    "currency": "USD",
    "amount": "150.00",
    "description": "Payment for design services",
    "metadata": {
      "order_id": "order_1024",
      "customer_tier": "premium"
    }
  }'

cURL — Dynamic Link

curl --request POST \
  --url https://api.basqet.com/v1/payment-links \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Open Donation",
    "link_type": "dynamic",
    "currency": "USD"
  }'

Response Schema

Field	Type	Nullable	Description
`message`	string	No	Always `Payment Link created` on success.
`id`	string	No	Unique identifier for the payment link, e.g. `bq_pl_...`.
`title`	string	No	Payment link title.
`link_type`	string	No	Either `static` or `dynamic`.
`currency`	string	No	Fiat currency code, e.g. `USD` or `NGN`.
`amount`	number/null	Yes	Fixed payment amount for static links. `null` for dynamic links.
`payment_url`	string	No	Shareable Basqet-hosted checkout URL for this payment link.
`metadata`	object/null	Yes	Echo of the metadata passed in, or `null` when omitted.
`created_at`	string	No	ISO 8601 timestamp of link creation.
`last_used`	string/null	Yes	ISO 8601 timestamp of the most recent use. `null` if unused.
`deleted_at`	string/null	Yes	ISO 8601 timestamp of deletion. `null` if active.

Sample Response

{
  "message": "Payment Link created",
  "id": "bq_pl_aBcDeFgHiJkLmNo",
  "title": "Invoice #1024",
  "link_type": "static",
  "currency": "USD",
  "amount": 150.0,
  "payment_url": "https://pay.basqet.com/pl_aBcDeFgHiJkLmNo",
  "metadata": {
    "order_id": "order_1024",
    "customer_tier": "premium"
  },
  "created_at": "2026-04-22T10:30:00.000Z",
  "last_used": null,
  "deleted_at": null
}

Error Reference

HTTP Code	Error Code	Resolution
`400`	`missing_required_field`	Ensure `title`, `link_type`, and `currency` are all present in the body.
`400`	`invalid_link_type`	`link_type` must be exactly `static` or `dynamic`.
`400`	`invalid_currency`	Verify that the currency code is supported.
`400`	`missing_amount`	`amount` is required when `link_type` is `static`.
`400`	`invalid_amount`	`amount` must be a number greater than `0`.
`400`	`invalid_metadata`	`metadata` must be a valid JSON object.
`404`	`merchant_user_not_found`	No merchant user was found for the provided secret key.
`422`	Varies based on KYC status	The merchant must complete KYB verification before creating live-mode payment links.

List Payment Links

API Details

Field	Value
Action	List Payment Links
Method	`GET`
Path	`/v1/payment-links`
Auth Requirement	Secret key

Business Summary

Returns a paginated list of payment links for your merchant account. By default, only active, non-deleted links are returned. Use the status parameter to retrieve archived links.

Request Parameters

Request Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Bearer token in the form `Bearer sec_...`, using your secret key.

Query Parameters

Name	Type	Required	Default	Allowed Values	Description
`offset`	number	No	`0`	Integer greater than or equal to `0`	Number of records to skip.
`limit`	number	No	`10`	Integer from `1` to `100`	Number of records to return.
`order`	string	No	`desc`	`asc`, `desc`	Sort order by creation date.
`from`	string	No	—	Date string in `YYYY-MM-DD` format	Filter links created on or after this date.
`to`	string	No	—	Date string in `YYYY-MM-DD` format	Filter links created on or before this date.
`search_term`	string	No	—	—	Search links by title or currency code.
`status`	string	No	`active`	`active`, `archived`, `all`	Filter by link status. `archived` returns deleted links.

Request Example

cURL

curl --request GET \
  --url 'https://api.basqet.com/v1/payment-links?limit=20&order=desc&status=active' \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx'

Response Schema

Field	Type	Nullable	Description
`data`	array	No	Array of payment link objects.
`meta.limit`	number	No	Limit applied to the request.
`meta.count`	number	No	Total number of matching payment links.
`meta.hasNext`	boolean	No	`true` if more records exist beyond this page.

Sample Response

{
  "data": [
    {
      "id": "bq_pl_aBcDeFgHiJkLmNo",
      "title": "Invoice #1024",
      "link_type": "static",
      "currency": "USD",
      "amount": 150.0,
      "payment_url": "https://pay.basqet.com/pl_aBcDeFgHiJkLmNo",
      "metadata": null,
      "created_at": "2026-04-22T10:30:00.000Z",
      "last_used": null,
      "deleted_at": null
    }
  ],
  "meta": {
    "limit": 20,
    "count": 1,
    "hasNext": false
  }
}

Get Payment Link

API Details

Field	Value
Action	Get Payment Link
Method	`GET`
Path	`/v1/payment-links/:id`
Auth Requirement	Secret key

Business Summary

Retrieves the details of a single payment link by its ID.

Request Parameters

Request Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Bearer token in the form `Bearer sec_...`, using your secret key.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Unique ID of the payment link, e.g. `bq_pl_...`.

Request Example

cURL

curl --request GET \
  --url https://api.basqet.com/v1/payment-links/bq_pl_aBcDeFgHiJkLmNo \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx'

Sample Response

{
  "id": "bq_pl_aBcDeFgHiJkLmNo",
  "title": "Invoice #1024",
  "link_type": "static",
  "currency": "USD",
  "amount": 150.0,
  "payment_url": "https://pay.basqet.com/pl_aBcDeFgHiJkLmNo",
  "metadata": null,
  "created_at": "2026-04-22T10:30:00.000Z",
  "last_used": null,
  "deleted_at": null
}

Error Reference

HTTP Code	Error Code	Resolution
`404`	`link_not_found`	Verify that the `id` is correct and belongs to your account.

Update Payment Link

API Details

Field	Value
Action	Update Payment Link
Method	`PATCH`
Path	`/v1/payment-links/:id`
Auth Requirement	Secret key

Business Summary

Updates one or more fields on an existing payment link. At least one field must be provided.

Request Parameters

Request Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Bearer token in the form `Bearer sec_...`, using your secret key.
`Content-Type`	string	Yes	Must be `application/json`.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Unique ID of the payment link to update.

Body Parameters

All fields are optional, but at least one field must be provided.

Name	Type	Required	Allowed Values	Description
`title`	string	No	2–100 characters	Updated display name for the payment link.
`link_type`	string	No	`static`, `dynamic`	Changing to `static` requires an `amount`. Changing to `dynamic` clears any existing amount.
`currency`	string	No	`USD`, `NGN`, `GBP`, `EUR`	Updated fiat currency for the link.
`amount`	string/number/null	No	Numeric value greater than `0`	Required when changing `link_type` to `static`. Set to `null` with `dynamic`.
`description`	string/null	No	Maximum 255 characters	Updated description for the link.
`metadata`	object/null	No	Any JSON object	Replaces the existing metadata. Set to `null` to clear.
`pass_fee_to_customer`	boolean	No	`true`, `false`	Updates whether the Basqet processing fee is passed to the customer.
`pass_settlement_fee_to_customer`	boolean	No	`true`, `false`	Updates whether the settlement fee is passed to the customer.

Request Example

cURL

curl --request PATCH \
  --url https://api.basqet.com/v1/payment-links/bq_pl_aBcDeFgHiJkLmNo \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Invoice #1024 (Updated)",
    "amount": "200.00"
  }'

Sample Response

{
  "id": "bq_pl_aBcDeFgHiJkLmNo",
  "title": "Invoice #1024 (Updated)",
  "link_type": "static",
  "currency": "USD",
  "amount": 200.0,
  "payment_url": "https://pay.basqet.com/pl_aBcDeFgHiJkLmNo",
  "metadata": null,
  "created_at": "2026-04-22T10:30:00.000Z",
  "last_used": null,
  "deleted_at": null
}

Error Reference

HTTP Code	Error Code	Resolution
`400`	`missing_amount`	`amount` must be provided when changing `link_type` to `static`.
`400`	`invalid_amount`	`amount` must be greater than `0`.
`404`	`link_not_found`	Verify that the `id` is correct and belongs to your merchant account.

Delete Payment Link

API Details

Field	Value
Action	Delete Payment Link
Method	`DELETE`
Path	`/v1/payment-links/:id`
Auth Requirement	Secret key

Business Summary

Soft-deletes a payment link. Deleted links are no longer accessible to customers and are excluded from your default list view. This action cannot be undone via the API.

Request Parameters

Request Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Bearer token in the form `Bearer sec_...`, using your secret key.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Unique ID of the payment link to delete.

Request Example

cURL

curl --request DELETE \
  --url https://api.basqet.com/v1/payment-links/bq_pl_aBcDeFgHiJkLmNo \
  --header 'Authorization: Bearer sec_live_xxxxxxxxxxxxx'

Sample Response

{
  "id": "bq_pl_aBcDeFgHiJkLmNo",
  "status": "deleted",
  "deleted_at": "2026-04-22T14:00:00.000Z"
}

Error Reference

HTTP Code	Error Code	Resolution
`404`	`link_not_found`	Verify that the `id` is correct and belongs to your merchant account.
`409`	`link_already_deleted`	The payment link is already deleted.

Notes

All Merchant API endpoints require a secret key in the form sec_... in the Authorization header. Public keys are not accepted.
Payment links in live mode require your merchant account to have completed KYB verification.
Deleting a payment link is a soft delete. The record is retained, but the link becomes inactive.
Use status=archived in the List endpoint to retrieve deleted links.
The payment_url returned in responses is the shareable link to send to your customers. When a customer opens this URL, they are taken through the Basqet-hosted checkout flow.
For merchants using payment links with the Initialize Transaction API, pass the payment link’s url_slug, prefixed with pl_, as the payment_link parameter when initializing a transaction. This associates the transaction with the link’s configuration.