Acepta pagos con Yape

🚧 Early Release — Beta

Este producto está en acceso temprano. Los parámetros, estructuras de respuesta y comportamientos pueden cambiar sin previo aviso. No uses esta versión en producción sin coordinarlo previamente con el equipo de integraciones de Kushki.

Acepta pagos aprobados en la app de Yape, por redirección o notificación push

Yape es uno de los procesadores de APM (métodos alternativos de pago) en Perú: en lugar de redirigir al pagador a su banca electrónica, el pago se aprueba directamente en la app de Yape, por redirección directa a la app (DEEPLINK, cuando el pagador compra desde mobile) o mediante una notificación push al número Yape del pagador (PUSH, cuando compra desde web o desktop).

Qué procesadores tiene tu comercio lo responde la consulta de configuración (GET /transfer/v1/config) — el modelo completo está en ¿Cómo funcionan los pagos con APM?. Las integraciones existentes de transferencia bancaria no cambian: siguen su guía de transferencias bancarias.

Importante

Disponible exclusivamente para Perú, en soles (PEN), con el procesador Yape configurado en tu MID. Para habilitarlo, contacta a tu ejecutivo de cuenta.

Así es la experiencia de pago de tu cliente

La experiencia cambia según el canal desde el que compra tu cliente.

Desde mobile (DEEPLINK)

Desde web o desktop (PUSH)

El pagador compra desde su celular, toca Pagar con Yape y se abre directamente la app de Yape, donde aprueba el pago.

Experiencia de pago con Yape desde mobile (DEEPLINK): el cliente elige Yape, se abre la app para aprobar y el pago queda aprobado

Detalles de operación

Parámetro	Detalle
Moneda	PEN
Tipo de integración	100% API — el token se solicita desde tu backend. Kajita y Kushki.js aún no soportan este flujo.
Campo adicional requerido	El objeto `processor` (`name` + `flowType`) en el cuerpo del token
Flujos disponibles	`DEEPLINK` (mobile) · `PUSH` (web / desktop)
Campo extra del flujo PUSH	`phoneNumber` — número celular del pagador asociado a su cuenta Yape
Resultado del init	`deepLink` para redirigir al pagador (`DEEPLINK`) · confirmación del envío con `ticketNumber` y `consentId` (`PUSH`)
Consulta de listado de bancos	No requerida para este flujo

1. Consulta tus procesadores

Este paso es opcional si Yape es tu único procesador, pero recomendado siempre: será la regla a medida que se habiliten más procesadores y flujos. Antes de tokenizar, llama a Consulta la configuración de Transfer In (GET /transfer/v1/config) con tu credencial pública. La entrada de Yape llega con supportedFlows: copia su name y el type del flujo elegido en el objeto processor del token.

{
  "processors": [
    {
      "name": "Yape Processor",
      "currency": "PEN",
      "supportedFlows": [
        { "type": "DEEPLINK", "name": "Deeplink", "description": "Mobile: redirección directa a la app de Yape" },
        { "type": "PUSH", "name": "Push", "description": "Web / Desktop: notificación push al número Yape del pagador" }
      ]
    }
  ]
}

2. Elige el flujo según el canal del pagador

`flowType`	Canal	Cómo funciona	Campo adicional
`DEEPLINK`	Mobile	El pagador es redirigido directamente a la app de Yape, instalada en su celular, para aprobar el pago.	—
`PUSH`	Web / Desktop	El pagador ingresa su número de celular en tu checkout y Yape le envía una notificación push a su app, donde aprueba la compra desde la opción Aprobar compras.	`phoneNumber` requerido.

3. Crea el token

Realiza la petición del token usando el mismo endpoint que el flujo tradicional (POST /transfer/v1/tokens, con tu credencial pública). Incluye el objeto processor con las propiedades name y flowType, copiadas exactamente de la respuesta de la consulta de procesadores.

Campos requeridos

Campo	Tipo	Descripción
`amount.subtotalIva0`	number	Monto de la transacción sin impuestos
`amount.subtotalIva`	number	Monto gravado de la transacción
`amount.iva`	number	Valor del IVA (0 si no aplica)
`currency`	string	Moneda. Debe ser `"PEN"`
`processor.name`	string	Debe ser `"Yape Processor"`, exactamente como lo devuelve la consulta de procesadores — sin alias cortos
`processor.flowType`	string	`"DEEPLINK"` o `"PUSH"`. No tiene valor por defecto: elige según el canal del pagador
`phoneNumber`	string	Solo con `flowType: "PUSH"`. Número celular del pagador asociado a su cuenta Yape; es el destino de la notificación push

El objeto processor no admite propiedades adicionales: cualquier otra propiedad produce 400.

Campos opcionales

callbackUrl · documentType · documentNumber · paymentDescription · email

Ejemplo con flujo PUSH:

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 54.56,
    "iva": 10
  },
  "currency": "PEN",
  "processor": {
    "name": "Yape Processor",
    "flowType": "PUSH"
  },
  "phoneNumber": "938530546"
}

Ejemplo con flujo DEEPLINK:

{
  "amount": {
    "subtotalIva": 0,
    "subtotalIva0": 54.56,
    "iva": 10
  },
  "currency": "PEN",
  "processor": {
    "name": "Yape Processor",
    "flowType": "DEEPLINK"
  }
}

4. Inicia la transacción

Con el token obtenido, llama a Init Transaction (POST /transfer/v1/init) con tu credencial privada (Private-Merchant-Id), repitiendo el mismo monto del token. El body es el mismo del flujo tradicional; lo que cambia es la respuesta, según el flowType con el que generaste el token.

{
  "token": "{{token}}",
  "amount": { "subtotalIva": 0, "subtotalIva0": 54.56, "iva": 10 },
  "fullResponse": "v2"
}

El token queda ligado al procesador con el que fue generado: si no coincide con el procesador configurado para tu comercio, la respuesta es 422 E046. En ese caso, revisa la consulta de procesadores y regenera el token con el procesador correcto.

Respuesta `201` — flujo `PUSH`

Yape envía la notificación push al phoneNumber que enviaste en el token. La respuesta confirma el envío; el pagador aprueba el pago desde la app de Yape.

{
  "ticketNumber": "9748463867065188",
  "consentId": "4d09b123-84c4-4363-955e-70ac1e58d8e6",
  "transactionReference": "d0d07647-3866-4f95-8cbd-87d46ce08658",
  "details": {
    "status": "initializedTransaction",
    "amount": { "currency": "PEN", "iva": 10, "subtotalIva": 0, "subtotalIva0": 54.56 },
    "created": 1789747994247,
    "description": "-",
    "merchantId": "20000000100000000001",
    "merchantName": "COMERCIO DEMO PERU"
  }
}

Respuesta `201` — flujo `DEEPLINK`

La respuesta incluye además deepLink. Redirige al pagador a esa URL tal como la recibes, sin modificar sus parámetros: en el navegador móvil abre la app de Yape, donde aprueba el pago.

{
  "ticketNumber": "9748582884405310",
  "consentId": "ec9cd71c-63e7-4c58-9860-7589c587adc0",
  "transactionReference": "4ff5221b-8ad8-4728-b35f-cc9d45315f54",
  "deepLink": "https://www.yape.com.pe/app/checkout/oneshotpayment?origin=deeplink-externo&consentId=ec9cd71c-63e7-4c58-9860-7589c587adc0&partnerCode=PEX022",
  "details": {
    "status": "initializedTransaction",
    "amount": { "currency": "PEN", "iva": 10, "subtotalIva": 0, "subtotalIva0": 54.56 },
    "created": 1789748578782,
    "description": "-",
    "merchantId": "20000000100000000001",
    "merchantName": "COMERCIO DEMO PERU"
  }
}

Campo	Flujo	Descripción
`ticketNumber`	`PUSH`, `DEEPLINK`	Número de ticket de la transacción en Kushki.
`consentId`	`PUSH`, `DEEPLINK`	Identificador (UUID) del consentimiento de pago en Yape. Permite correlacionar la aprobación del pagador.
`deepLink`	`DEEPLINK`	Enlace al checkout de Yape. Úsalo tal como se recibe.
`transactionReference`	Ambos	Identificador de la transacción en Kushki. Úsalo para correlacionar el webhook con tu orden.
`details`	Ambos	Solo con `fullResponse: "v2"`: estado, monto, fecha de creación y datos del comercio.

Flujo	Qué haces con la respuesta
`PUSH`	Indica al pagador que apruebe la notificación que le llegó a su app de Yape.
`DEEPLINK`	Redirige al pagador al `deepLink`.

5. Espera el resultado del pago

El pagador aprueba (o no) el pago en la app de Yape. El estado final — aprobado, rechazado o expirado — te llega por el webhook configurado para tu comercio; también puedes consultarlo con Get Status (GET /transfer/v1/status/{token}). Usa transactionReference para correlacionar la notificación con tu orden.

6. Errores

Al operar con el flujo multiprocesador puedes recibir errores de la API en la consulta de procesadores, la tokenización o al iniciar la transacción. Los campos de la respuesta de error son code y message.

Endpoint	HTTP	Código	¿Cuándo ocurre?	¿Qué debe hacer el comercio?
`GET /transfer/v1/config`	`500`	`E002`	Error al consultar la configuración del comercio. Mensaje: «Ha ocurrido un error inesperado.»	Reintenta; si persiste, contacta a soporte.
`POST /transfer/v1/tokens`	`400`	—	El body no cumple el contrato: campo requerido ausente (incluido `phoneNumber` en Yape `PUSH`), valor fuera del enumerado (`processor.name`, `processor.flowType`) o propiedad no permitida dentro de `processor`.	Corrige el body según la consulta de procesadores y el contrato del flujo elegido.
`POST /transfer/v1/init`	`422`	`E046`	El token no es compatible con el procesador resuelto (p. ej., token con `processor` y comercio con otro procesador, o token tradicional y comercio con Yape).	Revisa la consulta de procesadores y regenera el token con el procesador correcto.
Todos	`401`	—	Credencial pública o privada inválida o ausente.	Verifica tus credenciales.

Rechazos de Yape. Cuando Yape declina la transacción, retorna el código 006 con el mensaje «Transacción declinada». Es el único código de rechazo y se usa para todos los casos, por lo que no permite distinguir el motivo.

Acepta pagos con Yape

Así es la experiencia de pago de tu cliente#

Detalles de operación#

1. Consulta tus procesadores#

2. Elige el flujo según el canal del pagador#

3. Crea el token#

4. Inicia la transacción#

Respuesta 201 — flujo PUSH#

Respuesta 201 — flujo DEEPLINK#

5. Espera el resultado del pago#

6. Errores#

Artículos relacionados#