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

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}/

Parameter	Location	Description
code	Path	The numeric or alphanumeric code provided by the end-user.

Request

curl -X GET "https://api.pago46.com/api/v1/providers/orders/pay-out/1234567890/" \
  -H "Provider-Key: <YOUR_PROVIDER_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>"

Response (200 OK) - Order Ready

{
  "order_type": "LocalCurrencyOrder",
  "price": "1500.00",
  "price_currency": "MXN",
  "created": "2023-11-25T10:00:00Z",
  "modified": "2023-11-25T10:05:00Z",
  "status": "READY",
  "expiry": "2023-11-26T10:00:00Z"
}

Response (200 OK) - Order Already In Progress

{
  "order_type": "LocalCurrencyOrder",
  "price": "1500.00",
  "price_currency": "MXN",
  "created": "2023-11-25T10:00:00Z",
  "modified": "2023-11-25T10:05:00Z",
  "status": "PAYMENT_STARTED",
  "expiry": "2023-11-26T10:00:00Z"
}

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/

Request

curl -X POST "https://api.pago46.com/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"
  }'

Response (200 OK)

{
  "order_type": "LocalCurrencyOrder",
  "price": "1500.00",
  "price_currency": "MXN",
  "status": "PAYMENT_STARTED",
  "modified": "2023-11-25T10:06:00Z",
  "expiry": "2023-11-26T10:00:00Z"
}

Error (409 Conflict)

{
  "detail": "Order is currently being processed by another provider."
}

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/

Request

curl -X POST "https://api.pago46.com/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"
  }'

Response (200 OK)

{
  "order_type": "LocalCurrencyOrder",
  "price": "1500.00",
  "price_currency": "MXN",
  "status": "COMPLETED",
  "paid": "2023-11-25T10:08:00Z",
  "modified": "2023-11-25T10:08:00Z"
}

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

Status Summary

Status	Description	Required Provider Action
READY	The order is ready to be paid.	Can call start-payment.
PAYMENT_STARTED	The order is locked by a provider.	Must hand over money and call confirm-payment.
COMPLETED	The flow finished successfully.	No action required. Historical record.
CANCELLED	The order was annulled.	Do not hand over money.