Webhook Payloads

EdfaPay delivers real-time transaction updates to your configured webhook endpoint using POST requests. This documentation outlines the various payload structures you may receive, categorized by transaction status.

Redirect Response (3D Secure / Additional Authentication Required)

{
    "action": "SALE",
    "amount": "0.11",
    "card": "512345XXXXXX0008",
    "card_brand": "MASTER",
    "card_expiration_date": "01/2039",
    "currency": "SAR",
    "hash": "examplehash",
    "merchant_name": "Test Merchant",
    "order_id": "ORDER123",
    "redirect_method": "POST",
    "redirect_params": "RedirectParamsObject",
    "redirect_url": "https://3ds.example.com",
    "result": "REDIRECT",
    "status": "REDIRECT",
    "trans_date": "2025-07-20 13:30:19",
    "trans_id": "TX-0001"
}

3D Secure Authentication in Progress (Pending)

{
    "action": "SALE",
    "amount": "0.11",
    "card": "512345XXXXXX0008",
    "card_brand": "MASTER",
    "card_expiration_date": "01/2039",
    "currency": "SAR",
    "hash": "examplehash",
    "merchant_name": "Test Merchant",
    "order_id": "ORDER123",
    "result": "PENDING",
    "sessionId": "SESSION00001",
    "status": "PENDING",
    "trans_date": "2025-07-20 13:30:21",
    "trans_id": "TX-0001"
}

Success Response (Payment Settled)

This payload is sent when a payment transaction has been successfully processed.

Common Fields

Field	Explanation
`action`	Always `SALE` for payment transactions.
`amount`	The payment amount requested by the merchant.
`card`	Masked card number used in the payment (e.g., `XXXXXX0008`).
`card_brand`	Type of card: `VISA`, `MASTER`, `MADA`, etc.
`card_expiration_date`	Expiry date of the card.
`currency`	Transaction currency (e.g., `SAR`).
`hash`	Hash signature for verifying webhook authenticity.
`merchant_name`	Your business or merchant name.
`order_id`	The ID of the order as defined in your system.
`trans_id`	Unique transaction ID assigned by EdfaPay.
`trans_date`	Date and time of the transaction.
`result`	Outcome of the transaction: `SUCCESS`, `REDIRECT`, `PENDING`, or `DECLINED`.
`status`	Current status of the transaction: `SETTLED`, `REDIRECT`, or `DECLINED`.
`redirect_url`	Used for 3D Secure redirection (if required); present only when `result` is `REDIRECT`.
`redirect_params`	Parameters for 3D Secure redirection (if required); present only when `result` is `REDIRECT`.
`rrn`	Reference Retrieval Number (RRN) from the card issuer; present for successful transactions.
methods	Integration type used in making the payment (Card, Apple pay)
`recurring_token`	Provided when tokenization is used.

{
    "action": "SALE",
    "amount": "0.11",
    "card": "512345XXXXXX0008",
    "card_brand": "MASTER",
    "card_expiration_date": "01/2039",
    "currency": "SAR",
    "hash": "examplehash",
    "merchant_name": "Test Merchant",
    "methods": "applepay",
    "order_id": "ORDER123",
    "recurring_token": "9d8238bc-2877-4f29-a464-token-example",
    "result": "SUCCESS",
    "rrn": "520110182659",
    "status": "SETTLED",
    "trans_date": "2025-07-20 13:31:05",
    "trans_id": "TX-0001"
}

🚧
Confirming Payment Status
The PENDING, REDIRECT, and 3D Secure statuses are intermediate. Only mark orders as paid upon receiving a payload with both result: SUCCESS and status: SETTLED.
{
    "result": "SUCCESS",
    "status": "SETTLED"
}

Failed Response (Declined)

{
    "action": "SALE",
    "amount": "0.11",
    "card": "512345XXXXXX0008",
    "card_brand": "MASTER",
    "card_expiration_date": "01/2039",
    "currency": "SAR",
    "hash": "examplehash",
    "merchant_name": "Test Merchant",
    "methods": "applepay",
    "order_id": "ORDER123",
    "result": "DECLINED",
    "status": "DECLINED",
    "decline_reason": "Insufficient Funds",
    "trans_date": "2025-07-20 13:31:05",
    "trans_id": "TX-0001"
}

Refund (CREDITVOID Action) Response (Completed)

Notifies you when a refund is successfully processed.

Field	Explanation
`action`	Indicates a refund action; always `CREDITVOID`.
`amount`	The amount refunded.
`card_brand`	Brand of the card used in the original transaction.
`creditvoid_date`	Date and time the refund was processed.
`hash`	Hash signature for webhook data validation.
`merchant_name`	Your registered merchant or store name.
`order_id`	Your internal order ID associated with the refunded transaction.
`result`	Outcome of the refund: `ACCEPTED` or `SUCCESS`.
`rrn`	Reference Retrieval Number (RRN).
`status`	Status of the refund; always `REFUND`.
`trans_id`	Original transaction ID from the EdfaPay platform.

{
    "action": "CREDITVOID",
    "amount": "0.11",
    "card_brand": "MASTER",
    "creditvoid_date": "21-07-2025 13:58:14",
    "hash": "e9dfc813ffeca5d3a8XXXXX080278428d33753b",
    "merchant_name": "Test Merchant",
    "order_id": "ORD0SU1",
    "result": "ACCEPTED",
    "rrn": "520xxxx76671",
    "status": "REFUND",
    "trans_id": "5733832xxxxxx5133019"
}

Recurring Payment Response (Settled)

Sent when a recurring payment is successfully processed.

Field	Explanation
`action`	Indicates a recurring payment; always `RECURRING`.
`amount`	The amount charged.
`currency`	Currency of the transaction (e.g., `SAR`, `USD`).
`order_id`	Your order ID linked to this recurring transaction.
`trans_id`	Unique transaction ID from EdfaPay.
`recurring_token`	The token used for this recurring transaction.
`status`	Status of the recurring payment: `SETTLED` for completion, `DECLINED` for failure.
`result`	Outcome of the recurring payment: `SUCCESS` or `DECLINED`.
`trans_date`	Date and time of this specific recurring payment.

{
    "action": "RECURRING",
    "amount": "0.11",
    "currency": "SAR",
    "order_id": "ORDER123",
    "trans_id": "TX-0001",
    "result": "SUCCESS",
    "status": "SETTLED",
    "recurring_token": "9d8238bc-2877-4f29-a464-token-example",
    "trans_date": "2025-07-20 13:31:05"
}

Webhook Payload Summary

Action	Used For	Result Status	Lifecycle
`SALE`	Payment	`SUCCESS` / `REDIRECT` / `PENDING` / `DECLINED`	Purchase completed or pending
`CREDITVOID`	Refund	`ACCEPTED` / `SUCCESS`	Refund completed
`RECURRING`	Subscription	`SUCCESS` / `DECLINED`	Subscription / recurring

Important Notes for Developers

Always validate the hash parameter to ensure authenticity.
Respond to webhooks with HTTP 200 OK to acknowledge receipt.
Handle retries safely, as duplicate callbacks may occur.
Only mark orders as Paid / Failed upon receiving the final SUCCESS / DECLINED status.

📘
Hash Validation: Ensuring Webhook Authenticity
To ensure the integrity and authenticity of webhook payloads, always validate the hash parameter. This step confirms that the webhook originated from EdfaPay and that its content has not been tampered with.
Implementation:

Recalculate the hash: Generate a new hash using your secret key and the received payload data.

Compare: Match your recalculated hash against the hash parameter provided in the payload.

Process: Only proceed with processing the webhook if the hashes match, confirming the payload's validity.

❗️
Idempotency and Retries: Handling Duplicate Webhooks
EdfaPay may re-send webhook notifications if your server does not acknowledge receipt (e.g., by returning an HTTP 200 OK status). To prevent duplicate processing of the same transaction, it is crucial to implement idempotency in your system.
Recommendation: Design your webhook handler to safely process duplicate notifications. This ensures data consistency and prevents unintended side effects, even if a webhook is delivered multiple times.