Callback Notifications

Merchants enrolled in callbacks receive POST notifications when invoice payment state changes.

Current triggers:

• Partial payment received

• Payment completed

Callback payload shape:

{
  "signature": "e1ca4421621c4d795fe3612b1044634595c52ebe1c52225573c310741c9d47b6",
  "data": {
    "client": {
      "name": "Optional Customer Name",
      "email": "[email protected]",
      "phone": "[phone]",
      "referenceID": "order-10001"
    },
    "paidAmount": 0.1,
    "subTotal": 0.1,
    "total": 0.1,
    "partialPaymentsEnabled": false,
    "currency": "USDC",
    "completed": true,
    "description": "Optional Order Description",
    "transactions": [
      {
        "tx": "0xd1c7fe2821a9df5240f3d31e570a760322fa979f84c0655a8f9f857023e7064f",
        "sender": "0x2F67f1426f33E25A920F0b2139cd460fDfb8997C",
        "amount": 0.1,
        "cryptoAmount": 100000,
        "timestamp": "2024-09-05T21:00:27.000Z",
        "network": "MATIC_POLYGON"
      }
    ],
    "createdAt": "2024-09-05T20:59:47.429Z",
    "merchant": {
      "name": "Business Name",
      "initiator": "POS API Key Name"
    },
    "id": "66da1bc34f03a871430c1a71"
  }
}

Signature

signature is computed as:

sha256(JSON.stringify(data) + secret)

Use your callback secret issued during onboarding.

Delivery and Retry Behavior

Current runtime delivery behavior:

• Initial POST timeout: 30 seconds

• If no response is received, one retry is sent after 5 seconds

• Retry request timeout: 5 seconds

Reliability Guidance

• Treat callbacks as at-least-once delivery (deduplicate by data.id plus latest transaction hash/count).

• Always return a fast 2xx acknowledgement after validating signature.

• Use GET /crypto/v1/status/{id} to reconcile final state if callback processing fails.

Validation Example

See Validating the Callback Notification.