Foreign Currency Withdrawals (Pay Out)

This module allows you to create withdrawals (pay-out) in local currency using source funds in foreign currency (for example, USDC → MXN).

As a Merchant, your integration communicates exclusively with Pago46. Pago46 internally manages the quote, monitors the receipt of funds, and enables the cash withdrawal.

Base Endpoint

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

General Flow

1. You create a quote for an asset pair (POST /merchants/quotes/).
2. Your user accepts the quote in your application.
3. You create a foreign withdrawal order associated with that quote.
4. Your user sends the funds to the address indicated by Pago46.
5. If the funding arrives within the valid window, the order advances to READY and is ready to continue the normal withdrawal flow.

---

Prerequisites

• Merchant credentials (Merchant-Key and Merchant-Secret).
• HMAC signature on every request (Message-Date, Message-Hash).
• Public notify_url via HTTPS for status changes.
• At least one of consumer_email or consumer_phone_number when creating the order.

Check the Authentication section for the signature.

---

1) Create Quote

Request a quote for the desired asset pair.

Endpoint: POST /merchants/quotes/

Request Fields

Field	Type	Required	Description
blockchain	String	Yes	Funding network (SOLANA, STELLAR, MONAD).
send	Decimal	Yes	Amount the user will send.
send_currency	String	Yes	Source currency (e.g., USDC).
target_country	String	Yes	Destination country (MX, CL, etc.).
target_currency	String	Yes	Target local currency (e.g., MXN).

Request Example

curl -X POST "https://api.dev.pago46.io/api/v1/merchants/quotes/" \
  -H "Merchant-Key: <YOUR_MERCHANT_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "blockchain": "SOLANA",
    "send": "150.00",
    "send_currency": "USDC",
    "target_country": "MX",
    "target_currency": "MXN"
  }'

Response (201 Created)

{
  "id": "01952d8f-8da1-7f4b-bb36-cfba8a3be829",
  "blockchain": "SOLANA",
  "send": "150.00",
  "send_currency": "USDC",
  "target_country": "MX",
  "target_currency": "MXN",
  "calculated_order_price": "2895.00",
  "calculated_order_price_currency": "MXN",
  "expires": "2030-01-01T11:05:00Z"
}

tip

Save the quote id. You will use it when creating the foreign order.

---

2) Create Foreign Withdrawal Order

When your user accepts the quote, create the foreign pay-out order using the quote.

Endpoint: POST /merchants/orders/pay-out/

Request Fields

Field	Type	Required	Description
order_type	String	Yes	Must be ForeignCurrencyOrder.
quote	UUID	Yes	ID of the previously created quote.
description	String	Yes	Transaction description.
merchant_order_id	String	Yes	Unique ID from your system per Merchant.
notify_url	URL	Yes	URL for status notifications.
return_url	URL	Yes	Return URL.
expiry	DateTime	Yes	Order expiration (ISO 8601).
consumer_email	String	Conditional	Required if you don't send a phone number.
consumer_phone_number	String	Conditional	Required if you don't send an email.
wallet	String	Yes	Wallet that will sign the on-chain transaction.

Request Example

curl -X POST "https://api.dev.pago46.io/api/v1/merchants/orders/pay-out/" \
  -H "Merchant-Key: <YOUR_MERCHANT_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>" \
  -H "Content-Type: application/json" \
  -d '{
    "quote": "01952d8f-8da1-7f4b-bb36-cfba8a3be829",
    "description": "Cash withdrawal from USDC balance",
    "merchant_order_id": "FX-PO-2026-0001",
    "notify_url": "https://your-merchant.com/webhooks/pago46",
    "return_url": "https://your-merchant.com/withdrawal/back",
    "consumer_email": "user@example.com",
    "expiry": "2030-01-01T12:05:00Z",
    "wallet": "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV",
    "order_type": "ForeignCurrencyOrder"
  }'

Important

Do not assume a successful (202 Accepted) POST to /pay-out/ means the withdrawal is actually available!

• The order has been created, but it DOES NOT INCLUDE the blockchain transaction to sign.
• Pago46 will build the transaction asynchronously.
• When it's ready, you will receive a webhook (CREATED status) that will include the transaction field in the order.
• Do not attempt to sign or show blockchain data to the user until you receive this webhook!

Response (202 Accepted)

{
  "id": "01952d91-a0ff-7f57-8f4e-68d95be01122",
  "direction": "PAY_OUT",
  "country": "MX",
  "price": "2895.00",
  "price_currency": "MXN",
  "description": "Cash withdrawal from USDC balance",
  "merchant_order_id": "FX-PO-2026-0001",
  "status": "CREATED",
  "notify_url": "https://your-merchant.com/webhooks/pago46",
  "redirect_url": "https://checkout.dev.pago46.io/01952d91-a0ff-7f57-8f4e-68d95be01122",
  "return_url": "https://your-merchant.com/withdrawal/back",
  "consumer_email": "user@example.com",
  "consumer_phone_number": "",
  "expiry": "2030-01-01T12:05:00Z",
  "paid": null,
  "quote": "01952d8f-8da1-7f4b-bb36-cfba8a3be829",
  "wallet": "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV",
  "order_type": "ForeignCurrencyOrder"
}

---

Notification webhook payload example

{
  "id": "01952d91-a0ff-7f57-8f4e-68d95be01122",
  "order_type": "ForeignCurrencyOrder",
  "country": "MX",
  "price": "2895.00",
  "price_currency": "MXN",
  "description": "Cash withdrawal from USDC balance",
  "merchant_order_id": "FX-PO-2026-0001",
  "status": "CREATED",
  "notify_url": "https://your-merchant.com/webhooks/pago46",
  "redirect_url": "https://checkout.dev.pago46.io/01952d91-a0ff-7f57-8f4e-68d95be01122",
  "return_url": "https://your-merchant.com/withdrawal/back",
  "consumer_email": "user@example.com",
  "consumer_phone_number": "",
  "expiry": "2030-01-01T12:05:00Z",
  "paid": null,
  "quote": "01952d8f-8da1-7f4b-bb36-cfba8a3be829",
  "transaction": "AgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADyTBSt8EsV++3pX0uVJVEfDjDp8mnxoqBQocHmFw2xTf62jiq5VGtOhOY4yZH7evGRh3UonSpGQKHYTU0EVXkCgAIBBxJXN/S1MQpq3laWmAefYKQbtIFHc3dbFnEnnIO8+VCswgaIfmL5OVR6yf1DpJxY0nPEwFUxZnKSpVis0mLyYvB+CadUk1OGINWUunRSHPvVZsHS9SxcAzkMV3l0YrJa87VfpoD7lSKyS7KXhZdFjn4tDD9PM7ZkSXL+bJrJU6WMj2H0hZpDLnPhzU1d1RhBedKdDIuLnQj09NPzfpJAUTubj9Njqmepn7FPWB/pRxyBJLcCwVALhYefbQnfHrKVYlqZDYlyLNK33Q83kGZK7y8fZH3WFOPQax4GGUN64gOvfJ3zTDIAyZPrGSRcP4/Qj+sgg0V135Yr0S5moofrpJa7uYWuPLoIHj1rtPdLNX3+MqAowL1C3mfnKmBZ/gHZOU2/2TY6lXGwBdMPZ/X4ph/o4AGrpI1iulm/FEsovQG37vM5zLFxniH7ltpr8uBf04yhJRTUvdC/74e97kFxMjiNAwZGb+UhFzL/7K26csOb57yM5bvF9xJrLEObOkAAAAAEedVb8jHAbu50xW7OaBUH/bGy3qP0jlECsc2iVrwTjwVKU1qZKSEGTSTocWDaOHx8NbXdvJK7geQfqEBBBUSNBt324ddloZPZy+FGzut5rBy0he1fWzeROoz1hX7/AKkG3fbh7nWP3hhCXbzkbM3athr8TYO5DSf+vfko2KGL/LQ/+if11/ZKdMCbHylYed5LCas238ndUUsyGqezjOXo4vh36D2uxoiPQ6u1rnsxG7eMNJYIl/zlp7gsFuIP8ZcyjRWyhzKZjkXq5kHeRVDaKaLEEPfSWQM7V8ohwWOR/wYNABhBWnljbytLbWRnbTNZZFN4Q1Z5SnFBPT0OBAYYCQAKDEBCDwAAAAAABgsABQLAXBUACwAJAwQXAQAAAAAADB0OEQEJCAcEGBcMDxAMFg8ODRETFxgHEggUAgMKFSbBIJszQdacgQABAAAALwAAZAABQEIPAAAAAADskeQAAAAAABQAAA8EBBcFAQoM7vXjAAAAAAAGAWdhe29wATESFFYXVPJ+3KgjZOfKxNroQxcYyDV2rOPsBJVakZgDllyS",
  "wallet": "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV"
}

---

3) Retrieve Order

You can retrieve the withdrawal order whenever you need to verify its status.

Endpoint: GET /merchants/orders/pay-out/{id}/

curl -X GET "https://api.dev.pago46.io/api/v1/merchants/orders/pay-out/01952d91-a0ff-7f57-8f4e-68d95be01122/" \
  -H "Merchant-Key: <YOUR_MERCHANT_KEY>" \
  -H "Message-Date: <TIMESTAMP>" \
  -H "Message-Hash: <HMAC_SIGNATURE>"

---

Order Statuses (Foreign Pay-Out)

Status	Description	What does it mean for the merchant?
CREATED	Order successfully created	The order is registered and pending provider assignment
READY	Ready for processing	Funding received; withdrawal can continue in the payment network
PAYMENT_STARTED	Payment in progress	A provider is processing the withdrawal
COMPLETED	Completed	The withdrawal completed; the beneficiary received the cash
CANCELLED	Cancelled	The order was cancelled and will not be processed
EXPIRED	Expired	The order expired and will not be processed

State Transition Diagram

---

Integration Best Practices

• Use idempotent merchant_order_id per business operation.
• Handle status changes in a retry-tolerant manner.
• Do not assume COMPLETED immediately after creating the order.
• Show the user a countdown based on the quote window.
• After a POST to /pay-out/, maintain a status like "Waiting for transaction" until you receive the webhook containing the transaction field. Only then proceed to collect a signature from the user or advance the flow.
• Store the returned order id so you can correlate the initial POST and the webhook notification.
• In case of validation errors, always request a new quote before retrying. See Common Errors for the exact error formats returned by the API for validation and logic issues.

If you need support for new asset pairs (for example, additional source currencies or destination countries), contact your Pago46 representative.