Skip to main content
USD payouts go out through Lead Bank or Erebor Bank, depending on how the customer was onboarded. Pay US accounts over ACH, Wire, or FedNow, and accounts at banks outside the US over SWIFT. See Payouts for the overall flow.

​
Who can receive USD payouts

Read abilities.fiat_payout.usd from GET /api/customers/{customer_id}/abilities to see which of ach, wire, fednow, and swift (and their _thirdparty variants) are Active for a customer. RTP appears in the response but is never Active in production. Sandbox reports rtp and rtp_thirdparty as Active.

​
Register the bank account

POST /api/addresses/fiat registers the account. Every USD rail uses the same request shape and differs only in account_identifier.
POST /api/addresses/fiat requires an Idempotency-Key header. A missing key returns 400. Only successful responses are cached, so a retry after an error runs again. See Idempotency.

​
Fields for every rail

​
ACH and Wire

Use "type": "Wire" with the same two fields for a wire.
  • routing_number: a 9-digit ABA routing number. A value that isn’t exactly 9 digits fails request validation with 400 and a "parse request payload error: ..." body. A 9-digit number with a wrong prefix or check digit returns 400 with "Invalid routing number"
  • account_number: 4-17 digits or uppercase letters

​
FedNow

FedNow takes the same fields as ACH. Only Lead Bank sends FedNow payouts, and only for customers onboarded to the MoonPay USA entity. The recipient’s bank must accept FedNow payments.

​
SWIFT

SWIFT pays USD to a bank outside the US.
  • bic: uppercase letters and digits. Its country must match provider_country, or registration returns 400 with "BIC country does not match provider_country"
  • account_number: 1-34 letters, digits, or spaces, ending in a letter or digit. Send an IBAN here for banks that use them
  • intermediary_bic: optional. Lead Bank uses it as the correspondent bank only when it’s the BIC of a US bank, and otherwise picks one itself. Erebor Bank ignores it

​
Which countries

Two banks send SWIFT payouts, and each covers different countries and customers:
  • Erebor Bank pays to 46 countries, for individuals and businesses: AE, AT, AU, BE, BH, BM, BR, BS, CA, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HK, HR, HU, IE, IL, IT, KR, KY, LI, LT, LU, LV, MT, MX, NL, NO, PH, PL, PT, RO, RS, SE, SG, SI, SK, SM
  • Lead Bank pays to every country except 28: AF, BI, BT, BY, CD, CN, CU, GW, HT, IQ, IR, KE, KP, LB, LY, MM, MZ, PK, PS, QA, RU, SD, SO, SS, SY, VE, YE, ZW. It pays businesses, and pays individuals only when MoonPay Enterprise enables it for your account
A country is open for a customer when a bank the customer is onboarded with covers it. MoonPay Enterprise checks both the bank’s country (provider_country) and the country in the recipient’s address. If either isn’t covered, registration returns 400:
400 Bad Request
SWIFT payouts are USD only. Pay banks in the US over ACH, Wire, or FedNow: a SWIFT Autoramp to a US bank on Lead Bank returns 400 with "USD SWIFT payouts to a U.S. bank are not supported; provide domestic wire (ABA) details instead".

​
Canadian banks

A SWIFT account at a Canadian bank needs its national routing data in bank_details.local_routing:
institution_number is the 3-digit financial institution number and transit_number the 5-digit branch transit number. Without it, registration returns 400 with "CA SWIFT accounts require local_routing of type CA_ROUTING". Every other country rejects local_routing.

​
Purpose codes

Banks in the United Arab Emirates (AE), South Korea (KR), and the Philippines (PH) require a purpose code. Pass swift_purpose_code when you create the Autoramp or request the quote. A missing or unknown code returns 400, and the message lists the codes that country accepts. Every other country rejects swift_purpose_code. The purpose code is fixed when you create the Autoramp. To change it, cancel the Autoramp and create a new one. See Edit an Autoramp.

​
Create the payout Autoramp

Create a standing Autoramp or a quote-based Autoramp the same way as any payout. See Payouts. The recipient is the registered account:

​
Payment references

Set at most one reference per Autoramp, in the field for the account’s rail. A field that doesn’t match the rail returns 400, for example "ach_payment_reference is only allowed for offramps via ACH transfer". The ACH reference becomes the entry’s statement descriptor at the recipient’s bank. Lead Bank also cuts the recipient’s name on an ACH entry to 22 characters and converts it to plain ASCII. References are fixed when you create the Autoramp. On a quote-based Autoramp, the reference and swift_purpose_code is part of the signed quote: pass it on GET /api/autoramps/quote, not on POST /api/autoramps, which returns 400 with "Invalid signature" if you add it there. To use a different reference for later deposits, pass payment_reference on GET /api/autoramps/{autoramp_id}/quote. See Quotes.

​
Third-party payouts

Set is_third_party: true when you register an account that doesn’t belong to your customer, such as a supplier or a family member. ACH, Wire, FedNow, and SWIFT all pay third parties. MoonPay Enterprise screens every third-party recipient against sanctions lists when the payout runs.

​
Timing

Lead Bank sends ACH payouts of up to $1,000,000 as same-day ACH, and larger ones as next-day ACH. See Settlement Times by Payment Method for every rail.

​
Fees and minimums

Banking fees per rail come from the Autoramp’s fee profile. See Fees and Invoices. A SWIFT payout under 5 USD, or any other payout under 1 USD, ends as RejectedMinAmount. See Minimum Transaction Amount.

​
What can go wrong

​
Sandbox

Sandbox registers USD accounts automatically, so a new account reaches Registered without a manual step. Test the full payout with Test the full flow in Sandbox.