Apple Pay

Quick Reference

WhatApple Pay

Why1-tap checkout with biometric auth — higher conversion, lower fraud, tokenized card data

Reading Time15–30 min

DifficultyIntermediate

PrerequisitesAuthentication → Credit card

Activation required

Apple Pay requires activation per country, currency, and account. Contact tech.services@a55.tech to verify availability and register your merchant.

Why Apple Pay

Advantage	Detail
1-tap checkout	Biometric auth replaces manual entry
Higher conversion	Up to 2x vs manual card forms (typical benchmark)
Lower fraud	Tokenized DPAN + cryptogram
Liability shift	Wallet authentication aligns with issuer protections
No card storage	You never persist the real PAN

Method 1 — SDK (native Apple Pay button)

Use this method to let A55's SDK handle the full Apple Pay session on your frontend. Your backend creates a charge first, and the SDK takes the charge_uuid to process the Apple Pay payment natively in Safari.

Prerequisites

Merchant registration: Your merchant must be registered in A55's Apple Pay account. Contact tech.services@a55.tech.
Domain association file: Host the Apple Pay domain verification file at:
```
https://yourdomain.com/.well-known/apple-developer-merchantid-domain-association
```
This file is required on every domain where the Apple Pay button is displayed (Apple Pay on the Web).

Step 1 — Create a charge (no card data)

Create the charge on your backend with type_charge: "applepay" but without card fields or applepay object. The charge is created with status: "issued".

Request:

curl -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "YOUR_MERCHANT_UUID",
    "wallet_uuid": "YOUR_WALLET_UUID",
    "payer_name": "John Does",
    "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
    "due_date": "2025-10-31",
    "installment_count": 1,
    "installment_value": 1,
    "currency": "BRL",
    "items": [
      {
        "sku": "CABXIN-HDMI21-2M-BLK",
        "code": "HDMI21-2M-ULTRA",
        "name": "Cabo HDMI 2.1 Ultra 8K 2m – Cabxin",
        "quantity": 1,
        "description": "Cabo HDMI 2.1 (48 Gbps) compatível com 8K/60Hz e 4K/120Hz",
        "unit_amount": 1,
        "total_amount": 1
      }
    ],
    "webhook_url": "https://webhook-test.com/your-endpoint",
    "type_charge": "applepay"
  }'

Response:

{
  "charge_uuid": "58e6dabd-71fe-49ed-8f55-ec055648dae7",
  "local_currency": 1,
  "currency": "BRL",
  "usd_currency": 0.2,
  "type": "applepay",
  "date": "2026-04-16",
  "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
  "due_date": "2025-10-31",
  "status": "issued",
  "installment_count": 1,
  "charge_payment_url": "https://pay.a55.tech/charge/v2/58e6dabd-71fe-49ed-8f55-ec055648dae7",
  "reference_external_id": "5807d23d-38b4-42c6-97fc-6e68dc6eded0",
  "is_async": false
}

Step 2 — Render the Apple Pay button with the SDK

Pass the charge_uuid from Step 1 to A55Pay.startApplePay(). The SDK handles the Apple Pay session, merchant validation, token exchange, and authorization with the acquirer.

<!-- Official Apple Pay button (Safari 12.1+) -->
<apple-pay-button
  id="apple-pay-btn"
  buttonstyle="black"
  type="pay"
  locale="en-US"
  style="display:none; --apple-pay-button-width:240px; --apple-pay-button-height:44px; --apple-pay-button-border-radius:8px;"
></apple-pay-button>

<script src="https://cdn.jsdelivr.net/npm/a55pay-sdk/dist/a55pay-sdk.min.js"></script>
<script>
  var btn = document.getElementById('apple-pay-btn');

  // Show button only if Apple Pay is available
  if (A55Pay.isApplePayAvailable()) {
    btn.style.display = 'inline-block';
  }

  btn.addEventListener('click', function () {
    A55Pay.startApplePay({
      chargeUuid: 'CHARGE_UUID_FROM_STEP_1',
      countryCode: 'US',
      amount: 1.00,
      currencyCode: 'BRL',           // default: 'BRL'
      merchantDomain: 'pay.a55.tech', // default: 'pay.a55.tech'
      displayName: 'Your Company',    // default: 'A55Pay'
      supportedNetworks: ['visa', 'masterCard', 'elo', 'amex'],

      onSuccess: function (result) {
        console.log('Payment approved:', result);
        // Redirect to confirmation page or update UI
      },

      onError: function (error) {
        console.error('Payment error:', error.message);
        // Show error message to user
      },

      onClose: function () {
        console.log('User cancelled payment');
        // Restore UI to initial state
      },
    });
  });
</script>

SDK flow

Method 2 — Server-side (decrypted data)

Use this method when your backend already decrypts the Apple Pay token. Send the decrypted card data directly to the A55 API to create and authorize the charge in a single step.

How it works:

Customer taps Apple Pay on your frontend.
Apple returns an encrypted payment token.
Your backend decrypts the token to obtain: DPAN (card_number), expiry, CVV, eci, cavv.
Your backend sends a POST /charge with type_charge: "applepay" and the decrypted fields.
A55 authorizes the transaction and returns the result synchronously.

ECI and CAVV required

eci and cavv from the decrypted Apple Pay token are mandatory. Missing or incorrect values cause declines.

Never log wallet data

Never log raw wallet tokens, cavv, or full PAN to analytics or support tickets.

Request

curl -X POST https://sandbox.api.a55.tech/api/v1/bank/wallet/charge/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "YOUR_MERCHANT_UUID",
    "wallet_uuid": "YOUR_WALLET_UUID",
    "payer_name": "John Does",
    "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
    "due_date": "2025-10-31",
    "installment_count": 1,
    "installment_value": 1,
    "currency": "BRL",
    "type_charge": "applepay",
    "card_name": "John Does",
    "card_number": "4111111111111111",
    "card_expiry_year": "2030",
    "card_expiry_month": "08",
    "card_cvv": "123",
    "applepay": {
      "eci": "07",
      "cavv": "AM1mbqehL24XAAa0J04CAoABFA==",
      "type": "credit_card"
    },
    "items": [
      {
        "sku": "CABXIN-HDMI21-2M-BLK",
        "code": "HDMI21-2M-ULTRA",
        "name": "Cabo HDMI 2.1 Ultra 8K 2m – Cabxin",
        "quantity": 1,
        "description": "Cabo HDMI 2.1 (48 Gbps) compatível com 8K/60Hz e 4K/120Hz",
        "unit_amount": 1,
        "total_amount": 1
      }
    ],
    "webhook_url": "https://webhook-test.com/your-endpoint"
  }'

Response

{
  "charge_uuid": "fe5e2c1e-b3fb-4cc4-bb28-004da37d5804",
  "local_currency": 1,
  "currency": "BRL",
  "usd_currency": 0.2,
  "type": "applepay",
  "date": "2026-04-01",
  "description": "#18770 Payments Cabo HDMI 2.1 Ultra 8K",
  "due_date": "2025-10-31",
  "status": "confirmed",
  "message": [],
  "installment_count": 1,
  "installments": [],
  "pix_payload": {},
  "qra_payload": {},
  "applepay_payload": {},
  "charge_payment_url": null,
  "action_url": "",
  "session_id": null,
  "subscription": {},
  "reference_external_id": "e4e3ec12-b51a-4ea2-aceb-2b41602a5a84",
  "is_async": false
}

Status lifecycle

Status	Description
`issued`	Charge created, awaiting Apple Pay SDK processing (Method 1 only)
`confirmed`	Authorization succeeded
`paid`	Confirmed for settlement
`error`	Declined or failed

SDK V2 →A55Pay.startApplePay() and other SDK methods H2H →Card and wallet integration patterns Network token →DPAN and cryptogram flows Create charge →Complete charge schema

Quick Reference

Why Apple Pay​

Method 1 — SDK (native Apple Pay button)​

Prerequisites​

Step 1 — Create a charge (no card data)​

Step 2 — Render the Apple Pay button with the SDK​

SDK flow​

Method 2 — Server-side (decrypted data)​

Request​

Response​

Status lifecycle​