Saltar al contenido principal

Pagos (Pay In)

Este módulo permite a los Proveedores de Pago (Payment Providers) procesar solicitudes de depósito o pago iniciadas por usuarios de Pago46. Al igual que en los retiros, este flujo utiliza un mecanismo de bloqueo (locking) para evitar que una misma orden sea cobrada dos veces por distintos proveedores simultáneamente.

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 asegura que el dinero sea recolectado y conciliado correctamente antes de liberar el servicio al usuario final.

  1. Consulta (Check): El proveedor escanea o ingresa el código del usuario para ver el monto a cobrar y validar que el estado sea READY.
  2. Bloqueo (Start Payment): El proveedor "toma" la orden. El estado cambia a PAYMENT_STARTED. Esto asegura la intención de cobro.
  3. Confirmación (Confirm Payment): Una vez que el usuario entrega el efectivo y este ingresa a la caja, el proveedor confirma la transacción (estado COMPLETED).

1. Verificar Orden​

Cuando el cliente se acerca a la caja para pagar, debes consultar el código para informar el monto exacto a cobrar.

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

ParámetroUbicaciónDescripción
codePathEl código de pago generado por el usuario (numérico o QR).
curl -X GET "https://api.pago46.com/api/v1/providers/orders/pay-in/9876543210/" \
  -H "Provider-Key: <TU_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>"
Validación de Estado

Verifica siempre que el status sea READY. Si la orden está EXPIRED o COMPLETED, no debes recibir dinero del usuario.

2. Iniciar Cobro (Bloqueo)​

Antes de recibir el dinero, debes informar a Pago46 que estás atendiendo esta orden. Esto previene que el usuario intente pagar el mismo código en otro proveedor simultáneamente.

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

curl -X POST "https://api.pago46.com/api/v1/providers/orders/pay-in/9876543210/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"
  }'
Momento del Cobro

Una vez recibas el estado PAYMENT_STARTED, puedes proceder a solicitar y recibir el dinero del cliente con seguridad.

3. Confirmar Cobro (Finalización)​

Una vez que el dinero está seguro en tu caja, confirma la transacción. En este momento, Pago46 notificará al comercio original (Merchant) para que libere el producto o servicio al usuario.

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

curl -X POST "https://api.pago46.com/api/v1/providers/orders/pay-in/9876543210/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"
  }'

Cancelación​

Si el usuario decide no pagar en el último momento o hay un problema con el efectivo, debes liberar la orden para que vuelva a estar disponible (o se cancele definitivamente, según las reglas de expiración de la orden).

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

curl -X POST "https://api.pago46.com/api/v1/providers/orders/pay-in/9876543210/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á pendiente de pago.Verificar monto y llamar a start-payment.
PAYMENT_STARTEDLa orden está en proceso de cobro.Recibir dinero y llamar a confirm-payment.
COMPLETEDEl dinero fue recaudado exitosamente.Entregar comprobante al usuario.
CANCELLEDLa orden fue cancelada.No recibir dinero.