Saltar al contenido principal

Apple Pay

Esta guía cubre el flujo de comunicación entre un Storefront Headless, la biblioteca Adyen Web y el VTEX Payment Provider Protocol (PPP) para pagos con Apple Pay.

Dado que los storefronts headless controlan su propia interfaz, los desarrolladores deben orquestar manualmente la extracción de datos de VTEX, la renderización de los Componentes Adyen y las llamadas a la API del backend del Conector VTEX.

Configuración de Apple Pay

Antes de integrar Apple Pay en un storefront headless, asegúrese de que Apple Pay esté correctamente configurado en su Área del Cliente de Adyen y en la cuenta VTEX. Consulte la guía de configuración de Apple Pay para el proceso completo.

Extracción de credenciales de Apple Pay​

Dentro del appPayload devuelto por el gateway callback (ver Paso 2), extraiga las credenciales de 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 estos valores en el objeto paymentMethodsConfiguration al inicializar AdyenCheckout:

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

Paso 1: Guardar Información del Navegador​

Al inicio del proceso de checkout (antes de que el usuario realice el pedido), su frontend debe enviar la información del navegador del comprador al conector backend. Estos datos son obligatorios para los flujos de 3D Secure (3DS).

Dado que los storefronts headless se ejecutan en un dominio diferente al de la API de VTEX (que bloquea las cookies de sesión entre dominios), debe pasar explícitamente el orderformId en el cuerpo de la solicitud.

Endpoint: POST https://{su-cuenta-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.su-tienda-headless.com",
  "orderformId": "10928nr01927rb6basdb61"
}
consejo

Capture los datos del navegador de forma dinámica usando los objetos navigator y window.screen del navegador.

Paso 2: Realizar el Pedido y Extraer el appPayload​

Cuando el usuario haga clic en "Realizar Pedido", llame a la API estándar de Place Order de VTEX y, a continuación, llame a /api/checkout/pub/gatewayCallback/${orderGroupId} para obtener el appPayload. Este payload contiene todos los datos de configuración generados por el conector para inicializar los componentes Adyen.

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

Paso 3: Manejo de Eventos del Componente Adyen​

onSubmit​

Se activa cuando el comprador envía los datos de pago.

Objetivo: iniciar la autorización del pago.

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

Payload:

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

Pase la respuesta de la API al componente usando component.handleAction(data) cuando sea necesario (ej: 3DS, redirects).

onChange​

Se activa cuando el estado del componente cambia y se vuelve válido. Se usa para métodos de pago que no tienen un botón de submit explícito.

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

Payload:

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

Gestione la respuesta con component.handleAction(data).

onAdditionalDetails​

Se activa cuando Adyen requiere información adicional (ej: autenticación 3D Secure).

Objetivo: completar el paso de autenticación del pago.

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

Payload:

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

Según la respuesta, resuelva el flujo de pago (éxito o fallo).

Polling de Estado del Pago​

Llame a este endpoint en intervalos (ej: cada 5 segundos) mientras el estado esté pendiente.

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

Payload:

{
  "paymentId": "identificador del pago"
}

Trate los siguientes estados como exitosos:

  • Authorised
  • Received
  • Pending (según su lógica de negocio)

Cualquier otro estado debe tratarse como un fallo o rechazo.

Paso 4: Manejo de 3DS y Redirects Externos​

Cuando un usuario pasa por un desafío 3D Secure o usa una billetera externa, es redirigido fuera de su storefront. Tras la autenticación, el Gateway de Pagos de VTEX emite un redirect 302 fijo hacia:

/checkout/orderPlaced/?og={orderGroup}

Su aplicación headless debe implementar una ruta en /checkout/orderPlaced. Esta página debe:

  1. Capturar el parámetro og (Order Group) de la URL.
  2. Obtener los detalles del pedido usando la API de Orders de VTEX (si es necesario).
  3. Mostrar su UI personalizada de "Confirmación de Pedido".
peligro

Si no crea esta ruta, los usuarios que regresen de validaciones 3DS encontrarán un error 404 en su storefront headless.