Skip to content

Merchant API - Payments ​

Overview ​

The Merchant API Payments endpoints allow you to create, manage, and retrieve payment links for accepting cryptocurrency payments. All endpoints require Merchant API Key authentication with an Ed25519 (EdDSA) request signature (RSA-PSS accepted for legacy keys). The signed path must include the /api/v1 prefix; see Authentication.

All responses except the catalog are wrapped as {"message": string, "data": …}; error responses carry only message (plus error/code for authentication errors).

Base URL: https://sandboxapi.bitxpay.com/api/v1

Authentication: Merchant API Key (asymmetric Ed25519 / EdDSA signature)


Supported Currencies ​

Payment links accept any code returned by the Get Currencies endpoint. The list is environment-specific and changes over time, so fetch it rather than hard-coding codes. Use currency_type=fiat or currency_type=crypto to filter records. For engine-backed checkout, also check the catalog: a currency record alone does not guarantee an offerable payment route.

One record per currency and network

The currencies endpoint returns one record per currency record in the catalogue, so the same code appears several times when a token exists on several networks (for example a token supported on several networks). Any of them is valid as the currency of a payment link; network selection happens at checkout. Deduplicate by code if you present the list to users.

Currency Validation ​

When creating a payment link:

  1. Currency code is required - Validation failed: currency is required otherwise
  2. Case-insensitive - usdt, Usdt and USDT are all accepted and stored as USDT
  3. Length: 3-10 characters
  4. Must exist in the currencies list - unknown codes are rejected with invalid currency code 'XYZ': currency not found
  5. Network selection - happens automatically at checkout

Examples: USDT, usdt, and ETH are accepted when present in the currency catalog. Unknown codes such as XYZ return HTTP 400.


Endpoints ​

1. Get Currencies ​

Retrieve the list of currency records a payment link can be denominated in.

Request ​

GET /payment_links/currencies

Authentication ​

X-API-Key: btxm_9b451fa04a2e
X-API-Signature: <base64_encoded_ed25519_signature>
X-API-Timestamp: 2026-01-31T12:00:00Z
Accept: application/json

Optional query parameter: currency_type=fiat or currency_type=crypto. Omit it for the full currency list. Other non-empty values return HTTP 400 with Invalid currency_type. Must be 'fiat' or 'crypto'.

Response (200 OK) ​

json
{
  "message": "Currencies retrieved successfully",
  "data": [
    {
      "id": "25193059-4008-4522-8eb4-3c2583ee1ebf",
      "code": "USDT",
      "name": "Tether USD"
    },
    {
      "id": "eff091bc-223e-4326-b64f-140625b3f008",
      "code": "USDC",
      "name": "USD Coin"
    },
    {
      "id": "a93e5a54-9725-4af1-85be-c389ce485017",
      "code": "ETH",
      "name": "Ethereum"
    },
    {
      "id": "0c2b4a1e-5f6d-4a7b-9c8d-1e2f3a4b5c6d",
      "code": "USDT",
      "name": "Tether USD"
    }
  ]
}

Response Fields:

FieldTypeDescription
idstring (UUID)Unique identifier for the currency record
codestringCurrency code (use this when creating payment links)
namestringFull currency name

Multiple Networks

Some currencies like USDT and ETH are available on multiple networks (Ethereum, BSC, Polygon, etc.). This endpoint returns one entry per currency record, so a code can appear several times; network selection is handled automatically at checkout. When creating a payment link, you only need to specify the code.

Error Responses ​

StatusErrorDescription
401UnauthorizedMissing or invalid API key/signature
500Internal Server ErrorServer error

Example Request ​

bash
curl --location 'https://sandboxapi.bitxpay.com/api/v1/payment_links/currencies' \
  --header 'X-API-Key: btxm_9b451fa04a2e' \
  --header 'X-API-Signature: <signature>' \
  --header 'X-API-Timestamp: 2026-01-31T12:00:00Z' \
  --header 'Accept: application/json'

Creates a new payment link for accepting payments.

Request ​

POST /payment_links

Authentication ​

X-API-Key: btxm_9b451fa04a2e
X-API-Signature: <base64_encoded_ed25519_signature>
X-API-Timestamp: 2026-01-31T12:00:00Z
Content-Type: application/json

Request Body ​

FieldTypeRequiredDescriptionExample
payment_namestringYesPayment link name (1-100 chars)"Invoice #12345"
amountfloatYesPayment amount (must be > 0)100.50
currencystringYesCurrency code (3-10 chars, case-insensitive). Must be a code from the currencies list"USDT"
descriptionstringNoPayment description (max 1000 chars)"Payment for Order #12345"
expires_attimestampNoRFC 3339 expiry; must be after starts_at. Defaults to 24 hours after the start"2026-02-01T12:00:00Z"
max_usesintegerNoMaximum uses (must be > 0; default: 1)1
customer_idstringNoMerchant's customer ID (1-100 chars)"AB-001"
customer_namestringNoCustomer name (1-100 chars)"John Doe"
customer_emailstringNoCustomer email (valid email)"john@example.com"
product_namestringNoProduct name (1-200 chars)"Course A"
product_descriptionstringNoProduct description (max 1000 chars)"Art Course for Beginners"
cartobjectNoShopping cart details with items, subtotal, tax, and totalSee cart object below
order_idstringNoMerchant's order ID (1–200 chars; auto-generated if not provided)"ORD-20260226-A1B2C3"
auto_fillbooleanNoStored checkout auto-fill flag (default: true). Omitted customer/order IDs are generated even when falsetrue
starts_attimestampNoTime from which the link can be paid (ISO 8601, default: now)"2026-02-01T00:00:00Z"
is_testbooleanNoCreate a test payment link (default: false)false
success_urlstringNoRedirect URL after success (valid URL, max 500 chars)"https://www.success.io/success.html"
cancel_urlstringNoRedirect URL after cancellation (valid URL, max 500 chars)"https://www.failure.io/cancel.html"
webhook_metadataobjectNoMetadata included in payment_link.created; not automatically propagated to later payment events

The cart is stored as an arbitrary JSON object; the fields below are an application convention rather than a nested server-validated schema.

Cart Object Example:

json
{
  "cart": {
    "items": [
      {
        "name": "Course A",
        "product_id": "prod_001",
        "quantity": 1,
        "unit_price": 100.50,
        "total": 100.50
      }
    ],
    "shipping": 0,
    "subtotal": 100.50,
    "tax": 0,
    "total": 100.50
  }
}
FieldTypeRequiredDescription
itemsarrayYesArray of cart items
items[].namestringYesItem name
items[].product_idstringNoYour internal product identifier
items[].quantityintegerYesItem quantity (must be > 0)
items[].unit_pricefloatYesPrice per single unit
items[].totalfloatYesLine total (quantity × unit_price)
subtotalfloatYesSubtotal amount
shippingfloatNoShipping cost (default: 0)
taxfloatYesTax amount
totalfloatYesTotal amount (should match payment amount)

Response Variations

The optional receipt_number identifies a payment receipt when available. The core fields (id, payment_name, amount, currency, payment_url, payment_status, payment_type, source, starts_at, expires_at, max_uses, current_uses, is_active, is_test, customer_id, order_id, auto_fill, created_at) are always returned. Optional fields (description, customer_name, customer_email, product_name, product_description, cart, success_url, cancel_url, webhook_metadata) are returned only when you provided them. customer_id and order_id are auto-generated when omitted.

Request Examples ​

Minimal Request:

json
{
  "payment_name": "Invoice #12345",
  "amount": 100.50,
  "currency": "USDT"
}

Full Request:

json
{
  "payment_name": "Invoice #12345",
  "description": "Payment for Order #12345",
  "amount": 100.50,
  "currency": "USDT",
  "expires_at": "2026-02-01T12:00:00Z",
  "max_uses": 1,
  "customer_id": "AB-001",
  "customer_name": "John Doe",
  "customer_email": "john@example.com",
  "product_name": "Course A",
  "product_description": "Art Course for Beginners",
  "cart": {
    "items": [
      {
        "name": "Course A",
        "product_id": "prod_001",
        "quantity": 1,
        "unit_price": 100.50,
        "total": 100.50
      }
    ],
    "shipping": 0,
    "subtotal": 100.50,
    "tax": 0,
    "total": 100.50
  },
  "checkout_mode": "redirect",
  "origin": "https://yoursite.com",
  "success_url": "https://www.success.io/success.html",
  "cancel_url": "https://www.failure.io/cancel.html",
  "webhook_metadata": {
    "merchant_id": "M-10001",
    "demo": true
  }
}

Response (201 Created) ​

The response structure varies based on the request parameters provided.

Minimal Response (when only required fields are provided):

json
{
  "message": "Payment link created successfully",
  "data": {
    "id": "f7a9ff0a-678f-45ba-a918-dcafc5d479e9",
    "payment_name": "Invoice #12345",
    "amount": 100.5,
    "currency": "USDT",
    "payment_url": "sandboxpay.bitxpay.com/payment_link?payment_id=f7a9ff0a-678f-45ba-a918-dcafc5d479e9",
    "payment_status": "processing",
    "payment_type": "one_time",
    "source": "payment_link_api",
    "starts_at": "2026-03-12T15:21:12.988351Z",
    "expires_at": "2026-03-13T15:21:12.988351519Z",
    "max_uses": 1,
    "current_uses": 0,
    "is_active": true,
    "is_test": false,
    "customer_id": "CUST-20260312-96D009D4",
    "order_id": "ORD-20260312-E29917C9",
    "auto_fill": true,
    "created_at": "2026-03-12T15:21:12.988356Z"
  }
}

Full Response (when optional fields like cart, customer details are provided):

json
{
  "message": "Payment link created successfully",
  "data": {
    "id": "d26ffcc8-f013-464e-893a-d71ee1e849ae",
    "payment_name": "Invoice #12345",
    "description": "Payment for Order #12345",
    "amount": 100.5,
    "currency": "USDT",
    "payment_url": "sandboxpay.bitxpay.com/payment_link?payment_id=d26ffcc8-f013-464e-893a-d71ee1e849ae",
    "payment_status": "processing",
    "payment_type": "one_time",
    "source": "payment_link_api",
    "starts_at": "2026-07-05T07:30:05.703759Z",
    "expires_at": "2026-03-13T15:23:32.084432Z",
    "max_uses": 1,
    "current_uses": 0,
    "is_active": true,
    "is_test": false,
    "customer_id": "AB-001",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "product_name": "Course A",
    "product_description": "Art Course for Beginners",
    "cart": {
      "items": [
        {
          "name": "Course A",
          "product_id": "prod_001",
          "quantity": 1,
          "unit_price": 100.5,
          "total": 100.5
        }
      ],
      "shipping": 0,
      "subtotal": 100.5,
      "tax": 0,
      "total": 100.5
    },
    "order_id": "ORD-20260226-A1B2C3",
    "auto_fill": true,
    "success_url": "https://www.success.io/success.html",
    "cancel_url": "https://www.failure.io/cancel.html",
    "webhook_metadata": {
      "merchant_id": "M-10001",
      "demo": true
    },
    "created_at": "2026-07-05T07:30:05.703759Z"
  }
}

Response Fields:

FieldTypeDescription
idstring (UUID)Unique payment link identifier
payment_namestringPayment link name
descriptionstringPayment description (if provided)
amountfloatPayment amount
currencystringCurrency code
payment_urlstringCheckout URL built from deployment configuration. Add https:// only if the returned URL has no scheme
payment_statusstringprocessing on creation; later completed, expired or cancelled
payment_typestringPayment type: one_time, recurring
sourcestringOrigin of the payment link: payment_link_api
is_testbooleanWhether this is a test payment
starts_attimestampTime from which the link can be paid (creation time unless provided)
expires_attimestampExpiration timestamp (24 hours after creation unless provided)
max_usesintegerMaximum number of uses allowed
current_usesintegerCurrent number of uses
is_activebooleanWhether the payment link is active
customer_idstringCustomer ID (auto-generated or provided)
customer_namestringCustomer name (if provided)
customer_emailstringCustomer email (if provided)
product_namestringProduct name (if provided)
product_descriptionstringProduct description (if provided)
cartobjectShopping cart details (if provided)
order_idstringOrder ID (auto-generated or provided)
auto_fillbooleanAuto-fill setting
success_urlstringSuccess redirect URL (if provided)
cancel_urlstringCancel redirect URL (if provided)
webhook_metadataobjectCustom webhook metadata (if provided)
created_attimestampCreation timestamp

Top-level response fields (alongside data):

FieldTypeDescription
messagestringHuman-readable result message

Error Responses ​

StatusErrorDescription
400Bad RequestInvalid request payload, validation failed, or unsupported currency
401UnauthorizedMissing or invalid API key/signature
409ConflictDuplicate payment link or resource conflict
500Internal Server ErrorServer error

Common 400 Errors (body is {"message": "..."}):

  • Invalid request payload - body parsing failed: check the sent Content-Type: application/json, JSON syntax, field types, and optional date formats. See Postman troubleshooting
  • Validation failed: currency is required - missing currency
  • Validation failed: amount is required - missing, zero or negative amount
  • Validation failed: payment_name must be at most 100 characters
  • Validation failed: customer_email must be a valid email address
  • invalid currency code 'XYZ': currency not found - code not in the currencies list

Retrieve all payment links for the authenticated merchant with filtering, searching, and pagination.

Request ​

GET /payment_links?page=1&limit=20&status=pending&currency=USDT&sort_by=created_at&sort_order=desc

Query Parameters ​

ParameterTypeDefaultDescriptionExample
pageinteger1Page number (min: 1; out-of-range values fall back to 1)1
limitinteger20Items per page (max: 100; out-of-range values fall back to 20)20
statusstring-Filter by status: pending, completed, expired, cancelled (processing is not accepted here and returns 400)"pending"
is_activeboolean-Filter by active statustrue
currencystring-Filter by currency (3-10 chars)"USDT"
min_amountfloat-Minimum amount filter (must be > 0)10.00
max_amountfloat-Maximum amount filter (must be > 0)1000.00
created_fromtimestamp-Filter from date (ISO 8601)"2026-01-01T00:00:00Z"
created_totimestamp-Filter to date (ISO 8601)"2026-01-31T23:59:59Z"
searchstring-Search in name and description (max 100 chars)"Invoice"
sort_bystringcreated_atSort field: created_at, updated_at, amount, name"created_at"
sort_orderstringdescSort order: asc, desc"desc"

Response (200 OK) ​

The response includes an array of payment links with varying detail levels based on how they were created.

json
{
  "message": "Payment links retrieved successfully",
  "data": {
    "data": [
      {
        "id": "fce13397-afb5-4093-84c0-b64178691dbd",
        "payment_name": "Invoice #12345",
        "description": "Payment for Order #12345",
        "amount": 100.5,
        "currency": "USDT",
        "payment_url": "sandboxpay.bitxpay.com/payment_link?payment_id=fce13397-afb5-4093-84c0-b64178691dbd",
        "payment_status": "expired",
        "payment_type": "one_time",
        "source": "payment_link_api",
        "starts_at": "2026-03-12T15:23:32.084432Z",
        "expires_at": "2026-03-13T15:23:32.084432Z",
        "max_uses": 1,
        "current_uses": 0,
        "is_active": true,
        "is_expired": true,
        "is_test": false,
        "customer_id": "AB-001",
        "customer_name": "John Doe",
        "customer_email": "john@example.com",
        "product_name": "Course A",
        "product_description": "Art Course for Beginners",
        "cart": {
          "items": [
            {
              "name": "Course A",
              "product_id": "prod_001",
              "quantity": 1,
              "unit_price": 100.5,
              "total": 100.5
            }
          ],
          "shipping": 0,
          "subtotal": 100.5,
          "tax": 0,
          "total": 100.5
        },
        "order_id": "ORD-20260226-A1B2C3",
        "auto_fill": true,
        "success_url": "https://www.success.io/success.html",
        "cancel_url": "https://www.failure.io/cancel.html",
        "webhook_metadata": {
          "merchant_id": "M-10001",
          "note": "Test payment",
          "source": "payment_link"
        },
        "created_at": "2026-03-12T15:23:32.084432Z"
      },
      {
        "id": "f7a9ff0a-678f-45ba-a918-dcafc5d479e9",
        "payment_name": "Invoice #12345",
        "amount": 100.5,
        "currency": "USDT",
        "payment_url": "sandboxpay.bitxpay.com/payment_link?payment_id=f7a9ff0a-678f-45ba-a918-dcafc5d479e9",
        "payment_status": "processing",
        "payment_type": "one_time",
        "source": "payment_link_api",
        "starts_at": "2026-03-12T15:21:12.988351Z",
        "expires_at": "2026-03-13T15:21:12.988351Z",
        "max_uses": 1,
        "current_uses": 0,
        "is_active": true,
        "is_expired": false,
        "is_test": false,
        "customer_id": "CUST-20260312-96D009D4",
        "order_id": "ORD-20260312-E29917C9",
        "auto_fill": true,
        "created_at": "2026-03-12T15:21:12.988356Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 20,
      "total_pages": 2,
      "total_records": 31,
      "has_next_page": true,
      "has_prev_page": false
    },
    "filters": {
      "sort_by": "created_at",
      "sort_order": "desc"
    }
  }
}

filters echoes every filter that was applied (status, is_active, currency, min_amount, max_amount, created_from, created_to, search, sort_by, sort_order). Items have the same shape as the create response plus is_expired. Soft-deleted links are not listed.

Response Variations

Payment links in the list may have different fields depending on how they were created:

  • Links created with minimal data will only show core fields
  • Links created with full details (cart, customer info) will include all those fields

Error Responses ​

StatusErrorDescription
400Bad RequestInvalid filter value, e.g. Validation failed: Status must be one of: pending, completed, expired, cancelled
401UnauthorizedMissing or invalid API key/signature
500Internal Server ErrorServer error

Retrieve a specific payment link with all related details including payers, transactions, and summary statistics.

Request ​

GET /payment_links/{id}

Path Parameters ​

ParameterTypeDescriptionExample
idstringPayment Link ID (UUID)"22222222-2222-2222-2222-222222222222"

Response (200 OK) ​

The response structure varies based on how the payment link was created.

Full Response (payment link created with complete details):

json
{
  "message": "Payment link retrieved successfully",
  "data": {
    "id": "fce13397-afb5-4093-84c0-b64178691dbd",
    "payment_name": "Invoice #12345",
    "description": "Payment for Order #12345",
    "amount": 100.5,
    "currency": "USDT",
    "payment_url": "sandboxpay.bitxpay.com/payment_link?payment_id=fce13397-afb5-4093-84c0-b64178691dbd",
    "payment_status": "expired",
    "payment_type": "one_time",
    "source": "payment_link_api",
    "starts_at": "2026-03-12T15:23:32.084432Z",
    "expires_at": "2026-03-13T15:23:32.084432Z",
    "max_uses": 1,
    "current_uses": 0,
    "is_active": true,
    "is_expired": true,
    "is_test": false,
    "customer_id": "AB-001",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "product_name": "Course A",
    "product_description": "Art Course for Beginners",
    "cart": {
      "items": [
        {
          "name": "Course A",
          "product_id": "prod_001",
          "quantity": 1,
          "unit_price": 100.5,
          "total": 100.5
        }
      ],
      "shipping": 0,
      "subtotal": 100.5,
      "tax": 0,
      "total": 100.5
    },
    "order_id": "ORD-20260226-A1B2C3",
    "auto_fill": true,
    "success_url": "https://www.success.io/success.html",
    "cancel_url": "https://www.failure.io/cancel.html",
    "webhook_metadata": {
      "merchant_id": "M-10001",
      "note": "Test payment",
      "source": "payment_link"
    },
    "summary": {
      "total_payers": 0,
      "total_transactions": 0,
      "total_amount_received": 0,
      "total_amount_received_crypto": 0,
      "pending_transactions": 0,
      "completed_transactions": 0,
      "failed_transactions": 0
    },
    "created_at": "2026-03-12T15:23:32.084432Z"
  }
}

Minimal Response (payment link created with only required fields):

json
{
  "message": "Payment link retrieved successfully",
  "data": {
    "id": "f7a9ff0a-678f-45ba-a918-dcafc5d479e9",
    "payment_name": "Invoice #12345",
    "amount": 100.5,
    "currency": "USDT",
    "payment_url": "sandboxpay.bitxpay.com/payment_link?payment_id=f7a9ff0a-678f-45ba-a918-dcafc5d479e9",
    "payment_status": "processing",
    "payment_type": "one_time",
    "source": "payment_link_api",
    "starts_at": "2026-03-12T15:21:12.988351Z",
    "expires_at": "2026-03-13T15:21:12.988351Z",
    "max_uses": 1,
    "current_uses": 0,
    "is_active": true,
    "is_expired": false,
    "is_test": false,
    "customer_id": "CUST-20260312-96D009D4",
    "order_id": "ORD-20260312-E29917C9",
    "auto_fill": true,
    "summary": {
      "total_payers": 0,
      "total_transactions": 0,
      "total_amount_received": 0,
      "total_amount_received_crypto": 0,
      "pending_transactions": 0,
      "completed_transactions": 0,
      "failed_transactions": 0
    },
    "created_at": "2026-03-12T15:21:12.988356Z"
  }
}

Response Fields:

FieldTypeDescription
idstring (UUID)Unique payment link identifier
payment_namestringPayment link name
descriptionstringPayment description (if provided)
amountfloatPayment amount
currencystringCurrency code
payment_urlstringCheckout page for customers (currently without a scheme; prefix https://)
payment_statusstringStatus: processing, completed, expired, cancelled
payment_typestringPayment type: one_time, recurring
sourcestringOrigin of the payment link: payment_link_api
starts_attimestampTime from which the link can be paid
expires_attimestampExpiration timestamp
max_usesintegerMaximum number of uses allowed
current_usesintegerCurrent number of uses
is_activebooleanWhether the payment link is active (merchant-controlled; distinct from is_expired)
is_expiredbooleanWhether the payment link's expires_at has passed
is_testbooleanWhether this is a test payment
settlement_statusstringSettlement status, once a payment has been received (optional)
usd_valuefloatUSD value of the payment, once known (optional)
payersarrayPayers who paid this link (optional; see below)
transactionsarrayOn-chain transactions for this link (optional; see below)
customer_idstringCustomer ID (auto-generated or provided)
customer_namestringCustomer name (if provided)
customer_emailstringCustomer email (if provided)
product_namestringProduct name (if provided)
product_descriptionstringProduct description (if provided)
cartobjectShopping cart details (if provided)
order_idstringOrder ID (auto-generated or provided)
auto_fillbooleanAuto-fill setting
success_urlstringSuccess redirect URL (if provided)
cancel_urlstringCancel redirect URL (if provided)
webhook_metadataobjectCustom webhook metadata (if provided)
summaryobjectTransaction summary statistics
summary.total_payersintegerTotal number of unique payers
summary.total_transactionsintegerTotal number of transactions
summary.total_amount_receivedfloatTotal amount received in fiat
summary.total_amount_received_cryptofloatTotal amount received in crypto
summary.pending_transactionsintegerNumber of pending transactions
summary.completed_transactionsintegerNumber of completed transactions
summary.failed_transactionsintegerNumber of failed transactions
created_attimestampCreation timestamp

Summary Field

The summary object is always included in the response and provides real-time statistics about payments received for this payment link.

payers[] fields: id, name, email, created_at, and optionally country, phone, wallet_address, ip_address, region.

transactions[] fields: id, total_amount_crypto, network_id, network_name, created_at, and optionally total_amount_fiat, tx_hash, tx_hash_send_time, tx_confirmation_time, tx_block, payment_currency, contract_address, payment_type, status, payment_status, payment_wallet.

Soft-deleted links are still returned by this endpoint (with is_active: false).

Error Responses ​

StatusErrorDescription
400Bad RequestInvalid payment link ID format
401UnauthorizedMissing or invalid API key/signature
404Not FoundPayment link not found
500Internal Server ErrorServer error

Soft delete a payment link by its ID. The link is marked deleted and inactive, disappears from List Payment Links, can no longer be paid, and any pending checkout order for it is voided. It remains readable via Get Payment Link by ID.

Request ​

DELETE /payment_links/{id}

Path Parameters ​

ParameterTypeDescriptionExample
idstringPayment Link ID (UUID)"22222222-2222-2222-2222-222222222222"

Response (200 OK) ​

json
{
  "message": "Payment link deleted successfully"
}

The response carries no data object. Deleting a link that is already deleted returns 200 again (the operation is idempotent).

Error Responses ​

StatusErrorDescription
400Bad RequestInvalid payment link ID - not a UUID
401UnauthorizedMissing or invalid API key/signature
500Internal Server ErrorFailed to delete payment link - currently also returned when the ID does not exist or belongs to another merchant

Deactivate, re-activate or expire a payment link without deleting it.

Request ​

PUT /payment_links/{id}/status

json
{
  "status": "deactivate"
}
statusEffect
deactivateSets is_active: false. The link can no longer be paid but can be re-activated later.
expireSets expires_at to now and is_active: false. Requests engine-order cancellation where allowed; orders with observed/pending funds are left to finish. Expiry is irreversible.
activateIntended to set is_active: true. Currently fails with 500 (Failed to update payment link status); re-activation is not available until this is fixed.

Response (200 OK) ​

json
{
  "message": "Payment link status updated to deactivate successfully",
  "data": {
    "id": "22222222-2222-2222-2222-222222222222",
    "payment_name": "Invoice #12345",
    "amount": 100.5,
    "currency": "USDT",
    "payment_url": "sandboxpay.bitxpay.com/payment_link?payment_id=22222222-2222-2222-2222-222222222222",
    "payment_status": "processing",
    "payment_type": "one_time",
    "source": "payment_link_api",
    "starts_at": "2026-01-31T10:00:00Z",
    "expires_at": "2026-03-13T15:23:32.084432Z",
    "max_uses": 1,
    "current_uses": 0,
    "is_active": false,
    "is_expired": false,
    "is_test": false,
    "customer_id": "AB-001",
    "order_id": "ORD-20260226-A1B2C3",
    "auto_fill": true,
    "created_at": "2026-01-31T10:00:00Z"
  }
}

data has the same shape as a list item.

Error Responses ​

StatusErrorDescription
400Bad RequestInvalid payment link ID, Invalid request payload, or Validation failed: status must be one of: activate, deactivate, expire
401UnauthorizedMissing or invalid API key/signature
500Internal Server ErrorLink not found, belongs to another merchant, or status: activate (see above)

7. Get Checkout Catalog ​

Lists the chains, tokens and settlement currencies the hosted checkout can currently offer. Useful to know which networks a customer will be able to pay on.

Request ​

GET /payment_links/catalog

Response (200 OK) ​

json
{
  "currencies": ["AUD", "CAD", "CHF", "EUR", "GBP", "USD"],
  "chains": [
    {
      "chain_id": 1,
      "family": "evm",
      "tokens": [
        {
          "token": "0x1abaea1f7c830bd89acc67ec4af516284b1bc33c",
          "symbol": "EURC",
          "decimals": 6,
          "currencies": ["AUD", "CAD", "CHF", "EUR", "GBP", "USD"]
        }
      ]
    }
  ]
}
FieldTypeDescription
currenciesarrayFiat settlement currencies the checkout can quote in
chains[].chain_idintegerChain ID (EVM chain ID, or an internal ID for non-EVM families)
chains[].familystringevm, tron, solana, …
chains[].tokens[].tokenstringToken contract address
chains[].tokens[].symbolstringToken symbol
chains[].tokens[].decimalsintegerToken decimals
chains[].tokens[].currenciesarrayFiat currencies this token can settle

This response is not wrapped in message/data.

Error Responses ​

StatusErrorDescription
401UnauthorizedMissing or invalid API key/signature
503Service UnavailableCheckout engine disabled in this environment

Webhook data ​

See the exact event payloads for payment success, partial payment, overpayment, expiry, and refunds. Webhook data differs from REST responses: link creation uses name instead of payment_name, and amount is a string. order_id and receipt_number are not automatically added to notification data. webhook_metadata is supported on link creation but absent from payment status/refund DTOs. For engine status events, correlate with data.payment_id (the link UUID); data.link_id is an INV-... display reference.

Payer checkout ​

When engine checkout is enabled and configured, newly created links receive an engine order. An engine attachment failure fails creation and removes the new link instead of returning an unusable checkout. source remains payment_link_api; it identifies provenance, not checkout capability.

Use the public checkout API for options, quoting, and state polling. The hosted checkout compatibility API also returns live fee/gas breakdown and a verbatim engine_quote when available. is_test: true creates a simulated engine order; sandbox host selection alone does not set this field. Fetch currently offerable chains and tokens from the catalog rather than assuming every currency/network record is payable.

receipt_number is an optional field in create, list, detail, and status responses. Completed and overpaid-completed detail reads ensure a receipt reference is assigned. Treat it as a display reference, not the payment link UUID.

Authentication ​

All requests require the following headers:

X-API-Key: btxm_9b451fa04a2e           # same format in sandbox and production
X-API-Signature: <base64_encoded_ed25519_signature>
X-API-Timestamp: 2026-01-31T12:00:00Z
Content-Type: application/json

Signing Process ​

  1. Construct message:

    message = METHOD + PATH + TIMESTAMP + BODY

    PATH is the full request path including /api/v1 (e.g. /api/v1/payment_links), without the query string. BODY is the exact raw body string sent (empty for GET/DELETE).

  2. Sign with Ed25519 (EdDSA):

    • Do not pre-hash — Ed25519 hashes the message internally (SHA-512)
    • Produce the raw 64-byte signature
    • Encode as Base64
    • (Legacy RSA keys: sign with RSA-PSS + SHA-256 instead, then Base64-encode)
  3. Include in request headers

For detailed implementation examples in various languages, see the Merchant API Authentication Guide.


Rate Limiting ​

  • Create Payment Link, Get Currencies, Get Checkout Catalog: 100 requests per minute per client IP (HTTP 429 Too many requests, please try again later when exceeded)
  • List / Get / Update status / Delete: no limiter attached directly by the merchant payment route registration; global middleware or infrastructure may add limits

Common Use Cases ​

Get Available Currencies ​

Before creating a payment link, fetch the list of supported currencies:

bash
curl https://sandboxapi.bitxpay.com/api/v1/payment_links/currencies \
  -H "X-API-Key: btxm_9b451fa04a2e" \
  -H "X-API-Signature: <signature>" \
  -H "X-API-Timestamp: 2026-01-31T12:00:00Z" \
  -H "Accept: application/json"
bash
curl -X POST https://sandboxapi.bitxpay.com/api/v1/payment_links \
  -H "X-API-Key: btxm_9b451fa04a2e" \
  -H "X-API-Signature: <signature>" \
  -H "X-API-Timestamp: 2026-01-31T12:00:00Z" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_name": "Product Purchase",
    "amount": 99.99,
    "currency": "USDT"
  }'
bash
curl -X POST https://sandboxapi.bitxpay.com/api/v1/payment_links \
  -H "X-API-Key: btxm_9b451fa04a2e" \
  -H "X-API-Signature: <signature>" \
  -H "X-API-Timestamp: 2026-01-31T12:00:00Z" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_name": "Premium Course",
    "amount": 299.99,
    "currency": "USDC",
    "description": "Advanced Web Development Course",
    "customer_email": "customer@example.com",
    "product_name": "Web Dev Pro",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel"
  }'
bash
curl 'https://sandboxapi.bitxpay.com/api/v1/payment_links?status=pending&currency=USDT&limit=10' \
  -H "X-API-Key: btxm_9b451fa04a2e" \
  -H "X-API-Signature: <signature>" \
  -H "X-API-Timestamp: 2026-01-31T12:00:00Z"
bash
curl -X DELETE https://sandboxapi.bitxpay.com/api/v1/payment_links/{id} \
  -H "X-API-Key: btxm_9b451fa04a2e" \
  -H "X-API-Signature: <signature>" \
  -H "X-API-Timestamp: 2026-01-31T12:00:00Z" \
  -H "Content-Type: application/json"

Support ​

For questions or issues: