Notifications

Payment notifications

The optional notificationUrl parameter determines the URL that will receive a POST request when the status of a payment changes.

The request body is the full V4 payment representation, matching GET /v4/payments/{paymentId}. Notifications are full snapshots, not deltas, so API clients should replace their local state with the latest payload they receive.

Example payment notification body:

{
  "paymentId": "8618ed13372b483b84d56c0cc5509a401c182d9e4dc04824a6ffddd8473753a3",
  "priceAmount": 1.23,
  "priceCurrency": "USD",
  "transferAmount": 0.00018942,
  "transferCurrency": "BTC",
  "address": "2N3kVr2CHHt2pSdCidq4dwZBFeBnMQhvaka",
  "paymentUri": "bitcoin:2N3kVr2CHHt2pSdCidq4dwZBFeBnMQhvaka?amount=0.00018942",
  "expirationTime": "2026-06-10T13:12:45.239167Z",
  "paymentPageUrl": "https://payments-sandbox.bitclear.li/payments/8618ed13372b483b84d56c0cc5509a401c182d9e4dc04824a6ffddd8473753a3",
  "notificationUrl": "https://example.com/payment-callback",
  "pendingPaidPriceAmount": 0,
  "acceptedPaidPriceAmount": 1.23,
  "pendingPaidTransferAmount": 0,
  "acceptedPaidTransferAmount": 0.00018942,
  "status": "CONFIRMED",
  "externalPaymentId": "order-123",
  "transactions": []
}

For each payment status change Bitclear API will attempt to call notificationUrl at least once. You may receive duplicated notifications or notifications out of order, so compare the payment status and current state before acting on a notification.

Underpaid Payments

When a customer sends too little cryptocurrency, Bitclear API sends a notification with status UNDERPAID. Use the updated paid amount fields to decide whether to prompt the customer to send the remaining amount or handle the partial payment differently.

Payout notifications

Payout notifications are sent when a payout with notificationUrl changes state. The request body is the full V4 payout representation, matching GET /v4/payouts/{payoutId}.

Example payout notification body:

{
  "payoutId": "592cf20b-0174-4b90-b2a4-2e7209a0e3cd",
  "transferAmount": 0.1,
  "priceAmount": 111.32,
  "priceCurrency": "USD",
  "transferCurrency": "BTC",
  "comment": "Refund for a purchase of a faulty product",
  "expirationTime": "2026-06-10T12:38:50.246Z",
  "createdTime": "2026-06-10T11:38:50.246Z",
  "notificationUrl": "https://example.com/payout-callback",
  "externalPayoutId": "refund-123",
  "status": "SENT",
  "destination": {
    "destinationType": "CRYPTO_ADDRESS",
    "cryptoAddress": "2N8hwP1WmJrFF5QWABn38y63uYLhnJYJYTF"
  }
}

Notification Security

Bitclear signs notifications with the merchant HMAC key. All notifications include the X-Bitclear-Signature header, which is an HMAC-SHA1 signature of the raw JSON request body.

See Verifying notification signatures.