Skip to main content

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:

  1. Comercio da opción de retirar dinero con PAGO46 al consumidor en su website o app.
  2. 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.
  3. 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.
  4. 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.
  5. El comercio completa su lógica interna ya sea descontar dinero de balance de usuario, completar flujo de devolución de dinero, entre otros.
  6. El usuario es re-direccionado a la página de éxito del comercio.

Diagrama de Flujo#

P46 Payment Button flow

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#

NombreTipoDescripción Requerido
amountIntMonto de la orden a cobrar a usuario final. Ejemplo: 1000 Si
currencystringMoneda de la orden a crear. Si el comercio desea recaudar en Chile debe ser CLP. Valores aceptados: USD, CLP, MXN, ARSSi
country_codestringPaís en el cual se desea recaudar. Valores aceptados: ARG, CHL, MEX, ECU, URYSi
descriptionstringDescripción del pago. Este texto será visualizado por el usuario en el comprobante de pago. Ejemplo: Movistar Pago Orden #123456789Si
userstringEmail 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.comNo
merchant_order_idstringID 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_123456789Si
notify_urlstringURL destino donde se harán request de notificaciones cuando la orden cambie de estado. Ejemplo: https://backend.merchant.com/p46_webhook_receiverSi
return_urlstringURL donde el usuario será re-direccionado luego de completar el pago con P46. Ejemplo: https://merchant.com/payment_finished Si
timeoutIntMinutos 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#

NombreValorDescripció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-Typeapplication/jsonSI

Response#

Ejemplo#

{
"id": "a0dd0341-e4e5-45c0-8e99-f3c307402ac5",
"amount": "1000.00",
"description": "Some user description",
"merchant_order_id": "merchant-000001",
"user": "user@mail.com",
"creation_date": "2021-04-12T21:17:20.886425Z",
"payment_date": null,
"return_url": "https://comercio.com/compra-exitosa",
"redirect_url": "https://compras.pago46.com/a0dd0341-e4e5-45c0-8e99-f3c307402ac5",
"status": "awaiting_assignment",
"timeout": 1440,
"currency": "CLP",
"country_code": "CHL",
"notify_url": "https://api.sistema-comercio.com/notificaciones-pago46"
}

Data#

NombreTipoDescripción
idstringID de orden de P46. Este ID puede ser utilizado posteriormente para consultar el estado de una orden
amountstringValor a cobrar de la orden. Mismo valor enviado en la creación
descriptionstringDescripción de la orden. Mismo valor enviado en la creación
merchant_order_idstringID de orden de comercio. Mismo valor enviado en la creación
userstringEmail de usuario consumidor. Mismo valor enviado en la creación
creation_datestringFecha y hora UTC ISO 8601 en de la creación de la orden
statusstringEstado 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#

{
"notification_id": "6cbddcac-67c4-451e-b414-aaa8b5d26117",
"merchant_id": "9B6491261BFB7EE077810FC7744081D",
"date": "1619123747.022237"
}

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#

NombreValorDescripció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-Typeapplication/jsonSI

Ejemplo response#

Cómo se puede apreciar en el siguiente ejemplo de response, el status de la orden ahora es successful.

{
"id": "a0dd0341-e4e5-45c0-8e99-f3c307402ac5",
"price": "1000.00",
"description": "Some user description",
"merchant_order_id": "merchant-000001",
"email": "user@mail.com",
"creation_date": "2021-04-12T21:17:20.886425Z",
"payment_date": null,
"return_url": "https://comercio.com/compra-exitosa",
"redirect_url": "https://compras.pago46.com/a0dd0341-e4e5-45c0-8e99-f3c307402ac5",
"status": "successful",
"timeout": 1440,
"currency": "CLP",
"country_code": "CHL",
"notify_url": "https://api.sistema-comercio.com/notificaciones-pago46"
}

Consulta por ID de Orden#

  • Path: /cashout/order/<order_id>
  • Method: GET

Parámetros Body#

Ninguno.

Parámetros Header#

NombreValorDescripción Requerido
merchant-keyMerchant Key del comercio SI
message-hashHash HMAC SHA256 de autenticación. Más info SI
message-dateUnix milisegundos timestamp SI
Content-Typeapplication/jsonSI

Ejemplo response#

Cómo se puede apreciar en el siguiente ejemplo de response, el status de la orden ahora es successful.

{
"id": "a0dd0341-e4e5-45c0-8e99-f3c307402ac5",
"amount": "1000.00",
"description": "Some user description",
"merchant_order_id": "merchant-000001",
"email": "user@mail.com",
"creation_date": "2021-04-12T21:17:20.886425Z",
"payment_date": null,
"return_url": "https://comercio.com/compra-exitosa",
"redirect_url": "https://compras.pago46.com/a0dd0341-e4e5-45c0-8e99-f3c307402ac5",
"status": "successful",
"timeout": 1440,
"currency": "CLP",
"country_code": "CHL",
"notify_url": "https://api.sistema-comercio.com/notificaciones-pago46"
}

Estados de una Orden#

Una orden puede tener multiples estados dependiendo en que parte del flujo se encuentra el usuario.

statusdescripción
pendingPrimer 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.
cancelOrden ha sido cancelada ya no es válida y se debe considerar como orden no completada exitosamente.
expireOrden expiró en base al timeout especificado para la orden.
acceptedOrden 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.

NombreImagenLink
P46 texto españolBtn P46 texto españolDescarga PNG
Descarga SVG
P46 texto inglésBtn P46 texto españolDescarga PNG
Descarga SVG
P46 smallBtn P46 texto españolDescarga PNG
Descarga SVG