Merchant Callbacks Reference

Firstly, see the Quick Start for easy instructions and pseudo-code showing how to properly verify and consume callbacks.

Authentication: you must verify the requests come with expected authorization header. See the Quick Start for details.

Integrity: fields that are marked “untrusted” come through the user browser and must be verified against your database. The values must match. If they don’t then user tampered with them. You must compare both total and currency with your database.

Your app should return HTTP status code 200 OK to confirm reception of the callback, even if you recognized user tampering and won’t ship. Your app should return other relevant status codes if request isn’t properly authenticated (most likely a misconfiguration) or request is malformed (for example, JSON body doesn’t parse).

The payment has been successfully settled and you can ship the order.

This is the only callback you need to support in your app.

Request URL:

POST payment_completed_notification_url

…where payment_completed_notification_url represents full URL you set in the config file.

Request headers:

Authorization: Bearer <cypherpunkpay_to_merchant_auth_token>

Request body (example):

{
  "untrusted": {
    "merchant_order_id": "whatever you rendered in the checkout form",
    "total": "12.34",
    "currency": "usd"
  },
  
  "status": "completed",    
  "cc_total": "0.000998",
  "cc_currency": "btc"
}

All fields are technically strings, including the amounts to facilitate precise decimals.

All fields are guaranteed present.

You do not necessarily need to handle this callback. The minimal merchant integration only needs the happy-path callback.

The payment has been cancelled or expired. Both user and merchant can manually cancel the payment. Expiration happens when user failed to initiate the payment within default 20 minutes OR the full amount failed to sufficiently confirm within default 48 hours.

Both cancelled and expired are final states, except when the merchant manually changes payment status in CypherpunkPay admin panel.

Request URL:

POST payment_failed_notification_url

…where payment_failed_notification_url represents full URL you set in the config file.

Request headers:

Authorization: Bearer <cypherpunkpay_to_merchant_auth_token>

Request body (example):

{
  "untrusted": {
    "merchant_order_id": "whatever you rendered in the checkout form",
    "total": "12.34",
    "currency": "usd"
  },
  
  "status": "cancelled"
}

All fields are technically strings, including the amounts to facilitate precise decimals.

The merchant_order_id, total, currency and status fields are guaranteed present.

The status value will be either cancelled or expired.