HomeGuidesAPI Reference
Guides

Webhook Payloads

Webhook payload examples for intermediate and final transaction statuses, SoftPOS responses, and webhook handling guidance.

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.

Updated 3 months ago

Did this page help you?