Payment Gateway

Overview

EdfaPay Payment Gateway enables secure payment processing through both Checkout (hosted) and Server-to-Server (S2S) integrations. It supports the full transaction lifecycle including payment initiation, execution, and status tracking.

API Reference:
https://docs.edfapay.com/v2.0/reference/payment-gateway.md

Integration Types

EdfaPay provides two integration models to support different implementation and compliance requirements.

Integration Type	Description	Best Use Case
Checkout	Redirect customer to EdfaPay hosted payment page	Fast and simple integration
S2S	Direct API integration handled by merchant backend	Full control and customization

Tip: Start with Checkout for faster implementation. Use S2S only if you need full control over the payment experience and can support the required backend and compliance responsibilities.

Supported Payment API Methods

The following API methods are available for payment creation, transaction management, and status retrieval.

API Method	Endpoint	Integration	Description
Initiate Payment	`/api/v1/payment/initiate`	Checkout / Hybrid	Create payment session
Sale	`/api/v1/payment/sale`	S2S	Direct payment (Auth + Capture)
Authorization	`/api/v1/payment/authorize`	S2S	Reserve funds only
Capture	`/api/v1/payment/capture`	S2S	Capture authorized funds
Refund	`/api/v1/payment/refund`	S2S	Refund full or partial amount
Transaction Inquiry	`/api/v1/payment-gateway/s2s/sale/{id}`	S2S	Retrieve transaction status

Alert: All S2S APIs require valid authentication headers: X-API-KEY and X-Signature. Invalid or missing authentication returns 403 Forbidden.

Request Example

The following example shows a typical payment request payload.

{
  "orderId": "Ord-123456",
  "currency": "SAR",
  "amount": 100.00,
  "customerDetails": {
    "name": "Alice",
    "email": "[email protected]",
    "phone": "+966533991234"
  },
  "address": {
    "line1": "Riyadh",
    "city": "Riyadh",
    "country": "SA"
  }
}

{
  "code": 200,
  "message": "Success",
  "data": {
    "transactionId": "0808724324827033891283",
    "orderId": "Ord-123456",
    "amount": 100.00,
    "currency": "SAR",
    "status": "SUCCESS"
  }
}

Payment Flow

The payment process begins when you send a transaction request to EdfaPay.

Send a payment request to EdfaPay.
For Checkout, redirect the customer to the hosted payment page using the returned paymentUrl.
For S2S, process the payment directly through the API.
Receive the initial API response.
Receive the callback with the final transaction status.

Flow Type	Behavior
Checkout	The customer completes payment on the EdfaPay hosted payment page
S2S	The merchant backend submits and manages the payment request directly

Important: Always treat the callback (webhook) as the final transaction status. Do not rely only on the immediate API response.

Callback Example

The following example shows a callback payload returned after payment processing.

{
  "transactionId": "0808724324827033891283",
  "status": "SUCCESS",
  "amount": 100.00
}

Important: Your callback endpoint must be publicly accessible and should handle retries correctly to avoid missed transaction updates.

Environments

Use the correct base URL for the environment you are targeting.

Environment	Base URL
Sandbox	`https://dev-api.edfapay.com`
Production	`https://api.edfapay.com`

Alert: Make sure your API keys, signatures, and endpoint URLs all match the same environment. Mixing sandbox and production credentials will cause authentication and transaction errors.

Additional Notes

The gateway supports a broad set of payment capabilities that can be implemented based on your business requirements.

Feature	Description
Authorization and Capture	Authorize funds first and capture them later
Refunds	Process full or partial refunds through the API
Recurring Payments	Support recurring payment use cases using recurring tokens
Webhooks	Receive real-time transaction updates
Fraud Checks	Apply built-in fraud screening mechanisms

Summary

EdfaPay provides flexible integration through Checkout and S2S APIs, with a complete set of payment operations to manage transactions securely. Proper handling of authentication, environment configuration, and callbacks is essential for a successful integration.