Pular para o conteúdo principal

Apple Pay

Este guia cobre o fluxo de comunicação entre um Storefront Headless, a biblioteca Adyen Web e o VTEX Payment Provider Protocol (PPP) para pagamentos com Apple Pay.

Como os storefronts headless controlam sua própria interface, os desenvolvedores precisam orquestrar manualmente a extração de dados do VTEX, a renderização dos Componentes Adyen e as chamadas de API ao backend do Conector VTEX.

Configuração do Apple Pay

Antes de integrar o Apple Pay em um storefront headless, certifique-se de que o Apple Pay está corretamente configurado na sua Área do Cliente Adyen e na conta VTEX. Consulte o guia de configuração do Apple Pay para o processo completo.

Extraindo credenciais do Apple Pay​

Dentro do appPayload retornado pelo gateway callback (veja o Passo 2), extraia as credenciais do Apple Pay:

const { paymentMethods, authorization, countryCodeISO2 } = parsedPayload

const applePaymentMethods = paymentMethods.paymentMethods.find(
  payments => payments.type === 'applepay'
)

const appleMerchantName = applePaymentMethods
  ? applePaymentMethods.configuration.merchantName
  : ''

const appleMerchantId = applePaymentMethods
  ? applePaymentMethods.configuration.merchantId
  : ''

Use esses valores no objeto paymentMethodsConfiguration ao inicializar o AdyenCheckout:

paymentMethodsConfiguration: {
  applepay: {
    amount: {
      value: Math.round(authorization.value * 100),
      currency: authorization.currency,
    },
    countryCode: countryCodeISO2,
    configuration: {
      merchantName: appleMerchantName,
      merchantId: appleMerchantId,
    },
  },
}

Passo 1: Salvar Informações do Navegador​

No início do processo de checkout (antes de o usuário finalizar o pedido), seu frontend deve enviar as informações do navegador do comprador ao conector backend. Esses dados são obrigatórios para fluxos de 3D Secure (3DS).

Como os storefronts headless rodam em um domínio diferente da API VTEX (que bloqueia cookies de sessão entre domínios), você deve passar explicitamente o orderformId no corpo da requisição.

Endpoint: POST https://{sua-conta-vtex}.myvtex.com/api/io/_v3/api/save-checkout-info

Payload:

{
  "browserInfo": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
    "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
    "language": "pt-PT",
    "colorDepth": 32,
    "screenHeight": 748,
    "screenWidth": 1707,
    "timeZoneOffset": -3,
    "javaEnabled": false
  },
  "origin": "https://www.sua-loja-headless.com",
  "orderformId": "10928nr01927rb6basdb61"
}
dica

Capture os dados do navegador dinamicamente usando os objetos navigator e window.screen do browser.

Passo 2: Realizar o Pedido e Extrair o appPayload​

Quando o usuário clicar em "Finalizar Pedido", chame a API padrão de Place Order da VTEX e, em seguida, chame /api/checkout/pub/gatewayCallback/${orderGroupId} para obter o appPayload. Esse payload contém todos os dados de configuração gerados pelo conector para inicializar os componentes Adyen.

Exemplo de appPayload parseado:

{
  "authorization": {},
  "merchantName": "Test",
  "paymentType": "applepay",
  "environment": "test",
  "action": false,
  "lineItems": [
    {
      "quantity": "1",
      "taxPercentage": "0",
      "productUrl": "",
      "imageUrl": "",
      "amountIncludingTax": "25",
      "id": "123",
      "description": "test"
    }
  ],
  "paymentMethods": {}
}

Passo 3: Gerenciando Eventos do Componente Adyen​

onSubmit​

Disparado quando o comprador envia os dados de pagamento.

Objetivo: iniciar a autorização do pagamento.

Endpoint: POST /api/io/_v/api/payment-authorization

Payload:

{
  "paymentMethod": {},
  "authorization": {}
}

Passe a resposta da API ao componente usando component.handleAction(data) quando necessário (ex: 3DS, redirects).

onChange​

Disparado quando o estado do componente muda e se torna válido. Usado para métodos de pagamento que não possuem botão de submit explícito.

Endpoint: POST /api/io/_v/api/payment-authorization

Payload:

{
  "paymentMethod": {},
  "authorization": {}
}

Trate a resposta com component.handleAction(data).

onAdditionalDetails​

Disparado quando a Adyen requer informações adicionais (ex: autenticação 3D Secure).

Objetivo: concluir a etapa de autenticação do pagamento.

Endpoint: POST /api/io/_v/api/payment-details

Payload:

{
  ...state.data,
  ...authorization
}

Com base na resposta, resolva o fluxo de pagamento (sucesso ou falha).

Polling de Status do Pagamento​

Chame este endpoint em intervalos (ex: a cada 5 segundos) enquanto o status estiver pendente.

Endpoint: POST /api/io/_v/api/payment-status

Payload:

{
  "paymentId": "identificador do pagamento"
}

Trate os seguintes status como bem-sucedidos:

  • Authorised
  • Received
  • Pending (dependendo da sua lógica de negócio)

Qualquer outro status deve ser tratado como falha ou recusa.

Passo 4: Tratando 3DS e Redirects Externos​

Quando um usuário passa por um desafio 3D Secure ou utiliza uma carteira externa, ele é redirecionado para fora do seu storefront. Após a autenticação, o Gateway de Pagamentos VTEX emite um redirect 302 hardcoded para:

/checkout/orderPlaced/?og={orderGroup}

Sua aplicação headless deve implementar uma rota em /checkout/orderPlaced. Esta página deve:

  1. Capturar o parâmetro og (Order Group) da URL.
  2. Buscar os detalhes do pedido usando a API de Orders da VTEX (se necessário).
  3. Exibir sua UI customizada de "Confirmação de Pedido".
perigo

Se você não criar essa rota, os usuários que retornarem de validações 3DS encontrarão um erro 404 no seu storefront headless.