Exirom Payment API Documentation

Apple Pay lets customers pay using cards stored in their Apple Wallet, authenticated with Face ID, Touch ID, or passcode. Exirom supports three integration paths depending on how much control you need over the checkout experience.

Flow	Certificate Management	Integration Effort	Description
Hosted Apple Pay	Exirom	Minimal	Create a payment intent, redirect to HPP — Apple Pay button appears automatically
Encrypted Payloads	Exirom	Medium	Apple Pay on your own checkout page — request session by account, submit encrypted token via S2S API
Decrypted Payloads	Merchant	High	Manage your own Apple developer account, decrypt the token, send one S2S request

#1. Hosted Apple Pay

The simplest integration. The Exirom Hosted Payment Page displays a native Apple Pay button and handles session management, token collection, and payment submission automatically. No Apple Pay-specific code is required on your side.

#Prerequisites

Apple Pay must be enabled for your merchant account (contact your Account Manager).

Follow the standard HPP Flow — create a payment intent, redirect the customer, and receive the result via webhook.

#2. Encrypted Payloads

Use this flow when you want Apple Pay on your own checkout page without managing Apple certificates. Exirom manages the Apple Pay certificates, validates the payment session, and decrypts the token server-side.

You implement Apple Pay on your own page using the Apple Pay JS API and submit the encrypted token via the S2S API — no payment intent required.

#Prerequisites

Before using the encrypted flow, ensure:

Apple Pay is enabled for your merchant account (contact your Account Manager)
Your payment page domain is registered for Apple Pay domain verification
The domain verification file is hosted at {your-domain}/.well-known/apple-developer-merchantid-domain-association (file provided by Exirom)

#Process Flow

Step	Endpoint	Description
1	`POST /api/v1/apple-pay/merchant-session-by-account`	Request an Apple Pay session, display payment sheet, customer authorizes
2	`POST /api/v1/payments/apm`	Submit payment with the encrypted Apple Pay token

#Step 1: Apple Pay Session & Authorization

When the customer clicks the Apple Pay button on your page, the Apple Pay JS API provides a validationURL. Use it together with your accountId to request a merchant session from Exirom.

POST /api/v1/apple-pay/merchant-session-by-account

See the API Reference: POST /api/v1/apple-pay/merchant-session-by-account for the full request schema.

{
  "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
  "origin": "https://your-checkout-page.com",
  "accountId": 825952981806376569
}

{
  "epochTimestamp": 1775219419078,
  "expiresAt": 1775223019078,
  "merchantSessionIdentifier": "SSH6DBBAF553B6043CBB1F8AE72AD730E13_916962FB55F24D6559E862E979992BD29DCFA5D2BA8AD8D4D893F837596083CA",
  "nonce": "620bc038",
  "merchantIdentifier": "31E2FA2262BD4CBEBFB904F36738900BBA9B3141A2054EF9F53272E58A57601B",
  "domainName": "your-checkout-page.com",
  "displayName": "Your Store Name",
  "signature": "308006092a864886f70d010702a08030800201...truncated...",
  "operationalAnalyticsIdentifier": "Your Store Name:31E2FA2262BD4CBEBFB904F36738900BBA9B3141A2054EF9F53272E58A57601B",
  "retries": 0,
  "pspId": "EF6B5BB55F74BBA31E58DC6A1E13172751F5956BB11ADFD197D051D1F8BAC517"
}

The response is an opaque Apple Pay session object — pass it directly to the Apple Pay JS API's completeMerchantValidation() method. The customer sees the Apple Pay payment sheet with your merchant name and authorizes with Face ID / Touch ID.

The origin must match one of your registered payment page domains. If it doesn't match, the request will be rejected.

#Step 2: Submit Payment with Encrypted Token

After authorization, the Apple Pay JS API returns an encrypted payment token. Submit it to the S2S API with paymentMethod: APPLE_PAY and the encrypted token in the apmPayload. Do not include the decrypted field — Exirom decrypts the token server-side.

POST /api/v1/payments/apm

See the API Reference: POST /api/v1/payments/apm for the full request schema.

{
  "amount": "10.00",
  "currency": "EUR",
  "requestId": "826070952327953629",
  "accountId": "825952981806376569",
  "apmPayload": {
    "paymentMethod": "APPLE_PAY",
    "paymentType": "MOBILE_WALLET",
    "token": {
      "paymentData": {
        "data": "<encrypted-payment-data>",
        "header": {
          "publicKeyHash": "<public-key-hash>",
          "transactionId": "677231380d2b3dcdbc4c2a2a61f3253e55401cf45a012ab79ada860cd02e0095",
          "ephemeralPublicKey": "<ephemeral-public-key>"
        },
        "version": "EC_v1",
        "signature": "<signature>"
      },
      "paymentMethod": {
        "type": "debit",
        "network": "Visa",
        "displayName": "Visa 3742"
      },
      "transactionIdentifier": "677231380d2b3dcdbc4c2a2a61f3253e55401cf45a012ab79ada860cd02e0095"
    }
  },
  "device": {
    "ip": "41.32.45.67"
  },
  "billingDetails": {
    "firstName": "Hassan",
    "lastName": "Mohamed",
    "email": "hassan.m@example.me",
    "phone": "+201112345678",
    "country": "EG",
    "city": "Cairo",
    "address1": "12 Tahrir Square",
    "postalCode": "11511"
  },
  "callbackUrl": "https://your-server.com/webhooks/payment",
  "successRedirectUrl": "https://your-site.com/success",
  "failureRedirectUrl": "https://your-site.com/failure"
}

{
  "requestId": "826070952327953629",
  "paymentType": "APM",
  "transactionId": "826070956875999958",
  "transactionStatus": "SUCCEED",
  "apmResponseData": {
    "isFinal": true,
    "authCode": "F64ZBA",
    "actionType": "NONE",
    "paymentType": "MOBILE_WALLET",
    "paymentMethod": "APPLE_PAY",
    "providerTransactionId": "payment_170af2fa9d55c596c3a7803fd6f9ef2f"
  }
}

Apple Pay S2S payments return actionType: NONE — no customer redirect is needed.

#3. Decrypted Payloads

Use this flow when you manage your own Apple developer account and Apple Pay certificates. You decrypt the Apple Pay token on your server and send the decrypted token directly to the Exirom S2S API in a single request — POST /api/v1/payments/apm with paymentMethod: APPLE_PAY and both the original token and decrypted objects in the apmPayload.

#Prerequisites

Before using the decrypted flow, ensure you have:

An Apple developer account with Apple Pay configured
Apple Pay Merchant Identity Certificate (for Apple Pay JS session management)
Apple Pay Payment Processing Certificate (for token decryption)

For the full payload structure, see the Apple Pay Payload reference. For the endpoint schema, see the API Reference: POST /api/v1/payments/apm.

{
  "amount": "0.10",
  "currency": "EUR",
  "requestId": "826059968196931128",
  "accountId": "825952981806376569",
  "apmPayload": {
    "paymentMethod": "APPLE_PAY",
    "paymentType": "MOBILE_WALLET",
    "token": {
      "paymentData": {
        "data": "<encrypted-payment-data>",
        "header": {
          "publicKeyHash": "<public-key-hash>",
          "transactionId": "f8781ec844fa03cf803d0cd1ff113d1f2021196fa6e1347c51ea4e55f303c7ee",
          "ephemeralPublicKey": "<ephemeral-public-key>"
        },
        "version": "EC_v1",
        "signature": "<signature>"
      },
      "paymentMethod": {
        "type": "debit",
        "network": "Visa",
        "displayName": "Visa 3742"
      },
      "transactionIdentifier": "f8781ec844fa03cf803d0cd1ff113d1f2021196fa6e1347c51ea4e55f303c7ee"
    },
    "decrypted": {
      "applicationPrimaryAccountNumber": "<card-pan>",
      "applicationExpirationDate": "311231",
      "currencyCode": "978",
      "transactionAmount": "10",
      "deviceManufacturerIdentifier": "040010030273",
      "paymentDataType": "3DSecure",
      "paymentData": {
        "eciIndicator": "5",
        "onlinePaymentCryptogram": "<cryptogram>"
      }
    }
  },
  "device": {
    "ip": "41.32.45.67"
  },
  "billingDetails": {
    "firstName": "Hassan",
    "lastName": "Mohamed",
    "email": "hassan.m@example.me",
    "phone": "+201112345678",
    "country": "EG",
    "city": "Cairo",
    "address1": "12 Tahrir Square",
    "postalCode": "11511"
  },
  "callbackUrl": "https://your-server.com/webhooks/payment",
  "successRedirectUrl": "https://your-site.com/success",
  "failureRedirectUrl": "https://your-site.com/failure"
}

{
  "requestId": "826059968196931128",
  "paymentType": "APM",
  "transactionId": "826059973015789598",
  "transactionStatus": "SUCCEED",
  "apmResponseData": {
    "isFinal": true,
    "authCode": "5BS7B0",
    "actionType": "NONE",
    "paymentType": "MOBILE_WALLET",
    "paymentMethod": "APPLE_PAY",
    "providerTransactionId": "payment_e5363ba7d4248237e12e62f96fe488f0"
  }
}