Embedded Integration

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.

---

Embedded Integration APIs

---

Integration Workflow

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

sequenceDiagram
    participant C as Customer
    participant M as Merchant
    participant E as EdfaPay API
    participant P as Payment Processor

    %% Payment Start
    C->>M: Enter Card Details

    %% API Request
    M->>E: SALE Request

    %% 3DS Flow
    E-->>M: HTML Page (3DS Challenge)
    M->>C: Render HTML Page (OTP Form)

    C->>P: Submit OTP

    %% Auth Result
    P-->>E: Auth Result

    %% Finalization
    E->>C: Redirect (successUrl)
    E-->>M: Webhook (Final Status)

    M->>C: Display Result

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://app-api.edfapay.com/api/v1/payment-gateway/s2s/sale). 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 html.
• Your application (web or mobile) must then display the 3DS authentication challenge within a WebView or an iframe using the provided html.

4. Receive Transaction Outcome
Upon successful authentication, EdfaPay redirects the user back to your designated successUrl 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://app-api.edfapay.com/api/v1/payment-gateway/s2s/.

Request Method: All requests must be POST requests, formatted as application/json.

Mandatory Fields: Each request must precisely include fields such as orderId, amount, 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 an html field.

This field contains a complete HTML page for the 3DS authentication challenge, which must be rendered to the customer using either a WebView or an iframe.

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.