LATAM — cash and bank payouts

Cash pay-in and pay-out at supported pay-points across Latin America, plus bank payouts into Mexico, Chile and Colombia funded from any wallet.

LifecycleUserWalletKYCRailFundMove money

LATAM cash orders let users fund a smart wallet with physical cash, or receive cash from it, at supported pay-points across Latin America — no bank account required.

Direction	Endpoint	Meaning
Pay-in	POST /v1/users/{userId}/latam/cash/orders/fund	User deposits cash → wallet is funded
Pay-out	POST /v1/users/{userId}/latam/cash/orders/send	Wallet is debited → user collects cash

---

Create an order

Both directions take the same body:

POST /v1/users/{userId}/latam/cash/orders/fund
{
  "smartWalletId": "7f4d6b88-80a0-4d3f-9538-9a4dfabc1234",
  "country": "MX",
  "price": "1500.00",
  "priceCurrency": "MXN",
  "description": "Wallet top-up"
}

Field
smartWalletId	required — UUID of the smart wallet to fund / debit
country	required — ISO 3166-1 alpha-2 code, e.g. "MX"
price	required — decimal string in the order currency
priceCurrency	required — a fiat currency code that maps to a supported wallet stablecoin (MXN → MEXe, USD → USDB, NGN → CNGN, CAD → CADC, EUR → EURe, GBP → GBPe), and must match the smart wallet’s currency
description	required — shown on the order, e.g. "Wallet top-up"

Pay-in (fund) response

Returns the provider order including a redirect_url — send the user there to choose a pay-point and pay the cash. Once paid, the wallet is credited.

Pay-out (send) response

Returns a signatureRequest authorizing the payout from the user’s wallet. Have the user sign it on-device with bmoni_embedded_sdk and submit the signature via POST /v1/users/{userId}/wallets/submit-signature — the cash order is placed once the debit is authorized.

---

List and track orders

GET /v1/users/{userId}/latam/cash/orders?type=FUND&shape=LocalCurrencyOrder
GET /v1/users/{userId}/latam/cash/orders/{orderId}

List returns the user’s active order records — completed, cancelled and expired orders are excluded. Each record has id, orderId, type, an uppercase status (CREATED, READY, PAYMENT_STARTED, …), price, expiry (pay / collect before this), and timestamps.

Query
type	FUND (pay-in) or SEND (pay-out). Defaults to SEND
shape	LocalCurrencyOrder for cash orders (default), ForeignCurrencyOrder for bank payouts. FUND only ever exists as LocalCurrencyOrder

There is no “all orders” endpoint. Each call returns exactly one type + shape slice, and only active orders. To show a user everything, call it once per combination you care about — and read the transactions endpoints for anything that has already settled, since a completed order drops out of this listing.

Get by ID returns the live provider order: id, price, price_currency, description, merchant_order_id, status, redirect_url, and return_url.

---

Bank payouts

A cash order is collected in person. A bank payout pays local fiat straight into a recipient’s bank account in the destination country, funded from any supported stablecoin wallet — the source wallet is swapped into USDC atomically as part of the operation the user signs.

This is the corridor to reach a Mexican recipient from a USD (or any other) wallet. It is not the same thing as the MXN offramp, and the two have different prerequisites:

	Bank payout	MXN offramp
Source	any wallet token	the user’s own MEXe (MXN) wallet
Destination	a recipient’s bank account in targetCountry	the user’s own CLABE
Mexico KYC	not required	required — see the KYC page
Signatures	one	one or two (approve, then burn)
Tracking	the workflow	the order, and the workflow

1. Create the payout

POST /v1/users/{userId}/latam/cash/payouts/foreign
{
  "smartWalletId": "7f4d6b88-80a0-4d3f-9538-9a4dfabc1234",
  "usdcAmount": "100.00",
  "targetCountry": "MX",
  "targetCurrency": "MXN",
  "description": "Payout to Mexico"
}

Field
smartWalletId	required — the wallet being debited; any supported stablecoin
usdcAmount	required — decimal string, the USDC forwarded to the provider after the swap
targetCountry	required — ISO 3166-1 alpha-2, e.g. "MX", "CL", "CO"
targetCurrency	required — ISO 4217, e.g. "MXN", "CLP", "COP"
description	required — 1–255 characters

{
  "signatureRequest": { "…": "…" },
  "source": {
    "smartWalletId": "7f4d6b88-80a0-4d3f-9538-9a4dfabc1234",
    "currency": "USDB",
    "amountIn": "100.50",
    "feeAmount": "0.50"
  },
  "intermediate": { "asset": "USDC", "amount": "100.00" },
  "destination": {
    "amount": "1830.40",
    "currency": "MXN",
    "rate": "18.304",
    "fee": "1.20",
    "feeCurrency": "USD"
  }
}

destination is indicative. A fresh provider quote is taken after the bridge completes, so the settled amount can differ slightly. Show it as an estimate, not a guarantee.

2. Sign and submit

Sign signatureRequest on-device via bmoni_embedded_sdk and submit it the same way as any other smart-wallet mutation:

POST /v1/users/{userId}/wallets/submit-signature
{ "workflowId": "…", "signature": "0x…" }

3. Poll for settlement

GET /v1/users/{userId}/wallets/workflows/{workflowId}

The workflow is the authoritative settlement signal for a bank payout — poll it until isTerminal is true; see the signature pattern for the response shape.

A payout in flight also appears in the order listing under the foreign shape, which is useful for showing “in progress” state:

GET /v1/users/{userId}/latam/cash/orders?type=SEND&shape=ForeignCurrencyOrder

It drops out of that listing once it completes — by then the workflow has the outcome.