Yape On File: One Click Payments

Crear un pago con esta modalidad consiste en hacer una solicitud de afiliación a través de nuestra API. Esta solicitud podrá realizarse tanto para versión web, como para versión mobile. Una vez realizada con éxito, el cliente podrá realizar sus pagos posteriores con un solo clic, a través de su cuenta de Yape.

¿Cómo funciona?

Yape es una aplicación que permite realizar pagos y transferencias de dinero en Perú, utilizando solo el número de celular. Con Yape, los usuarios pueden hacer pagos en línea, recargar saldo en su cuenta o realizar compras en comercios afiliados. Para completar una transacción utilizando este método de pago, el cliente debe seleccionar la opción "Agrega Yape como método de pago", tener una cuenta creada y aprobar la afiliación desde su aplicación.

El proceso de pago con Yape On File: One Click Payment en Perú consta de seis etapas principales:

1. Selección de afiliación. Durante el checkout, el cliente elige la opción de "Agrega Yape como método de pago".
   1. En la versión web, se le pide al cliente ingresar su número de celular y hacer clic en el botón de solicitud de aprobación.
   2. En la versión mobile, el cliente debe hacer clic en el botón de solicitud de aprobación.
2. Solicitud. ProntoPaga se comunica con la wallet y genera la solicitud de afiliación.
3. Aprobación. El cliente accede a su aplicación de Yape, en donde hará el siguiente proceso:
   1. Autenticarse con su clave o Face ID.
   2. Dirigirse a Aprobar compras > Solicitudes por aprobar.
   3. Abrir la solicitud de tu comercio y hacer clic en Aprobar afiliación.
   4. Ingresar el código de validación.
4. Validación y confirmación de la afiliación. Se valida que el código sea correcto. En caso de serlo, se hace la afiliación, la pantalla de tu comercio se actualiza y se muestra el resultado de la transacción. A su vez, tu comercio recibe la confirmación a través de los webhooks que hayas configurado.
5. One Click Payment. Ahora el cliente puede ver en el checkout la sección de "Métodos de pago guardados", con su cuenta Yape. Al elegirla, comienza el proceso de pago, y el dinero se mueve desde la wallet del cliente hacia la cuenta de tu comercio.
6. Confirmación del One Click Payment. La pantalla de tu comercio se actualiza y se muestra el resultado de la transacción. A su vez, tu comercio recibe la confirmación a través de los webhooks que hayas configurado.

Versiones

Es posible integrar el servicio Yape On File: One Click Payment de dos maneras:

• Versión web.
• Versión mobile.

A continuación, verás las instrucciones para la versión web. Más abajo, dentro de esta misma página, verás los pasos para la versión mobile. Para una navegación más rápida, te sugerimos usar el índice de la derecha.

Integra la versión web

El front-end será el encargado de recopilar los datos necesarios de tu cliente para comenzar el proceso de afiliación, mientras que tu back-end estará integrado con nuestra API, procesando la afiliación y el pago.

Crea una afiliación

Para crear una solicitud de afiliación de tipo One Click Payment, deberás usar este endpoint y enviar un body request con los datos necesarios. A continuación, puedes ver un ejemplo del body que se envía en la solicitud:

{
  "origin": "WEB",
  "document": "12345678",
  "phoneNumber": "999999999",
  "webhookUrl": "https://www.webhook.com",
  "type": "ON_DEMAND"
}

Si la afiliación se realizó con éxito, se mostrará el resultado de la transacción en pantalla. A su vez, tu comercio recibirá la confirmación a través de los webhooks que hayas configurado.

🚧

Tiempo de expiración

El cliente debe aprobar la afiliación en menos de 15 minutos. En caso de no hacerse, la afiliación expirará a los 15 minutos.

Crea un One Click Payment

Una vez que tu cliente esté afiliado correctamente, podrá realizar One Click Payments en tu comercio. Para solicitar un pago, deberás usar este endpoint y colocar yape_cof_payment como método de pago en el body de la solicitud, así como agregar el identificador único (UID) de la afiliación de la wallet del cliente en el parámetro walletUID.

La solicitud se envía con tu Bearer Token, así como con tu secretKey. Además, debes incluir los datos necesarios del cliente para hacer el pago, como: nombre, correo electrónico, teléfono, monto, entre otros.

Body de la solicitud

A continuación puedes ver un ejemplo del body que se envía en la solicitud de un One Click Payment:

{
  "currency": "PEN",
  "country": "PE",
  "amount": 100,
  "clientName": "John Doe",
  "clientEmail": "[email protected]",
  "clientPhone": "999999999",
  "clientDocument": "12345678912",
  "paymentMethod": "yape_cof_payment",
  "urlConfirmation": "https://www.webhook.com",
  "order": "1234",
  "walletUID": "01JXNCAK8TX6PNBBN7ZNBSAEJH",
  "sign": "Signature of the parameters"
}

🚧

Límite transaccional

Recuerda que el límite máximo por transacción y por día es de 2000 soles. Esto significa que, si un cliente realiza hoy una compra por ese monto, no podrá hacer otra transacción hasta mañana.

Confirmación de un pago

Una vez que se haya completado el pago, ProntoPaga le mostrará al cliente una ventana con el resultado final de su transacción. Al mismo tiempo, devolverá los datos de la transacción a la URL que especificaste en urlConfirmation.

📘

Notificación del estado de la transacción

Para configurar el webhook que irá en el campo urlConfirmation y recibir notificaciones con el estado de tu transacción, revisa este artículo.

Para confirmar si una transacción fue exitosa, debes verificar que en tu webhook el valor del campo status sea success.

Conoce todos los estados posibles de un pago en el siguiente enlace: Estados de los pay ins.

Motivos de rechazo de un pago

A continuación, se listan los posibles motivos de rechazo para un pago de tipo One Click Payment, así como los mensajes que se muestran en pantalla a tu cliente.

Devolución de un One Click Payment

Para solicitar la devolución de un pago exitoso realizado con este método, usa este endpoint. A continuación, se muestra un ejemplo del body request que debe llevar:

{
  "reference": "1111111111",
  "clientDocument": "12345678912",
  "amount": 300,
  "urlCallbackRefund": "https://www.webhook.com",
  "sign": "Signature of the parameters"
}

Motivos de rechazo de una devolución

A continuación, se listan los posibles motivos de rechazo para una devolución de un pago realizado con este método, así como las acciones de Yape al respecto.

Lista de afiliaciones

Puedes obtener una lista con las afiliaciones activas de cierto cliente, haciendo una consulta con su número de documento. Utiliza este endpoint para ello.

Detalle de una afiliación

Consulta el detalle del estado de una afiliación, usando el identificador único (UID) de la afiliación de la wallet del cliente. Utiliza este endpoint para conocer el detalle.

Cancelar una afiliación

Para cancelar la afiliación de un cliente, y que éste ya no vea asociada su wallet a tu comercio, ni pueda realizar One Click Payments, haz una solicitud a este endpoint.

Para ello, deberás enviar el identificador único (UID) de la afiliación de la wallet del cliente en el path. Una vez finalizado el proceso de cancelación de forma exitosa, el cliente recibirá una notificación push de Yape, confirmando el proceso.

Integra la versión mobile

El front-end será el encargado de recopilar los datos necesarios de tu cliente para comenzar el proceso de afiliación, mientras que tu back-end estará integrado con nuestra API, procesando la afiliación y el pago.

Crea una afiliación

Para crear una solicitud de afiliación de tipo One Click Payment, deberás usar este endpoint y enviar un body request con los datos necesarios. A continuación, puedes ver un ejemplo del body que se envía en la solicitud:

{
  "origin": "MOBILE",
  "document": "12345678",
  "webhookUrl": "https://www.webhook.com",
  "type": "ON_DEMAND"
}

Si la afiliación se realizó con éxito, se mostrará el resultado de la transacción en pantalla. A su vez, tu comercio recibirá la confirmación a través de los webhooks que hayas configurado.

🚧

Tiempo de expiración

El cliente debe aprobar la afiliación en menos de 15 minutos. En caso de no hacerse, la afiliación expirará a los 15 minutos.

Crea un One Click Payment

Una vez que tu cliente esté afiliado correctamente, podrá realizar pagos One Click en tu comercio. Para solicitar un pago, deberás usar este endpoint y colocar yape_cof_payment como método de pago en el body de la solicitud, así como agregar el identificador único (UID) de la afiliación de la wallet del cliente en el parámetro walletUID.

La solicitud se envía con tu Bearer Token, así como con tu secretKey. Además, debes incluir los datos necesarios del cliente para hacer el pago, como: nombre, correo electrónico, teléfono, monto, entre otros.

Body de la solicitud

A continuación puedes ver un ejemplo del body que se envía en la solicitud de un One Click Payment:

{
  "currency": "PEN",
  "country": "PE",
  "amount": 100,
  "clientName": "John Doe",
  "clientEmail": "[email protected]",
  "clientPhone": "999999999",
  "clientDocument": "12345678912",
  "paymentMethod": "yape_cof_payment",
  "urlConfirmation": "https://www.webhook.com",
  "order": "1234",
  "walletUID": "01JXNCAK8TX6PNBBN7ZNBSAEJH",
  "sign": "Signature of the parameters"
}

🚧

Límite transaccional

Recuerda que el límite máximo por transacción y por día es de 2000 soles. Esto significa que, si un cliente realiza hoy una compra por ese monto, no podrá hacer otra transacción hasta mañana.

Confirmación de un pago

Una vez que se haya completado el pago, ProntoPaga le mostrará al cliente una ventana con el resultado final de su transacción. Al mismo tiempo, devolverá los datos de la transacción a la URL que especificaste en urlConfirmation.

📘

Notificación del estado de la transacción

Para configurar el webhook que irá en el campo urlConfirmation y recibir notificaciones con el estado de tu transacción, revisa este artículo.

Para confirmar si una transacción fue exitosa, debes verificar que en tu webhook el valor del campo status sea success.

Conoce todos los estados posibles de un pago en el siguiente enlace: Estados de los pay ins.

Motivos de rechazo de un pago

A continuación, se listan los posibles motivos de rechazo para un pago de tipo One Click Payment, así como los mensajes que se muestran en pantalla a tu cliente.

Devolución de un One Click Payment

Para solicitar la devolución de un pago exitoso realizado con este método, usa este endpoint. A continuación, se muestra un ejemplo del body request que debe llevar:

{
  "reference": "1111111111",
  "clientDocument": "12345678912",
  "amount": 300,
  "urlCallbackRefund": "https://www.webhook.com",
  "sign": "Signature of the parameters"
}

Motivos de rechazo de una devolución

A continuación, se listan los posibles motivos de rechazo para una devolución de un pago realizado con este método, así como las acciones de Yape al respecto.

Lista de afiliaciones

Puedes obtener una lista con las afiliaciones activas de cierto cliente, haciendo una consulta con su número de documento. Utiliza este endpoint para ello.

Detalle de una afiliación

Consulta el detalle del estado de una afiliación, usando el identificador único (UID) de la afiliación de la wallet del cliente. Utiliza este endpoint para conocer el detalle.

Cancelar una afiliación

Para cancelar la afiliación de un cliente, y que éste ya no vea asociada su wallet a tu comercio, ni pueda realizar One Click Payments, haz una solicitud a este endpoint.

Para ello, deberás enviar el identificador único (UID) de la afiliación de la wallet del cliente en el path. Una vez finalizado el proceso de cancelación de forma exitosa, el cliente recibirá una notificación push de Yape, confirmando el proceso.