Embedded Apple Pay

Overview

The Apple Pay S2S (Server-to-Server) Sale API facilitates secure processing of Apple Pay transactions. It enables merchants to transmit the Apple Pay payment token directly from their frontend to EdfaPay for authorization and capture.

This integration method is particularly well-suited for merchants who:

Maintain control over their checkout workflow.
Have implemented the Apple Pay JS API within their website or application.
Possess an Apple Developer Account and manage their own Apple Pay certificate and domain verification.

⚠
Important: Unlike the Checkout Integration, EdfaPay does not host the Apple Pay domain for S2S merchants. Consequently, merchants are solely responsible for independently configuring their Apple Pay environment.

A Postman collection for the Apple Pay S2S Sale API is available for download: Download Postman Collection

Endpoint

POST /applepay/orders/s2s/sale
Base URL: https://api.edfapay.com
Content-Type: application/json

Request Parameters

Field	Type	Required	Description
`action`	String	Yes	Transaction type — for sales use `"SALE"`.
`client_key`	String	Yes	Unique merchant key provided by EdfaPay.
`brand`	String	Yes	Always `"applepay"`.
`order_id`	String	Yes	Unique order identifier generated by the merchant.
`order_amount`	Decimal	Yes	Transaction amount (e.g., `"10.00"`).
`order_currency`	String	Yes	Currency code in ISO 4217 format (e.g., `"SAR"`).
`order_description`	String	Optional	Description of the order.
`payer_first_name`	String	Yes	Customer’s first name.
`payer_last_name`	String	Yes	Customer’s last name.
`payer_middle_name`	String	Optional	Customer’s middle name.
`payer_address`	String	Yes	Billing address line 1.
`payer_address2`	String	Optional	Billing address line 2.
`payer_country`	String	Yes	Country code (ISO 3166-1 alpha-2), e.g., `"SA"`.
`payer_state`	String	Yes	State or province name.
`payer_city`	String	Yes	City name.
`payer_zip`	String	Yes	Postal/ZIP code.
`payer_email`	String	Yes	Customer’s email address.
`payer_phone`	String	Yes	Customer’s phone number (with country code).
`payer_birth_date`	Date	Optional	Date of birth in `YYYY-MM-DD` format.
`payer_ip`	String	Yes	Customer’s IPv4 address.
`return_url`	String	Yes	Redirect URL after payment completion.
`identifier`	String	Yes	Apple Merchant Identifier.
`hash`	String	Yes	MD5 hash for request authentication (see below).
`parameters`	Object	Yes	Apple Pay payment token object from Apple Pay JS API.

Sample Request

curl --location 'https://api.edfapay.com/applepay/orders/s2s/sale' \
--header 'Content-Type: application/json' \
--data '{
  "action": "SALE",
  "client_key": "LIVE_CLIENT_KEY_123456",
  "brand": "applepay",
  "order_id": "ORDER-12345",
  "order_amount": "10.00",
  "order_currency": "SAR",
  "order_description": "Test Apple Pay transaction",
  "payer_first_name": "John",
  "payer_last_name": "Doe",
  "payer_middle_name": "William",
  "payer_address": "123 Main Street",
  "payer_address2": "Apt 45",
  "payer_country": "SA",
  "payer_state": "Riyadh",
  "payer_city": "Riyadh",
  "payer_zip": "12345",
  "payer_email": "[email protected]",
  "payer_phone": "+966512345678",
  "payer_birth_date": "1985-07-25",
  "payer_ip": "192.168.1.10",
  "return_url": "https://merchant.example.com/payment-return",
  "identifier": "4A948A647051C7F562559711461EE3E76C2F67A4BA7BF34B1E61EA583BDE9CC4",
  "hash": "9d8958ffdad46ff96f22d1e63a36c357",
  "parameters": {
    "paymentData": {
      "data": "ENCRYPTED_DATA_STRING",
      "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDTALBglghkgBZQMEAgEwgA...",
      "header": {
        "publicKeyHash": "VoGggOEFLzxlUYxbD0YwirzB1uxYF1c4NIWFT62cpLE=",
        "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEYpO2E28...",
        "transactionId": "b8329e350f9ab525621b657f05a515a4cd745e58ef46c8a966748ae36e90d697"
      },
      "version": "EC_v1"
    },
    "paymentMethod": {
      "displayName": "Visa 1234",
      "network": "Visa",
      "type": "credit"
    },
    "transactionIdentifier": "b8329e350f9ab525621b657f05a515a4cd745e58ef46c8a966748ae36e90d697"
  }
}'

Postman Pre-request Script

var password = "xxxxxx-xxxxxx-xxxxxx-xxxxxxxxx"; // Your EdfaPay merchant password
var identifier = "4A948A647051C7F562559711461EE3E76C2F67A4BA7BF34B1E61EA583BDE9CC4"; // Apple Merchant Identifier
var order_id = "ORDER-12345";
var order_amount = "10.00";
var order_currency = "SAR";

// Function to reverse string
const ReverseString = str => [...str].reverse().join('');

// 1. Concatenate values
var concatenated = identifier + order_id + order_amount + order_currency + password;

// 2. Reverse
var reversed = ReverseString(concatenated);

// 3. Uppercase
var upper = reversed.toUpperCase();

// 4. MD5 hash
var finalHash = CryptoJS.MD5(upper).toString();

console.log(finalHash);

// Save hash in Postman environment
postman.setEnvironmentVariable('operation_hash', finalHash);

💡
Tip: Integrate this script into the Pre-request Script tab within Postman to automatically generate the operation_hash prior to sending the request.

Hash Calculation

The hash field is crucial for ensuring the integrity and authenticity of the request.

Formula:

hash = MD5( Reverse(identifier + order_id + order_amount + order_currency + password).toUpperCase() )

Steps:

Concatenate the identifier, order_id, order_amount, order_currency, and your merchant password.
Reverse the resultant concatenated string.
Convert the reversed string to uppercase.
Apply MD5 hashing to the uppercase string.
Utilize the generated hash value in the request.

Sample Response

{
  "status": "success",
  "code": "000.000.000",
  "message": "Transaction succeeded",
  "data": {
    "transaction_id": "TXN-789654123",
    "order_id": "ORDER-12345",
    "amount": "10.00",
    "currency": "SAR",
    "payment_brand": "applepay",
    "result": "APPROVED",
    "descriptor": "EdfaPay ApplePay Purchase",
    "timestamp": "2025-08-15T11:32:45Z",
    "auth_code": "123456",
    "reference_id": "20250815113245",
    "redirect_url": "https://merchant.example.com/payment-return",
    "payer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]"
    }
  }
}

{
  "status": "error",
  "code": "200.300.404",
  "message": "Invalid payment token",
  "data": {
    "order_id": "ORDER-12345",
    "amount": "10.00",
    "currency": "SAR",
    "payment_brand": "applepay",
    "result": "DECLINED",
    "timestamp": "2025-08-15T11:35:20Z"
  }
}

💡
Notes for Merchants:

It is crucial to validate the result field; "APPROVED" indicates a successful payment.

Retain the transaction_id and reference_id for purposes of refunds and comprehensive transaction tracking.

Utilize the code and message fields for effective troubleshooting of errors with EdfaPay support.