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

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 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.sandbox.pago46.io/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.sandbox.pago46.io/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",
    "provider_network_id": "network_123",
    "price": "500.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 está cobrando. 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.

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.sandbox.pago46.io/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",
    "provider_network_id": "network_123",
    "price": "500.00",
    "price_currency": "MXN"
  }'

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.sandbox.pago46.io/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",
    "provider_network_id": "network_123",
    "price": "500.00",
    "price_currency": "MXN"
  }'

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.