Notifications

Payment and payout webhooks report transaction status updates. Notifications are posted to the transaction's notificationUrl when supplied; otherwise, CyberPay uses the brand's notification URL configured in the merchant portal.

Note 📌

All notification communications must use TLS/SSL encryption and an HTTPS endpoint.

Note 📌

Validate the notification request using signatures. More information here.

Acknowledge each notification with HTTP 200. Other HTTP statuses are treated as failed delivery.

Delivery starts after an initial eight-second queue delay. After a failed delivery, the standard retry delays are 30 seconds, 2 minutes, 10 minutes, 1 hour, 6 hours, 24 hours, and 72 hours, measured from the preceding failed attempt. Automatic retries stop after the final attempt.

Notifications can be delivered more than once. Verify the signature and process duplicates without fulfilling an order or recording a payout twice. Status values are uppercase; internalId and transactionId identify the same transaction. See transaction statuses.

Merchants can manually resubmit a notification using the merchant portal.

Pay-in notification example:

{
  "internalId": "fb488f37-8491-4e33-364f-93e72a188ba3",
  "transactionId": "fb488f37-8491-4e33-364f-93e72a188ba3",
  "sessionId": "bc8d79c2-ba6c-41b9-beec-8de7fbf56218",
  "merchantName": "Test",
  "brandName": "Test Brand",
  "userId": "a9f775048c2bbd86a9a5e8785f0",
  "type": "P2P",
  "paymentOptionName": "Easy P2P",
  "country": "EG",
  "currency": "EGP",
  "originalCurrency": "EGP",
  "originalAmount": 300,
  "paymentAmount": 300,
  "payoutAmount": null,
  "merchantReference": "mr-sfttarref",
  "status": "COMPLETED",
  "language": "EN",
  "paymentReference": "pr-fpltrea57laf",
  "storedToken": null,
  "extra1": null,
  "extra2": null,
  "extra3": null,
  "customer": {
    "_id": "2f6575d1-9e74-4db6-bbba-e836c16d8e91",
    "customerId": "86629a8e-9074-414e-b31b-52933b7995bb",
    "email": "[email protected]",
    "name": "Test Test",
    "phone": "0124589875456",
    "userDevice": "MOBILE",
    "userAgent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Mobile Safari/537.36",
    "ip": "196.159.229.116",
    "address": {
      "street": "Test Mountain",
      "streetNumber": "59994",
      "country": "EG",
      "zipCode": "2211",
      "city": "Lake test",
      "state": null
    },
    "identify": {
      "number": "73428tf2-f23e-xxxx-9xxx-530d2083f8c2",
      "type": "DNI"
    }
  },
  "orderDetails": [],
  "shippingAddress": null,
  "bonusApplied": false,
  "promoCode": null
}

Payout notification example:

{
  "internalId": "fb488f37-8491-4e33-364f-93e72a188ba3",
  "transactionId": "fb488f37-8491-4e33-364f-93e72a188ba3",
  "sessionId": "bc8d79c2-ba6c-41b9-beec-8de7fbf56218",
  "merchantName": "Test",
  "brandName": "Test Brand",
  "userId": "",
  "type": "P2P",
  "paymentOptionName": "Easy P2P",
  "country": "EG",
  "currency": "EGP",
  "originalCurrency": "EGP",
  "originalAmount": 1090.99,
  "paymentAmount": null,
  "payoutAmount": 1090.99,
  "merchantReference": "71221234",
  "status": "COMPLETED",
  "language": "EN",
  "paymentReference": null,
  "storedToken": null,
  "extra1": null,
  "extra2": null,
  "extra3": null,
  "customer": {
    "email": "[email protected]",
    "name": "abc de",
    "phone": "15201234343",
    "_id": "28111299-d708-46f7-996e1222323dede3"
  },
  "orderDetails": [],
  "shippingAddress": null,
  "bonusApplied": false,
  "promoCode": null
}