Saltar al contenido principal

Retiros (Pay Out)

Este módulo permite a los Proveedores de Pago (Payment Providers) procesar solicitudes de retiro de efectivo iniciadas por usuarios de Pago46. El flujo está diseñado para garantizar la atomicidad de la transacción y evitar duplicidad en la entrega de fondos mediante un mecanismo de bloqueo (locking).

Endpoint Base

Todas las rutas descritas a continuación son relativas a la URL base de la API: /api/v1

Registro de Redes de Pago​

Antes de procesar transacciones, los proveedores deben registrar las redes de pago que utilizan. Cada red debe tener un identificador único (provider_network_id) que se utilizará en todas las transiciones de estado.

Ejemplo de IDs de Red:

  • 01
  • oxxo_network
  • seven_eleven_mx
  • farmacia_abc
  • network_123
Contacto

Para registrar tus redes de pago, contacta al equipo de integración de Pago46. Los IDs que proporciones serán los que deberás usar en las solicitudes de cobro.

Ciclo de Vida de la Orden​

El proceso se rige por un cambio estricto de estados para asegurar que el dinero solo se entregue una vez.

  1. Consulta (Check): El proveedor verifica si el código entregado por el usuario es válido y la orden está en estado READY.
  2. Bloqueo (Start Payment): El proveedor "toma" la orden. Esto cambia el estado a PAYMENT_STARTED. En este punto, ningún otro proveedor puede procesar esta orden.
  3. Confirmación (Confirm Payment): Una vez entregado el dinero, el proveedor confirma la transacción, pasando la orden a COMPLETED.

1. Verificar Orden​

El primer paso ocurre cuando el usuario presenta su código de retiro en el punto físico. Debes consultar los detalles de la orden para validar el monto y su disponibilidad.

Endpoint: GET /providers/orders/pay-out/{code}/

ParámetroUbicaciónDescripción
codePathEl código numérico o alfanumérico proporcionado por el usuario final.
curl -X GET "https://api.sandbox.pago46.io/api/v1/providers/orders/pay-out/1234567890/" \
  -H "Provider-Key: <TU_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>"
Validación de Estado

Solo debes proceder al siguiente paso si el campo status es READY. Si recibes CANCELLED, COMPLETED o EXPIRED, debes informar al usuario que la orden no puede ser procesada.

2. Iniciar Pago (Bloqueo)​

Este es el paso más crítico. Al ejecutar este endpoint, estás indicando que tienes la intención de pagar la orden. El sistema bloqueará la orden para tu proveedor y cambiará su estado a PAYMENT_STARTED.

Si otro proveedor intenta iniciar el pago de la misma orden simultáneamente, recibirá un error indicando que la orden ya está siendo procesada.

Endpoint: POST /providers/orders/pay-out/{code}/start-payment/

curl -X POST "https://api.sandbox.pago46.io/api/v1/providers/orders/pay-out/1234567890/start-payment/" \
  -H "Provider-Key: <TU_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "LocalCurrencyOrder",
    "provider_network_id": "network_123",
    "price": "1500.00",
    "price_currency": "MXN"
  }'
CampoTipoDescripción
order_typestringTipo de orden (LocalCurrencyOrder o ForeignCurrencyOrder).
provider_network_idstringID de la red de pago utilizada por el proveedor. Requerido para órdenes LocalCurrencyOrder.
pricestringMonto exacto que se va a entregar. Debe coincidir con el price de la orden. Requerido para órdenes LocalCurrencyOrder.
price_currencystringCódigo de moneda (ej. MXN, USD). Debe coincidir con el price_currency de la orden. Requerido para órdenes LocalCurrencyOrder.
Subredes para Proveedores

Como proveedor, debes suministrar el provider_network_id que identifica la red específica utilizada para procesar esta transacción. Esto permite a Pago46 mantener un registro detallado de qué red procesó cada pago y proporcionar esta información al usuario final.

Operación Segura

Una vez recibes el 200 OK con status PAYMENT_STARTED, es seguro proceder a la entrega física del dinero o la gestión interna de fondos. La orden está reservada para ti.

3. Confirmar Pago (Finalización)​

Una vez que el dinero ha sido entregado exitosamente al usuario (o la transacción interna ha finalizado), debes confirmar la operación para cerrar la orden definitivamente.

Endpoint: POST /providers/orders/pay-out/{code}/confirm-payment/

curl -X POST "https://api.sandbox.pago46.io/api/v1/providers/orders/pay-out/1234567890/confirm-payment/" \
  -H "Provider-Key: <TU_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "LocalCurrencyOrder",
    "provider_network_id": "network_123",
    "price": "1500.00",
    "price_currency": "MXN"
  }'

Al recibir esta respuesta, notificaremos al usuario final que su transacción ha concluido exitosamente.

Cancelación (Opcional)​

Si por alguna razón (insuficiencia de fondos en caja, error operativo), no puedes completar el pago después de haber ejecutado el start-payment, debes liberar la orden para no dejarla bloqueada indefinidamente.

Endpoint: POST /providers/orders/pay-out/{code}/cancel-payment/

Esto devolverá la orden a un estado donde (dependiendo de la lógica de negocio) podría ser cancelada definitivamente o reintentada.

curl -X POST "https://api.sandbox.pago46.io/api/v1/providers/orders/pay-out/1234567890/cancel-payment/" \
  -H "Provider-Key: <TU_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "LocalCurrencyOrder",
    "provider_network_id": "network_123",
    "price": "1500.00",
    "price_currency": "MXN"
  }'

Resumen de Estados​

EstadoDescripciónAcción Requerida del Proveedor
READYLa orden está lista para ser pagada.Puede llamar a start-payment.
PAYMENT_STARTEDLa orden está bloqueada por un proveedor.Debe entregar el dinero y llamar a confirm-payment.
COMPLETEDEl flujo terminó exitosamente.No requiere acción. Historico.
CANCELLEDLa orden fue anulada.No entregar dinero.