Skip to main content

Withdrawals (Pay Out)

This module allows Payment Providers to process cash withdrawal requests initiated by Pago46 users. The flow is designed to guarantee transaction atomicity and prevent duplicate fund delivery through a locking mechanism.

Base Endpoint

All routes described below are relative to the API base URL: /api/v1

Payment Network Registration​

Before processing transactions, providers must register the payment networks they use. Each network must have a unique identifier (provider_network_id) that will be used in all state transitions.

Example Network IDs:

  • 01
  • oxxo_network
  • seven_eleven_mx
  • farmacia_abc
  • network_123
Contact

To register your payment networks, contact the Pago46 integration team. The IDs you provide will be the ones you must use in payment requests.

Order Lifecycle​

The process is governed by strict state changes to ensure money is delivered only once.

  1. Check: The provider verifies if the code presented by the user is valid and the order is in the READY state.
  2. Start Payment (Lock): The provider "claims" the order. This changes the status to PAYMENT_STARTED. At this point, no other provider can process this order.
  3. Confirm Payment: Once the cash is handed over, the provider confirms the transaction, moving the order to COMPLETED.

1. Verify Order​

The first step occurs when the user presents their withdrawal code at the physical location. You must query the order details to validate the amount and its availability.

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

ParameterLocationDescription
codePathThe numeric or alphanumeric code provided by the end-user.
curl -X GET "https://api.sandbox.pago46.io/api/v1/providers/orders/pay-out/1234567890/" \
  -H "Provider-Key: <YOUR_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>"
Status Validation

You must only proceed to the next step if the status is READY. If you receive CANCELLED, COMPLETED, or EXPIRED, you must inform the user that the order cannot be processed.

2. Start Payment (Lock)​

This is the most critical step. By executing this endpoint, you indicate the intention to pay the order. The system will lock the order for your provider and change its status to PAYMENT_STARTED.

If another provider attempts to start payment for the same order simultaneously, they will receive an error indicating the order is already being processed.

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: <YOUR_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"
  }'
FieldTypeDescription
order_typestringOrder type (LocalCurrencyOrder or ForeignCurrencyOrder).
provider_network_idstringID of the payment network used by the provider. Required for LocalCurrencyOrder orders.
pricestringExact amount to be delivered. Must match the order's price. Required for LocalCurrencyOrder orders.
price_currencystringCurrency code (e.g., MXN, USD). Must match the order's price_currency. Required for LocalCurrencyOrder orders.
Subnetworks for Providers

As a provider, you must supply the provider_network_id that identifies the specific network used to process this transaction. This allows Pago46 to maintain a detailed record of which network processed each payment and provide this information to the end user.

Safe Operation

Once you receive the 200 OK with status PAYMENT_STARTED, it is safe to proceed with the physical handover of money or internal fund management. The order is reserved for you.

3. Confirm Payment (Completion)​

Once the money has been successfully handed to the user (or the internal transaction has finished), you must confirm the operation to definitively close the order.

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: <YOUR_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"
  }'

Upon receiving this response, we will notify the end-user that their transaction has concluded successfully.

Cancellation (Optional)​

If for any reason (insufficient funds in the register, operational error) you cannot complete the payment after having executed start-payment, you must release the order so it is not left locked indefinitely.

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

This will return the order to a state where (depending on business logic) it could be cancelled permanently or retried.

curl -X POST "https://api.sandbox.pago46.io/api/v1/providers/orders/pay-out/1234567890/cancel-payment/" \
  -H "Provider-Key: <YOUR_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"
  }'

Status Summary​

StatusDescriptionRequired Provider Action
READYThe order is ready to be paid.Can call start-payment.
PAYMENT_STARTEDThe order is locked by a provider.Must hand over money and call confirm-payment.
COMPLETEDThe flow finished successfully.No action required. Historical record.
CANCELLEDThe order was annulled.Do not hand over money.