Webhook Payloads

Webhook Callbacks

EdfaPay sends real-time transaction updates to your configured webhook endpoint using HTTP POST requests. Use the examples on this page to understand how each transaction status appears in webhook payloads and what action to take after you receive it.

Process the status and type fields together to determine whether the transaction is still in progress, completed successfully, or failed.

Intermediate Statuses

Intermediate statuses mean the transaction is not yet final. Do not mark the payment as successful or failed until you receive a final webhook update.

Redirect (3D Secure or Additional Authentication Required)

{
  "transactionId": "c3ece452-564a-4d29-97c2-25aba8b3f0eb",
  "orderId": "8179228",
  "amount": 100.0,
  "currencyCode": "682",
  "cardScheme": "MasterCard",
  "status": "Redirect",
  "channel": "Payment Gateway",
  "type": "Purchase",
  "createdAt": "2026-04-02T13:58:04.404837",
  "finishedAt": "2026-04-02T13:58:07.508395879",
  "merchantId": "7da313e4-5424-4527-befc-53d81c977b1f",
  "pgDetails": {
    "reason": null
  }
}

This status means additional customer authentication, such as 3D Secure, is required before the transaction can complete.

Pending

{
  "transactionId": "c3ece452-564a-4d29-97c2-25aba8b3f0eb",
  "orderId": "8179228",
  "amount": 100.0,
  "currencyCode": "682",
  "cardScheme": "MasterCard",
  "status": "Pending",
  "channel": "Payment Gateway",
  "type": "Purchase",
  "createdAt": "2026-04-02T13:58:04.404837",
  "finishedAt": "2026-04-02T13:59:15.411824707",
  "merchantId": "7da313e4-5424-4527-befc-53d81c977b1f",
  "pgDetails": {
    "reason": null
  }
}

Pending is an intermediate status. Wait for a final webhook update before you mark the transaction as successful or failed.

Transaction Outcomes

The following examples show final transaction outcomes and the expected action for each operation type.

{
  "transactionId": "7fcae16d-4035-43e4-806b-87b51881135e",
  "orderId": "678895",
  "amount": 1150.0,
  "currencyCode": "682",
  "cardScheme": "MasterCard",
  "status": "Approved",
  "channel": "Payment Gateway",
  "type": "Purchase",
  "createdAt": "2026-04-02T14:09:30.764985",
  "finishedAt": "2026-04-02T14:10:46.397810922",
  "merchantId": "7da313e4-5424-4527-befc-53d81c977b1f",
  "pgDetails": {
    "reason": null
  },
  "rrn": "609211300976"
}

This indicates a successful payment. You can safely mark the order as paid.

SoftPOS Webhook Payload

The following payload represents a transaction processed through SoftPOS devices. It includes additional terminal and EMV-related fields that do not appear in standard Payment Gateway webhook payloads.

{
  "transactionId": "1c04c3d6-04f0-4f1b-b2e5-550a878442d8",
  "orderId": "1c04c3d6-04f0-4f1b-b2e5-550a878442d8",
  "amount": 0.1,
  "currencyCode": "682",
  "cardScheme": "Visa",
  "status": "Approved",
  "channel": "Soft POS",
  "type": "Purchase",
  "createdAt": "2026-04-09T15:58:01.447205",
  "finishedAt": "2026-04-09T15:58:02.220938331",
  "merchantId": "fc960d89-4ed2-40a4-86c0-c9151dce2ead",
  "softposDetails": {
    "trsm": "4E0144",
    "stan": "001088",
    "cardAcceptorBusinessCode": "7542",
    "bid": "588849",
    "applicationId": "A0000000031010",
    "kernelId": "03",
    "providerMerchantId": "205331022408",
    "providerTerminalId": "5130032400337880",
    "applicationCryptogram": "DF0B0D76C018C142",
    "cryptogramInformationData": "80",
    "tvr": "0000000000",
    "acquirerBank": "RYDB",
    "cardholderName": null,
    "responseMessageTextEnglish": "APPROVED",
    "responseMessageTextArabic": "مقبولة",
    "responseMessageCode": "000",
    "cvmrCode": "3",
    "cvmr": {
      "cvmr_code": "3",
      "cvmr_message_english": "NO VERIFICATION REQUIRED",
      "cvmr_message_arabic": "لا يتطلب التحقق"
    },
    "authCode": "061060",
    "apkVersionNo": "1.0.0",
    "cvm": "420300"
  },
  "rrn": "091258011088"
}

SoftPOS Fields

Field	Description
channel	Indicates SoftPOS transactions ("Soft POS")
softposDetails	Contains terminal and EMV-specific transaction data
trsm	Transaction reference identifier generated by the terminal
stan	System Trace Audit Number (unique transaction reference)
cardAcceptorBusinessCode	Merchant category code (MCC)
bid	Bank or business identifier
applicationId	Application identifier used for EMV processing
kernelId	Kernel identifier for transaction processing
providerMerchantId	Merchant ID assigned by the SoftPOS provider
providerTerminalId	Terminal ID assigned by the provider
applicationCryptogram	Cryptographic value generated during the transaction
cryptogramInformationData	Indicates the type of cryptogram generated
tvr	Terminal Verification Results (EMV risk checks)
acquirerBank	Acquiring bank identifier
cardholderName	Name of the cardholder (if available)
responseMessageTextEnglish	Transaction response message in English
responseMessageTextArabic	Transaction response message in Arabic
responseMessageCode	Response code returned by issuer
cvmrCode	Cardholder verification result code
cvmr	Detailed CVM (Cardholder Verification Method) information
authCode	Authorization code from issuing bank
apkVersionNo	Application version used by the terminal
cvm	Cardholder Verification Method result
rrn	Retrieval Reference Number for transaction tracking

📘
SoftPOS responses include additional terminal-level data inside softposDetails.
These fields are specific to in-person transactions and are not present in Payment Gateway webhook responses.

Important Notes

Treat a transaction as successful only when the webhook status is Approved.

Redirect means additional customer authentication is required.
Pending means the transaction is still being processed.
Approved means the transaction completed successfully.
Declined means the transaction failed.

Best Practices

Tip: Always validate webhook requests, return HTTP 200 OK quickly, handle duplicate callbacks with idempotency, and store transactionId for tracking and reconciliation.