Saltar al contenido principal

Retiros (Pay Out)

Este módulo permite a los Proveedores de Pago (Payment Providers) procesar órdenes de retiro de efectivo creadas por comercios para sus usuarios. El flujo está diseñado para garantizar la atomicidad de la transacción y evitar entregas duplicadas de efectivo mediante un mecanismo de bloqueo (locking).

Firma cada petición con HMAC SHA-256, revisa el formato de errores para manejar respuestas no exitosas y consulta los países y monedas soportados. Si eres nuevo, empieza por la introducción para Proveedores.

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 (network_id) que se utilizará en todas las transiciones de estado.

Ejemplos de IDs de red:

  • 01
  • oxxo_network
  • seven_eleven_mx
  • farmacia_abc
  • network_123
Contacto

Para registrar tus redes de pago, contacta a tu ejecutivo comercial o escríbenos a contacto@pago46.com. Los IDs que proporciones serán los que deberás usar en las solicitudes de retiro.

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: El proveedor verifica si el código presentado por el usuario es válido y la orden está en estado READY.
  2. Bloqueo: 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: 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 presentado por el usuario final.
curl -X GET "https://api.dev.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 mientras está bloqueada, recibirá un error 400 indicando que la transición no está permitida.

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

curl -X POST "https://api.dev.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 '{
    "network_id": "network_123",
    "price": "1500.00",
    "price_currency": "MXN"
  }'
CampoTipoDescripción
network_idstringID de la red de pago utilizada por el proveedor. Requerido.
pricestringOpcional. Si lo envías, debe coincidir con el price de la orden.
price_currencystringOpcional. Si lo envías, debe coincidir con el price_currency de la orden.
Subredes para proveedores

Como proveedor, debes suministrar el 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 estado 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.dev.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 '{
    "network_id": "network_123",
    "price": "1500.00",
    "price_currency": "MXN"
  }'

Al recibir esta respuesta, Pago46 notificará al comercio que creó la orden mediante el webhook configurado.

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 start-payment, debes liberar la orden para no dejarla bloqueada indefinidamente. Solo puedes hacerlo si la orden está en PAYMENT_STARTED y tu proveedor fue quien la bloqueó; si otro proveedor la bloqueó, no puedes actuar sobre ella.

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

Esto devuelve la orden a READY, donde queda disponible para procesarse nuevamente.

curl -X POST "https://api.dev.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 '{
    "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; registro histórico.
CANCELLEDLa orden fue anulada.No entregar dinero.