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.sandbox.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.sandbox.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"
  }'

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.sandbox.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.sandbox.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.sandbox.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
CREATED	Order created and pending validation of the associated funding.
READY	Funding received within the valid window. The withdrawal can continue in the payment network.
COMPLETED	Withdrawal completed successfully.
CANCELLED	Withdrawal cancelled.
EXPIRED	Withdrawal expired.

---

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.
• In case of validation errors, request a new quote before retrying.

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