Integración Cash-out
Autenticación HMAC
Toda la comunicación con API de PAGO46 requiere de autenticación HMAC, favor leer la sección Autenticación HMAC antes de continuar con la integración.
Siempre Server-side Requests
Las credenciales (merchant key y secret) nunca deben ser expuestas a usuarios finales no autorizados y toda la comunicación HTTP entre el comercio y PAGO46 debe hacerse Server-side, nunca desde el browser o app del usuario final. Exponer las credenciales puede provocar serias vulnerabilidades de seguridad para el comercio y sus consumidores.
Flujo General#
Un comercio puede utilizar la Red de PAGO46 integrando el botón de Cash-out el cual permite a los consumidores obtener dinero en efectivo ya sea dirigiéndose al punto PAGO46 más cercano o solicitando un Socio46 en su ubicación. Este flujo puede ser utilizado para proveer de dinero en efectivo a consumidores que usen Wallet digitales, cuentas bancarias, cuentas de ahorro, entre otros. También se puede implementar como flujo de devolución de dinero en efectivo. El flujo en términos generales es:
- Comercio da opción de retirar dinero con PAGO46 al consumidor en su website o app.
- El usuario consumidor presiona el botón. El comercio se comunica por API para crear una orden de cash-out. PAGO46 responde URL donde debe ser re-direccionado el usuario.
- Comercio debe re-direccionar al usuario, usuario completa el flujo en PAGO46 donde deberá ingresar su dirección y seleccionar si desea ir a pagar a un punto P46 o solicitar a un Socio46 que entregue el dinero en la dirección del usuario. El usuario puede ser re-direccionado (redirect) o también la página web de PAGO46 puede ser embebida en un web iframe, webview, entre otros.
- Una vez se encuentra consumidor y Socio46, se escanea QR, se entrega el dinero y se completa la transacción. En tiempo real el comercio es notificado para que pueda proceder con el flujo. Importante: La respuesta al request de notificación siempre debe ser HTTP 200 de lo contrario la orden intentará ser re-notificada hasta que se cancele.
- El comercio completa su lógica interna ya sea descontar dinero de balance de usuario, completar flujo de devolución de dinero, entre otros.
- El usuario es re-direccionado a la página de éxito del comercio.
Diagrama de Flujo#
Creación de Orden de Cash-out#
Cuando el usuario del comercio declara su intención de retirar dinero a través de PAGO46, el comercio debe crear una orden para comenzar el flujo, es decir, cuando el usuario hizo click (o touch) sobre la opción de PAGO46 que el comercio debe disponibilizar, se debe crear la orden contra la API P46 y re-direccionar al usuario a la URL que viene en la respuesta. Normalmente los comercios muestran una imagen (botón) donde los usuarios hacen click y este a su vez llama a algún servicio backend del comercio que a su vez crear una orden en PAGO46 y redirecciona al usuario al flujo web de PAGO46.
Cuando el comercio desea que el usuario comience el flujo de pago con P46, primero debe comunicarse con la API para crear una Orden. La API responderá la información necesaria para redireccionar al usuario y también para hacer seguimiento de la orden.
- Path:
/cashout/order/ - Method:
POST
Parámetros Body#
| Nombre | Tipo | Descripción | Requerido |
|---|---|---|---|
| amount | Int | Monto de la orden a cobrar a usuario final. Ejemplo: 1000 | Si |
| currency | string | Moneda de la orden a crear. Si el comercio desea recaudar en Chile debe ser CLP. Valores aceptados: USD, CLP, MXN, ARS | Si |
| country_code | string | País en el cual se desea recaudar. Valores aceptados: ARG, CHL, MEX, ECU, URY | Si |
| description | string | Descripción del pago. Este texto será visualizado por el usuario en el comprobante de pago. Ejemplo: Movistar Pago Orden #123456789 | Si |
| user | string | Email del usuario consumidor al cual se enviará las instrucciones de retiro y comprobante al final del flujo. Se recomienda enviar email para que el usuario tenga menos fricción. Si el email no se envía, P46 solicitará email al usuario en el primer paso del flujo de P46. Ejemplo: consumer@email.com | No |
| merchant_order_id | string | ID de orden del comercio para control interno. Este umero debe ser único o no debe ser repetido en la creación de la orden. Ejemplo: movistar_order_123456789 | Si |
| notify_url | string | URL destino donde se harán request de notificaciones cuando la orden cambie de estado. Ejemplo: https://backend.merchant.com/p46_webhook_receiver | Si |
| return_url | string | URL donde el usuario será re-direccionado luego de completar el pago con P46. Ejemplo: https://merchant.com/payment_finished | Si |
| timeout | Int | Minutos que la orden permanecerá activa desde la creación de la misma. Si el usuario intenta completar la orden después del plazo timeout no podrá hacerlo. Este campo es util cuando el comercio tiene procesos de pago asociados al stock de productos o despachos. Ejemplo: 1440 | No |
Parámetros Header#
| Nombre | Valor | Descripción | Requerido |
|---|---|---|---|
| merchant-key | {merchant-key} | Merchant Key del comercio | SI |
| message-hash | {hash} | Hash HMAC SHA256 de autenticación. Más información | SI |
| message-date | {date} | Unix milisegundos timestamp mismo que se usó para generar Hash | SI |
| Content-Type | application/json | SI |
Response#
Ejemplo#
Data#
| Nombre | Tipo | Descripción |
|---|---|---|
| id | string | ID de orden de P46. Este ID puede ser utilizado posteriormente para consultar el estado de una orden |
| amount | string | Valor a cobrar de la orden. Mismo valor enviado en la creación |
| description | string | Descripción de la orden. Mismo valor enviado en la creación |
| merchant_order_id | string | ID de orden de comercio. Mismo valor enviado en la creación |
| user | string | Email de usuario consumidor. Mismo valor enviado en la creación |
| creation_date | string | Fecha y hora UTC ISO 8601 en de la creación de la orden |
| status | string | Estado en el momento del response de la orden. Ver sección de Estados de una Orden para más información |
Redirect de usuario#
La respuesta de la API (Si es exitosa) contiene un campo llamada redirect_url donde el usuario final debe ser re-direccionado. El usuario continuará el flujo en la plataforma de PAGO46 y una vez finalizado será redireccionado a la URL especificada en el parámetro return_url en la creación de la Orden.
Notificaciones de la Orden#
Cada cambio de estado de una orden será notificado cómo webhook a la url especificada en el parámetro notify_url de la creación de la orden. Información relevante de la orden no será incluida en la notificación, es por eso, que cuando se recibe una notificación se debe consultar la información de la orden con comunicación HMAC.
Ejemplo Notificación Request#
Response HTTP 200 para Notificación Request#
HTTP Status Code 200#
Todo request de notificación debe ser respondida con el HTTP status code 200 de esta forma P46 asume que la notificación ha sido correctamente recepcionada por la contraparte.
HTTP Status Code 4xx#
Si el backend responde cualquier status 4xx la orden se re-intentará notificar algunos minutos más tarde.
HTTP Status Code 5xx#
Si el backend responde cualquier status 5xx se cancelará la orden y no se seguirá re-intentando notificar.
Consulta Estado de Orden#
Consulta por ID de Notificación#
Al cambiar de estado una orden un request será generado desde la plataforma de P46 hacia la URL indicada en el parámetro notify_url en la creación de la orden. Cómo se puede ver en el ejemplo anterior y por razones de seguirdad principalmente para mitigar el riesgo de ataques tipo Man in the Middle, no se comunica ninguna información referente a la orden o de usuarios, y es responsabilidad de la integración por lado del comercio consultar el estado de la orden usando notification_id
- Path:
/merchant/notification/<notification_id> - Method:
GET
Parámetros Body#
Ninguno.
Parámetros Header#
| Nombre | Valor | Descripción | Requerido |
|---|---|---|---|
| merchant-key | {merchant-key} | Merchant Key del comercio | SI |
| message-hash | {hash} | Hash HMAC SHA256 de autenticación. Más información | SI |
| message-date | {date} | Unix milisegundos timestamp mismo que se usó para generar Hash | SI |
| Content-Type | application/json | SI |
Ejemplo response#
Cómo se puede apreciar en el siguiente ejemplo de response, el status de la orden ahora es successful.
Consulta por ID de Orden#
- Path:
/cashout/order/<order_id> - Method:
GET
Parámetros Body#
Ninguno.
Parámetros Header#
| Nombre | Valor | Descripción | Requerido |
|---|---|---|---|
| merchant-key | Merchant Key del comercio | SI | |
| message-hash | Hash HMAC SHA256 de autenticación. Más info | SI | |
| message-date | Unix milisegundos timestamp | SI | |
| Content-Type | application/json | SI |
Ejemplo response#
Cómo se puede apreciar en el siguiente ejemplo de response, el status de la orden ahora es successful.
Estados de una Orden#
Una orden puede tener multiples estados dependiendo en que parte del flujo se encuentra el usuario.
| status | descripción |
|---|---|
pending | Primer estado de una orden cuando recién es creada, se mantendrá en este estado hasta que un agente de P46 acepte ir como delivery o el consumidor se acerque a un punto fijo y complete la orden. |
cancel | Orden ha sido cancelada ya no es válida y se debe considerar como orden no completada exitosamente. |
expire | Orden expiró en base al timeout especificado para la orden. |
accepted | Orden ha sido completada exitosamente, es decir, el usuario consumidor pagó a un agente o en un punto de pago externo y el Pago ya ha sido recepcionado por P46 |
Material gráfico#
A continuación puedes descargar el material gráfico oficial de PAGO46 para integrarlo en el sitio web.
| Nombre | Imagen | Link |
|---|---|---|
| P46 texto español |  | Descarga PNG Descarga SVG |
| P46 texto inglés |  | Descarga PNG Descarga SVG |
| P46 small |  | Descarga PNG Descarga SVG |