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 client panel and use it to verify notifications' signatures. See Verifying notification signatures