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

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.pago46.com/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.pago46.com/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"
  }'
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.pago46.com/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"
  }'

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.pago46.com/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"
  }'

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.