Overview

The EdfaPay Embedded Integration S2S (Server-to-Server) provides a robust solution for merchants to securely capture payment details directly within their customized checkout environments. This method facilitates the secure transmission of sensitive payment data from your backend server straight to EdfaPay's API.

This integration grants unparalleled control over the user experience while upholding stringent security standards through server-side hash authentication and strict PCI-compliant data handling protocols.

Payment Flow

S2S payment flow is shown below.

Embedded Integration

Complete reference for the Embedded integration API endpoints and operations

Embedded Card Payment SALE

Process secure card payments directly within your custom checkout environment using a POST request.

Transaction Details

Access comprehensive information for all your payment transactions via a POST request.

Captures

Finalize authorized payments by capturing the pre-approved funds with a POST request.

Credit Void

Cancel an authorized payment before it is captured by voiding the transaction with a POST request.

Full Refund

Reverse the entire amount of a successfully captured transaction using a POST request.

Partial Refund

Refund a specific portion of a previously captured transaction. Multiple partial refunds are allowed as long as the total refunded amount does not exceed the original capture.

Recurring Payments

Set up and manage automated recurring payments for subscriptions and installments using a POST request.

Integration Workflow

This section outlines the step-by-step process for integrating EdfaPay's Embedded S2S solution.

1. Collect Payment Data
Securely gather essential card and customer details via your custom checkout form.

2. Submit Transaction Request
Your backend server sends a secure SALE request to the EdfaPay S2S endpoint (https://api.edfapay.com/payment/post). This POST request must include all necessary transaction parameters, such as card details, order amount, currency, and a cryptographically generated hash.

3. Handle 3D Secure (Conditional)

If 3D Secure authentication is required, EdfaPay will respond with a redirect_url and a Base64-encoded payload.
Your application (web or mobile) must then display the 3DS authentication challenge within a WebView or an iframe using the provided redirect_url.

4. Receive Transaction Outcome
Upon successful authentication, EdfaPay redirects the user back to your designated term_url_3ds and simultaneously dispatches a webhook notification containing the definitive transaction status.

Core Advantages

Complete Checkout Control: Maintain full autonomy over your customer's checkout journey, eliminating external redirects.
Seamless Integration: Achieve a clean, cohesive, and effortless integration with your existing web or mobile platforms.
Enhanced Security: Card data is processed with utmost security via S2S communication, reinforced by robust hash verification to guarantee data integrity and authenticity.
Flexible Payment Operations: Supports a diverse range of payment functionalities, including secure tokenization, recurring payment profiles, and authorization-capture workflows.

Essential Integration Components

API Endpoint: All S2S requests are directed to https://api.edfapay.com/payment/post.
Request Method: All requests must be POST requests, formatted as multipart/form-data.
Mandatory Fields: Each request must precisely include fields such as action, client_key, order_id, order_amount, order_currency, comprehensive card data, payer information, and a unique transaction hash.
3D Secure Implementation: Should 3DS be triggered, your application is responsible for presenting EdfaPay's authentication page within an iframe or a WebView.

📘
Important Note on Hash Generation
A cryptographically secure hash must be generated for every transaction request. This hash is formulated using your unique secret key, the payer's email address, and the masked card PAN, which collectively ensures the authenticity and integrity of the request, safeguarding against unauthorized alterations.

❗️
Security & Validation Advisory
All card information must be collected securely within your frontend and subsequently transmitted exclusively to your backend server. It is paramount that this sensitive data is never submitted directly from the frontend to EdfaPay.

3D Secure & Webhook Integration Details

When 3D Secure authentication is initiated, the EdfaPay API response will include both a redirect_url and redirect_params.body.

Displaying the 3DS Challenge:
- You are required to POST the redirect_params.body (a BASE64_ENCODED_STRING) to the redirect_url.
- The expected structure for this POST request body is:
```
{
  "body": "BASE64_ENCODED_STRING"
}
```
- The response from this POST operation will be a rendered HTML page—the 3DS authentication challenge—which you must display within either a WebView or an iframe.

🚧
Critical Alert: Do Not Alter 3DS Payload
It is absolutely crucial that you do not decode or modify the Base64-encoded body received from EdfaPay. This payload is cryptographically signed and must be used precisely as provided to guarantee proper and secure authentication.

Webhooks for Transaction Status:
- Webhooks are an indispensable component for this integration.
- Your backend system must be diligently configured to receive and process payment status updates dispatched from EdfaPay. These webhooks serve as critical notifications for the final transaction status (e.g., successful, declined, refunded).
- Testing Tip: During staging and development phases, leverage tools suchs as Webhook.site to effectively simulate and inspect the behavior of incoming callbacks.