> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Requisitos previos (Apple Pay)

> Explica paso a paso la configuración del certificado de Apple Pay, el registro de dominios y la configuración de la conexión en el Dashboard de Yuno.

Usa esta guía para preparar y configurar Apple Pay con Yuno.

* [**Requisitos previos de Apple Developer**](#apple-pay-certificate-options): Según la ruta de certificados que elijas, puede que necesites crear un merchant ID y generar certificados y claves (Own), o registrar los dominios de tu comercio (Yuno).
* [**Configuración del Yuno Dashboard**](#finish-in-the-dashboard): Agrega la conexión de Apple Pay, configura el enrutamiento y habilita Apple Pay en Checkout Builder.

Al terminar, estarás listo para [elegir tu ruta de integración](#next-steps)  (SDK o Direct) para pagos únicos y recurrentes.

## Opciones de certificados de Apple Pay

En el Yuno Dashboard encontrarás tres opciones para los certificados de Apple Pay:

* **Yuno**: Esta opción es para comercios que no tienen una cuenta de Apple Developer ni una app móvil (es decir, que solo operan en la web). En estos casos, debes registrar los dominios de tu comercio para usar los certificados de Yuno. [→ Certificados de Yuno: registra los dominios de tu comercio](#yuno-certificates-register-your-merchant-domains)
* **Own (manual)**: Esta opción es para comercios que tienen una cuenta de Apple Developer y prefieren administrar sus propias claves privadas. Generas y conviertes los certificados manualmente con Keychain Access y OpenSSL (pasos 2 a 9), y luego pegas los valores PEM en el Yuno Dashboard. [→ Certificados propios (manual)](#own-certificates-manual)
* **Own — Yuno generates the CSRs**: Esta opción es para comercios que tienen una cuenta de Apple Developer pero no quieren generar claves privadas ni ejecutar comandos de OpenSSL. Yuno genera por ti las solicitudes de firma de certificado (CSR), tú las subes a Apple y devuelves los certificados firmados. [→ Certificados propios con CSR generados por Yuno](#own-certificates-with-yuno-generated-csrs)

## Certificados propios (manual)

Esta ruta es para comercios que tienen una cuenta de Apple Developer y quieren generar y administrar sus certificados manualmente con Keychain Access y OpenSSL.

### Paso 1: Registra un identificador de comercio

> [!NOTE]
>
> Si usas VTEX como plataforma de e-commerce, deberás configurar tu Merchant ID de Apple Pay. Para ver instrucciones detalladas, consulta la [documentación oficial de VTEX](https://developers.vtex.com/docs/guides/setting-up-merchant-id-in-apple-pay).

En el panel de Apple Developer:

1. Inicia sesión en [Apple Developer](https://idmsa.apple.com/IDMSWebAuth/signin?appIdKey=891bd3417a7776362562d2197f89480a8547b108fd934911bcbea0110d07f757\&path=%2Faccount%2F\&rv=1), ve a **Certificates, Identifiers & Profiles** y luego selecciona **Register a new identifier**.
2. Elige **Merchant IDs**.
3. Ingresa una **Description** (por ejemplo, `Apple Pay Integration`) y un **Identifier** con el formato `merchant.com.y.uno.YourBusinessName`.

### Paso 2: Genera un certificado de procesamiento de pagos

1. Crea un directorio nuevo (por ejemplo, `Downloads/ApplePayFiles`) para guardar los archivos de certificados.
2. Abre **Keychain Access** en tu Mac.
3. Ve a **Keychain Access > Certificate Assistant > Request a Certificate From a Certificate Authority**.

![Menú de Keychain Access con Certificate Assistant abierto y la opción Request a Certificate From a Certificate Authority resaltada](https://mintcdn.com/yuno-3979e326/MTlogjS0_SlxtlJG/images/reference/prerequisites-apple-pay/image1.png?fit=max\&auto=format\&n=MTlogjS0_SlxtlJG\&q=85\&s=e152e798919d4d240192edaee7d5ca8f)

4. Completa el formulario:
   * **Email Address**: tu dirección de email
   * **Common Name**: un nombre para el certificado (por ejemplo, `John Doe ProcessingCertificate`)
   * **CA Email Address**: déjalo en blanco
   * Selecciona **Saved to disk**
   * Marca **Let me specify key pair information**
5. Haz clic en **Continue** y luego guarda el archivo como `CertificateSigningRequestPaymentProcessingCertificate.certSigningRequest` en tu directorio de trabajo.
6. Cuando se te pida la configuración del par de claves, usa:
   * **Key Type**: Elliptic Curve (EC)
   * **Key Size**: 256-bit
   * **Algorithm**: ECDSA

### Paso 3: Obtén y convierte el certificado de procesamiento de pagos

1. Ve a la [lista de Merchant ID de Apple Developer](https://developer.apple.com/account/resources/identifiers/list/merchant).
2. Selecciona tu Merchant ID y haz clic en **Create Certificate** en **Apple Pay Payment Processing Certificate**.
3. Cuando se te pregunte, responde **No** a "Will payments... be processed exclusively in China mainland?"
4. Sube el archivo `CertificateSigningRequestPaymentProcessingCertificate.certSigningRequest`.
5. Descarga el certificado firmado como `apple_pay.cer` y guárdalo en tu directorio.
6. Convierte el certificado al formato PEM:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
openssl x509 -inform DER -in apple_pay.cer -out apple_pay.pem
```

### Paso 4: Exporta la clave privada

1. En **Keychain Access**, busca la clave que creaste (por ejemplo, `John Doe ProcessingCertificate`).
2. Haz clic derecho y elige **Export**.
3. Exporta la clave como un archivo `.p12` (por ejemplo, `JohnDoeProcessingCertificate.p12`) y guárdalo en tu directorio de trabajo.
4. Define una contraseña segura (la usarás en el siguiente paso).
5. Convierte el `.p12` en una clave privada en formato PEM:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
openssl pkcs12 -in JohnDoeProcessingCertificate.p12 -nocerts -nodes | sed -ne '/-BEGIN PRIVATE KEY-/,/-END PRIVATE KEY-/p' > ProcessingCertificatePrivateKey.pem
```

La clave privada se guardará en `ProcessingCertificatePrivateKey.pem`.

### Paso 5: Sube el certificado y la clave a Yuno

1. Abre el [Yuno Dashboard](https://dashboard.y.uno/auth/login) **> Connections > Apple Pay > Connect**
2. Ingresa el contenido de `ProcessingCertificatePrivateKey.pem` en el campo **Payment processing key**.
3. Ingresa el contenido de `apple_pay.pem` en el campo **Payment processing certificate**.

![Cuadro de diálogo Add Apple Pay en Yuno Connections con los campos de clave y certificado de procesamiento de pagos y los campos de identidad del comercio](https://mintcdn.com/yuno-3979e326/BSLLs6mIkbeJ-ThW/images/reference/prerequisites-apple-pay/image2.png?fit=max\&auto=format\&n=BSLLs6mIkbeJ-ThW\&q=85\&s=809eef22abc3fffc31f41a7d9284e0ca)

### Paso 6: Genera un certificado de identidad del comercio

1. Abre **Keychain Access**, ve a **Certificate Assistant > Request a Certificate From a Certificate Authority** e ingresa:

* **Email Address**: tu email
* **Common Name**: por ejemplo, `John Doe MerchantIdentityCertificate`
* Deja **CA Email Address** en blanco
* Selecciona **Saved to disk**

2. Guárdalo como `CertificateSigningRequestMerchantIdentityCertificate.certSigningRequest`.

### Paso 7: Obtén y convierte el certificado de identidad del comercio

1. Ve a la [lista de Merchant ID de Apple Developer](https://developer.apple.com/account/resources/identifiers/list/merchant).
2. Selecciona tu Merchant ID y haz clic en **Create Certificate** en **Apple Pay Merchant Identity Certificate**.
3. Sube el archivo `CertificateSigningRequestMerchantIdentityCertificate.certSigningRequest`.
4. Descarga el certificado firmado como `merchant_id.cer` y guárdalo.
5. Conviértelo a PEM:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
openssl x509 -inform DER -in merchant_id.cer -out merchant_id.pem
```

### Paso 8: Exporta la clave privada de identidad del comercio

1. En **Keychain Access**, busca el certificado creado en el paso 6, por ejemplo, `John Doe MerchantIdentityCertificate`.
2. Haz clic derecho y expórtalo como `JohnDoeMerchantIdentityCertificate.p12`.
3. Define una contraseña segura.
4. Convierte la clave privada a PEM:

```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
openssl pkcs12 -in JohnDoeMerchantIdentityCertificate.p12 -nocerts -nodes | sed -ne '/-BEGIN PRIVATE KEY-/,/-END PRIVATE KEY-/p' > MerchantIdentityCertificatePrivateKey.pem
```

La clave privada estará disponible como `MerchantIdentityCertificatePrivateKey.pem`.

### Paso 9: Sube el certificado y la clave de identidad del comercio

1. Vuelve a tu conexión de Apple Pay en el [Yuno Dashboard](https://dashboard.y.uno/auth/login) y ve al paso **Certificates & domains**.
2. Copia el contenido de `MerchantIdentityCertificatePrivateKey.pem` y pégalo en el campo **Merchant Identity key**.
3. Pega el contenido de `merchant_id.pem` en el campo **Merchant Identity certificate**.

![Cuadro de diálogo Add Apple Pay en Yuno Connections con los campos de clave y certificado de identidad del comercio](https://mintcdn.com/yuno-3979e326/BSLLs6mIkbeJ-ThW/images/reference/prerequisites-apple-pay/image3.png?fit=max\&auto=format\&n=BSLLs6mIkbeJ-ThW\&q=85\&s=49597bba668412526ddf7bbc0a920676)

## Certificados propios con CSR generados por Yuno

Esta opción es para comercios que tienen una cuenta de Apple Developer pero no quieren generar claves privadas, ejecutar comandos de OpenSSL ni pegar valores PEM en el Dashboard. Yuno genera por ti ambas solicitudes de firma de certificado (Payment Processing y Merchant Identity). Tú las subes a Apple, descargas los archivos .cer firmados que Apple te devuelve y los subes de nuevo a Yuno desde el formulario de la conexión de Apple Pay.

**Dónde encontrarlo:** En el Yuno Dashboard, abre tu conexión de Apple Pay y ve al paso **Certificates & domains**. Cuando estás creando la conexión, el paso aparece justo después de las credenciales; en una conexión existente, ábrela y ve al mismo paso.

### Paso 1: Ingresa tu Apple Merchant ID

En el campo **Your Apple Merchant ID**, ingresa el Merchant ID que registraste en el Apple Developer Portal (por ejemplo, `merchant.com.example.app`).

> [!NOTE]
>
> Encuentra tu Apple Merchant ID en tu Apple Developer Portal → Certificates, Identifiers & Profiles → Merchant IDs.

### Paso 2: Genera el CSR de Payment Processing

Apple Pay requiere dos certificados independientes. El Payment Processing Certificate es un certificado ECC P-256 que Apple usa para cifrar el token de pago que recibe tu tienda.

> [!NOTE]
>
> Apple permite solo un certificado Payment Processing activo por Merchant ID.

Haz clic en **Generate Payment Processing CSR**. Yuno genera la solicitud de firma. Haz clic en **Download .csr file** para guardarla localmente.

### Paso 3: Genera el CSR de Merchant Identity

El Merchant Identity Certificate es un certificado RSA 2048 que se usa para autenticar tu servidor ante Apple mediante mTLS al iniciar una sesión de Apple Pay en la web.

> [!NOTE]
>
> Se permiten varios certificados Merchant Identity activos por Merchant ID.

Haz clic en **Generate Merchant Identity CSR**. Haz clic en **Download .csr file** para guardar localmente el segundo archivo .csr.

### Paso 4: Sube cada .csr a Apple

Repite estos pasos dos veces: una para el CSR de Payment Processing y otra para el CSR de Merchant Identity.

1. Ve a [developer.apple.com](https://developer.apple.com) → **Certificates, Identifiers & Profiles**.
2. Selecciona tu Merchant ID.
3. En **Apple Pay Payment Processing Certificate** (primera vez) o **Apple Pay Merchant Identity Certificate** (segunda vez), haz clic en **Create Certificate**.
4. Cuando se te pregunte, responde **No** a "Will payments… be processed exclusively in China mainland?"
5. Sube el archivo .csr cuando se te pida.
6. Descarga el archivo .cer que te entrega Apple.

Al final tendrás dos archivos .cer: uno para Payment Processing y otro para Merchant Identity.

### Paso 5: Configura la conexión de Apple Pay

1. En **Use certificates**, selecciona **Own — Yuno generates the CSRs**.
2. Elige tu **Merchant Identifier** en la lista desplegable, que ya incluye los CSR que generaste.
3. Completa **Display Name** y **Domain Name**.
4. En **Payment Processing Certificate** → **Apple-issued .cer file**, haz clic en **Choose file** y selecciona el .cer que Apple emitió para Payment Processing.
5. En **Merchant Identity Certificate** → **Apple-issued .cer file**, haz clic en **Choose file** y selecciona el .cer que Apple emitió para Merchant Identity.

![Formulario de conexión de Apple Pay con la opción de certificados propios, el nombre de dominio y los campos para subir los archivos .cer emitidos por Apple](https://mintcdn.com/yuno-3979e326/BSLLs6mIkbeJ-ThW/images/reference/prerequisites-apple-pay/image7.png?fit=max\&auto=format\&n=BSLLs6mIkbeJ-ThW\&q=85\&s=4013ba67af0c9a0328527a324a0a9fd0)

## Certificados de Yuno: registra los dominios de tu comercio

Antes de que el botón de Apple Pay pueda aparecer en tu sitio web, debes registrar cada dominio que lo muestre. Tienes dos opciones:

### Dashboard (recomendado)

Registra tus dominios directamente en el Yuno Dashboard: Yuno registra cada dominio en Apple en tu nombre.

Los dominios pertenecen a la conexión de Apple Pay en la que los registras, así que regístralos en la conexión a la que tu enrutamiento envía los pagos de Apple Pay.

1. En el Dashboard, abre esa conexión de Apple Pay y ve al paso **Certificates & domains**.
2. Abre **Association file**, haz clic en **Download file** y aloja su contenido en cada dominio que vas a registrar (consulta la advertencia a continuación).
3. Haz clic en **Add domain**.
4. Ingresa los dominios donde aparecerá el botón de Apple Pay, **uno por línea** (hasta 10 por conexión). Cada subdominio se registra por separado: `example.com`, `www.example.com` y `checkout.example.com` son tres dominios.

> [!WARNING]
>
> Antes de agregar un dominio, debes alojar el archivo de verificación en él como texto sin formato (no lo dejes como un archivo descargable), usando la siguiente ruta de alojamiento:
>
> `/.well-known/apple-developer-merchantid-domain-association`
>
> Mantén el archivo alojado de forma permanente. Apple lo vuelve a verificar de vez en cuando, y Apple Pay puede dejar de funcionar en un dominio cuyo archivo ya no esté accesible. Un dominio puede alojar un solo archivo de este tipo, por lo que un dominio registrado con el certificado de Yuno tampoco se puede verificar con tu propio Apple Merchant ID.

5. Haz clic en **Add**. Cada dominio aparece en la tabla con el estado **Verifying** mientras Yuno completa el registro en Apple.
6. Cuando el registro es exitoso, el estado cambia a **Active**: el dominio está listo para mostrar Apple Pay. Si muestra **Failed**, verifica que el archivo sea accesible en ese dominio y usa **Retry** en la fila.

> [!NOTE]
>
> Cuando estás creando una conexión nueva, al menos un dominio debe llegar a **Active** antes de que puedas avanzar en el paso, porque Apple Pay no puede procesar un pago hasta que un dominio esté registrado y verificado. Editar una conexión existente nunca se bloquea, por lo que una conexión cuyos dominios fallen más adelante todavía se puede corregir.
>
> Con tu propio certificado no hay una lista de dominios en este paso: registras tus dominios directamente en Apple, con tu propio merchant ID.

### API

Usa los siguientes endpoints para administrar el registro de tus dominios. Register domain devuelve un `id` por dominio: pásalo como `domain_id` para consultar su estado o eliminarlo.

* [Register domain](https://docs.y.uno/reference/domains/register-domain): `POST /v1/payment-methods/domains`
* [Get domain](https://docs.y.uno/reference/domains/get-domain): `GET /v1/payment-methods/{payment_method}/domains/{domain_id}`
* [Delete domain](https://docs.y.uno/reference/domains/delete-domain): `DELETE /v1/payment-methods/{payment_method}/domains/{domain_id}`

La API informa los mismos estados que muestra el Dashboard: `CREATED` es **Verifying**, `REGISTERED` es **Active**, `ERROR` es **Failed** e `INACTIVE` es un dominio eliminado. Los eventos de dominio no se envían por webhook: lee el estado en la respuesta de Register domain y llama a Get domain hasta que deje de ser `CREATED`.

> [!WARNING]
>
> Apple permite 99 nombres de dominio por merchant identifier. Yuno registra un identifier por conexión de Apple Pay, por lo que una conexión contiene como máximo 99 dominios, ya sea que los agregues en el Dashboard o mediante la API. Eliminar un dominio que ya no usas libera su lugar. Si esperas tener más de 99 dominios en una misma conexión (por ejemplo, un dominio por vendedor), contacta a Yuno antes de escalar.

## Finaliza en el Dashboard

Las tres rutas de certificados, Yuno, Own y Own (CSR generados por Yuno), convergen aquí para completar la configuración en el Yuno Dashboard.

### Paso 1: Conecta Apple Pay

1. Inicia sesión en tu [Yuno Dashboard](https://dashboard.y.uno/connections).
2. Ve a **Connections**, busca **Apple Pay** en el catálogo de proveedores y haz clic en **Connect**.
3. Indica un **Name** para la conexión, selecciona **Apple Pay** como **Payment method** y, en la lista desplegable **Use certificates**, selecciona la opción que corresponde a tu configuración:
   * **Yuno**: Yuno administra los certificados en tu nombre de forma automática. No se requiere ninguna configuración adicional de certificados.
   * **Own — paste PEM values** (manual): pega los valores PEM que generaste en los pasos anteriores.
   * **Own — Yuno generates the CSRs**: selecciona esta opción, luego genera las solicitudes de firma y sube los archivos `.cer` emitidos por Apple en el paso **Certificates & domains**, como se describe en la sección [Certificados propios con CSR generados por Yuno](#own-certificates-with-yuno-generated-csrs).
4. Haz clic en **Next**. El paso **Certificates & domains** solicita lo que necesita el tipo de certificado que elegiste: tus dominios con el certificado de Yuno, o la configuración de tu certificado con cualquiera de las dos opciones de certificado propio.
5. Haz clic en **Next** de nuevo y luego completa las dos pantallas siguientes: costos de configuración (opcional) y cuentas.
6. Haz clic en **Save**. Apple Pay se agregará a tus conexiones.

> [!NOTE]
>
> El tipo de certificado no se puede cambiar una vez que existe la conexión, porque lo asociado a un tipo no se traslada al otro. Para cambiarlo, crea una conexión nueva y apunta tu enrutamiento hacia ella.

![Cuadro de diálogo Add Apple Pay en Yuno Connections con pasos de credenciales desplegables y un campo Name](https://mintcdn.com/yuno-3979e326/BSLLs6mIkbeJ-ThW/images/reference/prerequisites-apple-pay/image4.png?fit=max\&auto=format\&n=BSLLs6mIkbeJ-ThW\&q=85\&s=1e62ebeea376cd895090f6b984f8eaa5)

### Paso 2: Configura el enrutamiento

Configura una ruta nueva para controlar cómo se procesan los pagos a través de Apple Pay.

> [!NOTE]
>
> Visita la página de [Routing](https://docs.y.uno/es/docs/using-yuno/dashboard-overview/routing.md) para obtener más información sobre este paso.

1. En el [Yuno Dashboard](https://dashboard.y.uno/), ve a la sección **Routing**.
2. Busca la conexión de **Apple Pay**. Si aún no has creado una ruta para Apple Pay, estará en la pestaña **Not published**.
3. Configura una ruta nueva presionando **Setup** en tu módulo de **Apple Pay** (o **View** si la ruta está publicada) y luego haciendo clic en **Create new route**. Asigna un nombre a la conexión y haz clic en **Save**.
4. Agrega condiciones para especificar cómo se deben enrutar los pagos a través de Apple Pay.
5. Agrega Apple Pay como procesador de pagos de esta ruta para asegurar que los pagos que cumplan las condiciones definidas se procesen a través de Apple Pay.
6. Haz clic en **Publish** para publicar la ruta una vez que todas las configuraciones estén definidas.

Esta es una ruta sencilla que procesa todos los pagos a través de Apple Pay.

![Editor de rutas con All other payments enrutados a una conexión de Apple Pay con los resultados Succeeded, Declined y Error](https://mintcdn.com/yuno-3979e326/BSLLs6mIkbeJ-ThW/images/reference/prerequisites-apple-pay/image5.png?fit=max\&auto=format\&n=BSLLs6mIkbeJ-ThW\&q=85\&s=1f40249e74220b6ab53f5d06728d56f2)

### Paso 3: Habilita Apple Pay en Checkout Builder

> [!NOTE]
>
> Visita la página de [Checkout Builder](https://docs.y.uno/es/docs/using-yuno/dashboard-overview/checkout-builder.md) para obtener más información sobre este paso.

Para que Apple Pay esté disponible para tus usuarios finales, debes habilitarlo en Checkout Builder:

1. En el [Yuno Dashboard](https://dashboard.y.uno/), ve a la sección **Checkout Builder**.
2. Ubica los **Payment methods** disponibles y habilita **Apple Pay**. Haz clic en **Edit** junto a un método de pago para ver opciones adicionales.
3. Haz clic en **Review & publish** para que Apple Pay esté disponible como opción de pago en todas las transacciones que cumplan los criterios de enrutamiento definidos.

![Checkout Builder con Apple Pay habilitado en la lista de métodos de pago y una vista previa del checkout a la derecha](https://mintcdn.com/yuno-3979e326/BSLLs6mIkbeJ-ThW/images/reference/prerequisites-apple-pay/image6.png?fit=max\&auto=format\&n=BSLLs6mIkbeJ-ThW\&q=85\&s=e42fe41b4c2e4cf6a14a3d049aebf963)

> [!NOTE]
>
> Si planeas implementar pagos recurrentes, deberás configurar en tu conexión de Apple Pay una URL adicional donde los clientes puedan administrar sus suscripciones (cancelar, modificar, etc.). Esta URL debe ser creada y alojada por la plataforma de tu comercio.

## Próximos pasos

Después de completar la configuración del Dashboard, elige tu ruta para integrar mediante SDK o Direct:

* **Integración con SDK**: [pago único](https://docs.y.uno/es/docs/wallets/apple-pay/apple-pay-sdk-integration.md#one-time-payments-with-sdk) y [recurrente](https://docs.y.uno/es/docs/wallets/apple-pay/sdk-integration/recurring-payments.md)
* **Integración Direct**: [pago único](https://docs.y.uno/es/docs/wallets/apple-pay/apple-pay-direct-integration.md#one-time-payments)  y [recurrente](https://docs.y.uno/es/docs/wallets/apple-pay/apple-pay-direct-integration.md#recurring-payments-with-direct-api)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.