Fiat Addresses

Overview

Fiat addresses represent bank accounts that can receive payouts from your Autoramps. Before initiating an offramp, you must register the destination bank account. MoonPay Enterprise supports multiple payment rails:

Type	Description	Currency
SEPA	European payments via IBAN	EUR
ACH	US domestic transfers	USD
Wire	US wire transfers	USD
SWIFT	International transfers	USD
CHAPS	UK high-value payments	GBP
FPS	UK Faster Payments	GBP
PIX	Brazilian instant payments, registered through its own endpoints. See PIX (Brazil)	BRL

RTP (US Real-Time Payments) is not yet supported — support is coming soon.

Register a bank account

SEPA (Europe)

curl -X POST https://api.sandbox.iron.xyz/api/addresses/fiat \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000" \
-H "X-API-Key: $API_KEY" \
-d '{
  "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
  "currency": { "code": "EUR" },
  "label": "Primary Business Account",
  "bank_details": {
    "recipient": {
      "type": "Business",
      "name": "Acme Corp GmbH"
    },
    "provider_name": "Deutsche Bank",
    "provider_country": { "code": "DE" },
    "account_identifier": {
      "type": "SEPA",
      "iban": "DE89370400440532013000"
    },
    "address": {
      "street": "Crypto Street 123",
      "city": "Berlin",
      "state": "Berlin",
      "country": { "code": "DE" },
      "postal_code": "10115"
    },
    "is_third_party": false
  }
}'

ACH (US Domestic)

curl -X POST https://api.sandbox.iron.xyz/api/addresses/fiat \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174001" \
-H "X-API-Key: $API_KEY" \
-d '{
  "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
  "currency": { "code": "USD" },
  "label": "Jane Doe Checking",
  "bank_details": {
    "recipient": {
      "type": "Individual",
      "given_name": "Jane",
      "family_name": "Doe"
    },
    "provider_name": "Chase Bank",
    "provider_country": { "code": "US" },
    "account_identifier": {
      "type": "ACH",
      "routing_number": "021000021",
      "account_number": "123456789012"
    },
    "address": {
      "street": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "country": { "code": "US" },
      "postal_code": "10001"
    },
    "email_address": { "email": "finance@acme.com" },
    "phone_number": "+1-212-555-0123",
    "is_third_party": false
  }
}'

SWIFT (International)

curl -X POST https://api.sandbox.iron.xyz/api/addresses/fiat \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174002" \
-H "X-API-Key: $API_KEY" \
-d '{
  "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
  "currency": { "code": "USD" },
  "label": "International Account",
  "bank_details": {
    "recipient": {
      "type": "Business",
      "name": "Acme Global Ltd"
    },
    "provider_name": "HSBC",
    "provider_country": { "code": "GB" },
    "account_identifier": {
      "type": "SWIFT",
      "bic": "HSBCGB2L",
      "account_number": "12345678"
    },
    "address": {
      "street": "10 Downing Street",
      "city": "London",
      "state": "England",
      "country": { "code": "GB" },
      "postal_code": "SW1A 2AA"
    },
    "bank_address": {
      "street": "8 Canada Square",
      "city": "London",
      "state": "England",
      "country": { "code": "GB" },
      "postal_code": "E14 5HQ"
    },
    "is_third_party": false
  }
}'

SWIFT payouts are available in USD, to both first-party and third-party accounts. Country coverage for each customer depends on how they were onboarded and on your account setup. See USD payouts. For inbound SWIFT deposits, see Currencies and Rails.

Request fields

Field	Required	Description
`customer_id`	Yes	The customer’s UUID
`currency`	Yes	Object with a `code` property (e.g. `{ "code": "EUR" }`)
`label`	No	Optional label for the account
`bank_details.recipient`	Yes	Object with a `type` discriminator. `Business`: requires `name`. `Individual`: requires `given_name` and `family_name`.
`bank_details.provider_name`	Yes	Bank name
`bank_details.provider_country`	Yes	Bank’s country as `{ "code": "<ISO 3166-1>" }`
`bank_details.account_identifier`	Yes	Account details (varies by payment rail)
`bank_details.address`	Yes	Recipient’s postal address. All fields including `state` are required.
`bank_details.email_address`	USD only	Required for USD accounts
`bank_details.phone_number`	USD only	Required for USD accounts
`bank_details.is_third_party`	Yes	Whether this is a third-party account
`bank_details.bank_address`	SWIFT only	Required for SWIFT transfers

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z",
  "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
  "bank_details": { ... },
  "label": "Primary Business Account",
  "status": "Registered",
  "currency": "EUR",
  "bank_account_identifier": {
    "type": "SEPA",
    "iban": "DE89370400440532013000"
  },
  "country": "DE",
  "bank_name": "Deutsche Bank",
  "ownership_verified": true,
  "is_third_party": false
}

List bank accounts

Retrieve all registered bank accounts for a customer:

curl -X GET "https://api.sandbox.iron.xyz/api/addresses/fiat/{customer_id}" \
-H "X-API-Key: $API_KEY"

Query parameters

Parameter	Description
`cursor`	Pagination cursor from previous response
`page_size`	Number of results per page (max 100)
`search_term`	Filter by IBAN, label, or bank name

List by status

Retrieve all bank accounts with a specific status across all customers:

curl -X GET "https://api.sandbox.iron.xyz/api/addresses/fiat?status=Registered" \
-H "X-API-Key: $API_KEY"

Get a specific bank account

curl -X GET "https://api.sandbox.iron.xyz/api/addresses/fiat/{customer_id}/{fiat_address_id}" \
-H "X-API-Key: $API_KEY"

Delete a bank account

Soft-delete a registered bank account:

curl -X DELETE "https://api.sandbox.iron.xyz/api/addresses/fiat/{customer_id}/{fiat_address_id}" \
-H "X-API-Key: $API_KEY"

Deleted accounts cannot be used for new transactions. This operation cannot be undone.

Address statuses

Beneficiary whitelisting is instant. There is no separate recipient verification step. Most accounts move from RegistrationPending to Registered within seconds. If they don’t, the status tells you why.

Status	Description
`RegistrationPending`	Registration in progress. Resolves within seconds in production.
`Registered`	Account is active and ready for payouts.
`RegistrationFailed`	The bank details were rejected. Common causes: invalid IBAN or routing number, mismatched recipient name, missing required fields. Fix the details and re-register.
`AuthorizationRequired`	In rare cases the beneficiary needs to be approved by the bank before payouts can run.
`AuthorizationFailed`	The beneficiary was rejected by compliance. The account cannot receive payouts.

Third-party accounts

To register a bank account that doesn’t belong to the customer (a friend, family member, or business counterparty), set is_third_party: true. The registration flow is identical to first-party accounts: beneficiary whitelisting is instant, and the account is ready for payouts within seconds.

PIX (Brazil)

PIX destinations pay out in BRL. They use their own endpoints under /api/addresses/pix, not /api/addresses/fiat. Identify the recipient’s account with a PIX key, or with full bank details when they don’t have one.

Register a PIX destination

POST /api/addresses/pix

curl -X POST https://api.sandbox.iron.xyz/api/addresses/pix \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000" \
-H "X-API-Key: $API_KEY" \
-d '{
  "customer_id": "4b85d15e-f343-41c0-809c-85314cae2fa6",
  "label": "Primary PIX",
  "recipient": {
    "recipient": {
      "type": "Individual",
      "given_name": "João",
      "family_name": "Silva"
    },
    "account": {
      "type": "PHONE",
      "key": "+5511987654321"
    }
  }
}'

Every POST needs an Idempotency-Key header, and a missing key returns 400. MoonPay Enterprise caches successful responses only, so a retry after an error runs again. See Idempotency.

recipient.recipient is the account holder’s name, with the same Individual and Business shapes as bank accounts. recipient.account identifies the account by its type:

`type`	Fields	Format
`CPF`	`key`	11 digits, with or without `XXX.XXX.XXX-XX` formatting
`CNPJ`	`key`	14 digits, with or without `XX.XXX.XXX/XXXX-XX` formatting
`EMAIL`	`key`	Email address, up to 77 characters
`PHONE`	`key`	E.164 phone number, for example `+5511987654321`
`EVP`	`key`	Random key from the recipient’s bank, as a lowercase UUID
`BANK_DETAILS`	`tax_id`, `bank_code`, `branch_code`, `account_number`, `account_type`	For recipients without a PIX key. `tax_id` is the holder’s CPF or CNPJ, `bank_code` a 3-digit COMPE or 8-digit ISPB code, `branch_code` up to 4 digits without the check digit, `account_number` with its check digit and no separator, and `account_type` one of `CHECKING`, `SAVINGS`, `SALARY`, or `TRANSACTION`

The response is the PIX address with its id and a status. It starts as RegistrationPending and moves to Registered once the destination is set up for payouts. An Autoramp accepts the destination only when it’s Registered. To pay out to it, pass { "type": "Pix", "id": "<pix_address_id>" } as the Autoramp’s recipient_account. Registering the same account twice for a customer returns 409 with a plain string body:

"A PIX address with this account already exists for this customer"

Look up a PIX key

GET /api/pix-key-info?pix_key_type={type}&pix_key={key} returns the holder’s name, the bank name, and the bank’s 8-digit ISPB code, without registering anything. Use it to show your customer who they’re paying before you register the destination. pix_key_type is one of CPF, CNPJ, EMAIL, PHONE, or EVP.

List, get, and delete

Action	Endpoint
List a customer’s PIX destinations	`GET /api/addresses/pix/{customer_id}`
Get one PIX destination	`GET /api/addresses/pix/{customer_id}/{pix_address_id}`
Delete a PIX destination	`DELETE /api/addresses/pix/{customer_id}/{pix_address_id}`

Common errors

Error	Cause
`400 Bad Request`	Invalid IBAN format, missing required fields, or invalid country
`404 Not Found`	Customer not found or does not belong to your partner
`409 Conflict`	Bank account already registered for this customer

Getting Started

Coverage

Onboarding & Compliance

Virtual Accounts & Global Payouts

Issuance

Wallets

Webhooks & Events

Billing & Settlement

Support

Overview

Register a bank account

SEPA (Europe)

ACH (US Domestic)

SWIFT (International)

Request fields

Response

List bank accounts

Query parameters

List by status

Get a specific bank account

Delete a bank account

Address statuses

Third-party accounts

PIX (Brazil)

Register a PIX destination

Look up a PIX key

List, get, and delete

Common errors

Crypto Addresses

Offramp Guide

​Overview

​Register a bank account

​SEPA (Europe)

​ACH (US Domestic)

​SWIFT (International)

​Request fields

​Response

​List bank accounts

​Query parameters

​List by status

​Get a specific bank account

​Delete a bank account

​Address statuses

​Third-party accounts

​PIX (Brazil)

​Register a PIX destination

​Look up a PIX key

​List, get, and delete

​Common errors

​Related guides

Crypto Addresses

Offramp Guide

Overview

Register a bank account

SEPA (Europe)

ACH (US Domestic)

SWIFT (International)

Request fields

Response

List bank accounts

Query parameters

List by status

Get a specific bank account

Delete a bank account

Address statuses

Third-party accounts

PIX (Brazil)

Register a PIX destination

Look up a PIX key

List, get, and delete

Common errors

Related guides