Notifications

Payment notifications

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

API will call this URL using POST request with the contents visible on our OpenAPI documentation: GET /payments/{paymentId}

For each payment status change Bitclear API will attempt to call notificationUrl at least once. This means that you might receive duplicated notifications. In case you have missed payment notification (for example your server wasn't available) you use our API to request notification resend.

The notifications Bitclear API sends are not deltas, but the full snapshots of the state, so the API client should always replace the state with the one which is provided as the latest one. You can keep old states for your records.

Notification Schema

Notifications are now wrapped inside metadata, example:

Payment notification example - body schema GET /payments/{paymentId}:

{
  "timestamp": "2019-11-01T11:38:50.246Z",
  "notificationType": "v3/payment",
  "body": { 
   // payment schema of GET /v3/payments/{paymentId}
  }
}

Payout notification example - body schema GET /payouts/{payoutId}:

{
  "timestamp": "2019-11-01T11:38:50.246Z",
  "notificationType": "v3/payouts",
  "body": { 
   // payout schema of GET /v3/payouts/{payoutId}
  }
}

Handling duplicated notifications

There are cases like network errors, or merchant server errors where Bitclear API will re-attempt sending notifications, those attempts are scheduled with backoff, so it’s possible that Client will:

• receive the same notification 2 or more times
• receive notifications out of order

In all cases you should compare timestamp which indicates when notification was generated and always use the latest notification (state) that's available.

Underpaid Payments

In the rare case when the client has sent too little Bitcoins Bitclear API will send you an appropriate notification, so you can prompt the client to send the remaining amount.
This situation shouldn't happen under normal circumstances when the client is either scanning a QR code or clicking an application link to pay, but rather when they make a mistake when typing an amount manually.

Payout notification

Since payouts are not executed immediately, but queued for later execution, clients can specify notificationUrl to opt-in for notification. Once it's completed, Bitclear API will send a POST request to specified URL with JSON object describing sent payout.

Example payout JSON can be seen on our OpenAPI documentation page, the format is exactly the same as response after approving payout: POST /v3/payouts

Notification Security

It is possible that malicious user will try to attempt to send POST request to your notification endpoint to extort money. To mitigate that risk it is recommended to set up HMAC key via client panel and use it to verify notifications' signatures. See Verifying notification signatures