Apple Pay

Quick Reference

WhatApple Pay

WhyCheckout em 1 toque com autenticação biométrica — maior conversão, menor fraude, dados de cartão tokenizados

Reading Time15–30 min

DifficultyIntermediário

PrerequisitesAutenticação → Cartão de crédito

Ativação necessária

O Apple Pay requer ativação por país, moeda e conta. Entre em contato com tech.services@a55.tech para verificar disponibilidade e registrar seu merchant.

Por que Apple Pay

Vantagem	Detalhe
Checkout em 1 toque	Autenticação biométrica substitui o preenchimento manual
Maior conversão	Até 2x em relação a formulários manuais (benchmark típico)
Menor fraude	DPAN tokenizado + criptograma
Transferência de responsabilidade	A autenticação pela carteira alinha-se às proteções do emissor
Sem armazenamento de cartão	O PAN real nunca é persistido

Método 1 — SDK (botão nativo Apple Pay)

Use este método para deixar o SDK da A55 gerenciar toda a sessão Apple Pay no seu frontend. Seu backend cria a cobrança primeiro, e o SDK utiliza o charge_uuid para processar o pagamento Apple Pay nativamente no Safari.

Pré-requisitos

Cadastro do merchant: Seu merchant deve ser registrado na conta Apple Pay da A55. Entre em contato com tech.services@a55.tech.
Arquivo de associação de domínio: Hospede o arquivo de verificação de domínio Apple Pay em:
```
https://seudominio.com/.well-known/apple-developer-merchantid-domain-association
```
Este arquivo é obrigatório em todo domínio onde o botão Apple Pay é exibido (Apple Pay on the Web).

Etapa 1 — Criar a cobrança (sem dados do cartão)

Crie a cobrança no seu backend com type_charge: "applepay" mas sem campos de cartão ou objeto applepay. A cobrança é criada com status: "issued".

Requisição:

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": "SEU_MERCHANT_UUID",
    "wallet_uuid": "SEU_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/seu-endpoint",
    "type_charge": "applepay"
  }'

Resposta:

{
  "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
}

Etapa 2 — Renderizar o botão Apple Pay com o SDK

Passe o charge_uuid da Etapa 1 para A55Pay.startApplePay(). O SDK gerencia a sessão Apple Pay, validação do merchant, troca de token e autorização com o adquirente.

<!-- Botão oficial Apple Pay (Safari 12.1+) -->
<apple-pay-button
  id="apple-pay-btn"
  buttonstyle="black"
  type="pay"
  locale="pt-BR"
  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');

  // Exibir botão apenas se Apple Pay estiver disponível
  if (A55Pay.isApplePayAvailable()) {
    btn.style.display = 'inline-block';
  }

  btn.addEventListener('click', function () {
    A55Pay.startApplePay({
      chargeUuid: 'CHARGE_UUID_DA_ETAPA_1',
      countryCode: 'BR',
      amount: 1.00,
      currencyCode: 'BRL',            // padrão: 'BRL'
      merchantDomain: 'pay.a55.tech', // padrão: 'pay.a55.tech'
      displayName: 'Sua Empresa',     // padrão: 'A55Pay'
      supportedNetworks: ['visa', 'masterCard', 'elo', 'amex'],

      onSuccess: function (result) {
        console.log('Pagamento aprovado:', result);
        // Redirecionar para página de confirmação ou atualizar UI
      },

      onError: function (error) {
        console.error('Erro no pagamento:', error.message);
        // Exibir mensagem de erro ao usuário
      },

      onClose: function () {
        console.log('Usuário cancelou o pagamento');
        // Restaurar UI ao estado inicial
      },
    });
  });
</script>

Fluxo do SDK

Método 2 — Server-side (dados desencriptados)

Use este método quando seu backend já desencripta o token Apple Pay. Envie os dados do cartão desencriptados diretamente para a API A55 para criar e autorizar a cobrança em uma única etapa.

Como funciona:

O cliente toca no Apple Pay no seu frontend.
A Apple retorna um token de pagamento encriptado.
Seu backend desencripta o token para obter: DPAN (card_number), validade, CVV, eci, cavv.
Seu backend envia POST /charge com type_charge: "applepay" e os campos desencriptados.
A A55 autoriza a transação e retorna o resultado de forma síncrona.

ECI e CAVV obrigatórios

eci e cavv do token Apple Pay desencriptado são obrigatórios. Valores ausentes ou incorretos causam recusas.

Nunca registre dados de carteira

Nunca registre tokens brutos de carteira, cavv ou PAN completo em logs de analytics ou tickets de suporte.

Requisição

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": "SEU_MERCHANT_UUID",
    "wallet_uuid": "SEU_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/seu-endpoint"
  }'

Resposta

{
  "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
}

Ciclo de vida do status

Status	Descrição
`issued`	Cobrança criada, aguardando processamento pelo SDK Apple Pay (somente Método 1)
`confirmed`	Autorização bem-sucedida
`paid`	Confirmado para liquidação
`error`	Recusado ou com falha

SDK V2 →A55Pay.startApplePay() e outros métodos do SDK H2H →Padrões de integração de cartão e carteira Network token →Fluxos de DPAN e criptograma Criar cobrança →Schema completo de cobrança

Quick Reference

Por que Apple Pay​

Método 1 — SDK (botão nativo Apple Pay)​

Pré-requisitos​

Etapa 1 — Criar a cobrança (sem dados do cartão)​

Etapa 2 — Renderizar o botão Apple Pay com o SDK​

Fluxo do SDK​

Método 2 — Server-side (dados desencriptados)​

Requisição​

Resposta​

Ciclo de vida do status​