Apple Pay session

POST/api/v1/bank/public/charge/applepay/{uuid}/session

Public endpoint

This endpoint is called from the browser during the Apple Pay payment flow. When the user clicks the Apple Pay button, your JavaScript calls ApplePaySession.onvalidatemerchant, which triggers this endpoint to validate A55 as the payment processor with Apple's servers.

---

Request headers

Header	Value	Required
Content-Type	application/json	Yes

Path parameters

Field	Type	Required	Description
uuid	string (UUID)	Yes	Charge UUID for the Apple Pay payment

Request body

Field	Type	Required	Description
validation_url	string	Yes	Apple's merchant validation URL from onvalidatemerchant event
domain	string	Yes	Your website domain (e.g., www.your-store.com)
display_name	string	No	Merchant name shown on Apple Pay sheet

---

Response fields

Field	Type	Description
merchant_session	object	Opaque Apple Pay session object — pass to completeMerchantValidation()
merchant_session.epochTimestamp	number	Session creation timestamp
merchant_session.expiresAt	number	Session expiration timestamp
merchant_session.merchantSessionIdentifier	string	Apple session ID
merchant_session.merchantIdentifier	string	Apple merchant ID

---

HTTP status codes

Status	Description
200	Merchant session created
400	Invalid validation_url or domain
404	Charge not found or not an Apple Pay charge
409	Session already created for this charge
422	Domain not registered with Apple Pay
429	Rate limit exceeded
500	Internal server error

---

Code examples

cURL

curl -s -X POST "https://core-manager.a55.tech/api/v1/bank/public/charge/applepay/a1b2c3d4-e5f6-7890-abcd-ef1234567890/session" \
  -H "Content-Type: application/json" \
  -d '{
    "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
    "domain": "www.your-store.com",
    "display_name": "Your Store"
  }'

Python

import requests

charge_uuid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

try:
    response = requests.post(
        f"https://core-manager.a55.tech/api/v1/bank/public/charge/applepay/{charge_uuid}/session",
        json={
            "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/startSession",
            "domain": "www.your-store.com",
            "display_name": "Your Store",
        },
        headers={"Content-Type": "application/json"},
    )
    response.raise_for_status()
    session = response.json()
    print(f"Session ID: {session['merchant_session']['merchantSessionIdentifier']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Node.js

const chargeUuid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

try {
  const response = await fetch(
    `https://core-manager.a55.tech/api/v1/bank/public/charge/applepay/${chargeUuid}/session`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        validation_url: "https://apple-pay-gateway.apple.com/paymentservices/startSession",
        domain: "www.your-store.com",
        display_name: "Your Store",
      }),
    }
  );

  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  const { merchant_session } = await response.json();
  // Pass to ApplePaySession.completeMerchantValidation(merchant_session)
  console.log(`Session: ${merchant_session.merchantSessionIdentifier}`);
} catch (error) {
  console.error("Apple Pay session failed:", error.message);
}

---

Error response example

{
  "status": "error",
  "message": [
    {
      "code": "DOMAIN_NOT_REGISTERED",
      "source": "applepay",
      "description": "Domain www.your-store.com is not registered for Apple Pay. Register it in the A55 dashboard."
    }
  ]
}

---

Pay charge →Complete the Apple Pay payment after session validation.Create charge →Create an Apple Pay charge from your backend.