API Docs

Notifications

Payment notifications

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

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

Please note that this is exactly the same format that is used in "Check Payment Status"

For each payment status change we 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 we send are not deltas, but the full snapshots of the state, so the API client should always replace the state with the one that's provided. You can keep old states for your records.

Handling duplicated notifications

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

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

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

Underpaid Payments

In the rare case when the client has sent too little Bitcoins we will send you a 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 a application link to pay, but rather when they make a mistake when typing an amount manually.

Anomaly notifications

During the payment process, there are cases when the user makes a mistake or something else unexpected happens. Our system is designed to handle cases like that and return this information via "Anomaly notification", anomaly examples include:

  • User sends funds after the payment was expired
  • User paid to little (underpayment) and did not pay the remaining amount before payment expired
  • User overpaid in a single bitcoin payment

The anomalies are always linked to the specified, original paymentId, so on the API client side it will possible to match them and process according to the merchants' rules.

Please note that the exchangeRate used for anomalies might be different from the one used for payments because it's calculated at the time when we observe the anomaly.

API client can specify anomalyNotificationUrl for each payment request.
When we detect an anomaly for that payment we will send JSON containing details about the anomaly to the specified URL using HTTP POST method.

Please note that the anomalyNotificationUrl is optional - if it's not specified we won't send anomaly notification.

For anomalies we set notificationType to ANOMALY to distinguish them from regular notifications in case you use the same URL to receive both notification types.

Example anomaly can be seen on the swagger: GET /anomalies/{anomalyId}

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, BitcoinPaygate will send a POST request to specified URL with JSON object describing sent payout with notificationType set to PAYOUT.

Example payout JSON can be seen on our swagger documentation page, the format is exactly the same as response after approving payout: POST /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 admin panel and use it to verify notifications' signatures. See Verifying notification signatures