Botón Yape: One Shot

Crear un pago con Botón Yape: One Shot en Perú consiste en capturar los datos necesarios del cliente para el pago y hacer una solicitud a través de nuestra API con un Bearer Token y una secretKey. Esta solicitud podrá realizarse tanto para versión web, como para versión mobile. Además, el flujo de pago del cliente también varía ligeramente, dependiendo del dispositivo que esté usando.

1. ¿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 "Paga con Yape", tener una cuenta creada y aprobar la compra desde su aplicación.

El proceso de pago con wallet en Perú consta de las siguientes etapas:

1. Selección de método. Durante el checkout, el cliente elige pagar con Yape en tu sitio web o aplicación.
2. Solicitud. ProntoPaga se comunica con la wallet y genera la solicitud de pago.
3. Aprobación. El flujo de aprobación del pago varía según el dispositivo del cliente y si tu comercio tiene o no activado el servicio de validación de pago de terceros:

🌐 En web:

📱En mobile:

4. Validación. Se valida que la información sea correcta, se hace el pago y el dinero se mueve desde la wallet del cliente hacia la cuenta de tu comercio.
5. Confirmación. Se le informa el resultado de la transacción al cliente. A su vez, tu comercio recibe la confirmación a través de los webhooks que hayas configurado.

2. Versiones

Es posible integrar el servicio Botón Yape: One Shot 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.

3. Validación pago terceros

ProntoPaga cuenta con un servicio de validación de pago de terceros, el cual confirma que el número de teléfono celular ingresado coincida con los datos de la cuenta del cliente, evitando que se realicen pagos de terceros, y maximizando la seguridad de tus transacciones.

Esta validación se asigna de forma automática a ciertos comercios integrados con nosotros. Si deseas activarla o desactivarla, comunícate con nuestro equipo de integración. Toma en cuenta las diferencias que existen en la experiencia del cliente para cada caso. Esas diferencias están descritas en la sección de ¿Cómo funciona? de este artículo, en la parte superior.

👍

Códigos de rechazo

Puedes consultar la tabla completa de códigos de error en la sección de Motivos de rechazo para Validación de terceros

4. Integra la versión web

El front-end será el encargado de recopilar los datos necesarios de tu cliente para procesar el pago, mientras que tu back-end estará integrado con nuestra API, procesando el pago.

4.1. Crea un nuevo pago

De este modo, para crear una solicitud de nuevo pago deberás usar este endpoint y colocar yape_oneshot_payment como método de pago en el body de la solicitud.

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, monto, entre otros.

4.2. Body de la solicitud

A continuación puedes ver un ejemplo del body que se envía en la solicitud de pago.

{
  "currency": "PEN",
  "country": "PE",
  "amount": "100.90",
  "clientName": "John Doe",
  "clientEmail": "[email protected]",
  "clientDocument": "12345678912",
  "paymentMethod": "yape_oneshot_payment",
  "urlConfirmation": "https://www.webhook.com",
  "urlFinal": "https://www.webhook.com",
  "urlRejected": "https://www.webhook.com",
  "order": "XYZ789",
  "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.

4.3. Confirmación de un pago

Una vez que el usuario haya completado el pago, ProntoPaga le mostrará 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 PayIns.

4.4. Devolución de un pago

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": "100.90",
  "urlCallbackRefund": "https://www.webhook.com",
  "sign": "Signature of the parameters"
}

👍

Códigos de error

Puedes consultar la tabla completa de códigos de error en la sección de Motivos de rechazo para Validación de terceros

5. Integra la versión mobile

El front-end será el encargado de recopilar los datos necesarios de tu cliente para procesar el pago, mientras que tu back-end estará integrado con nuestra API, procesando el pago.

5.1. Crea un nuevo pago

De este modo, para crear una solicitud de nuevo pago deberás usar este endpoint y colocar yape_oneshot_payment como método de pago en el body de la solicitud. Además, deberás agregar el parámetro clientPhone que identifica el pago de tipo mobile.

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, monto, entre otros.

5.2. Body de la solicitud

A continuación puedes ver un ejemplo del body que se envía en la solicitud de pago.

{
  "currency": "PEN",
  "country": "PE",
  "amount": "100.90",
  "clientName": "John Doe",
  "clientEmail": "[email protected]",
  "clientPhone": "999999999",
  "clientDocument": "12345678912",
  "paymentMethod": "yape_oneshot_payment",
  "urlConfirmation": "https://www.webhook.com",
  "urlFinal": "https://www.webhook.com",
  "urlRejected": "https://www.webhook.com",
  "order": "XYZ789",
  "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.

5.3. Confirmación de un pago

Una vez que el usuario haya completado el pago, ProntoPaga le mostrará 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 PayIns.

5.4. Devolución de un pago

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": "100.90",
  "urlCallbackRefund": "https://www.webhook.com",
  "sign": "Signature of the parameters"
}

👍

Códigos de error

Puedes consultar la tabla completa de códigos de error en la sección de Motivos de rechazo para Validación de terceros

6. Motivos de rechazo

A continuación, se listan los posibles motivos de rechazo para una devolución de pago de tipo One Shot, así como los mensajes que se muestran en pantalla a tu cliente

📘

Notificación de errores

Los errores serán notificados a tu comercio vía webhook. También puedes consultarlos en el Portal de servicios > Transacciones > Payins (pagos), en el campo Nota del detalle de la transacción.

6.1. Motivos de rechazo de validación pago terceros

🚧

Ten en cuenta que

Estos errores solo pueden presentarse en el primer flujo de pago. Luego de la validación de terceros, solo se pueden presentar errores de pago.

A continuación, se listan los posibles motivos de validación de pago de terceros, así como los mensajes que se mostrarán.

6.2. 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.

6.3. Motivos de rechazo de una devolución de pago

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

7. Prueba tu integración

Contamos con demos que simulan la experiencia de pago del cliente, en donde podrás hacer pruebas. Conócelos aquí:

8. Certifica tu integración

La certificación de la integración en sandbox es un paso obligatorio que todos los comercios deben realizar antes de recibir sus credenciales de producción. Su propósito es asegurar que la integración cumpla con los estándares técnicos, funcionales y de seguridad requeridos por ProntoPaga. Dentro de esta sección, se establecen los requisitos que deben cumplirse sin excepción para que la certificación sea aprobada.

8.1. Requisitos de certificación

A continuación, encontrarás los distintos requisitos necesarios para completar tu certificación: