Overview
Fiat addresses represent bank accounts that can receive payouts from your Autoramps. Before initiating an offramp, you must register the destination bank account.
Iron supports multiple payment rails:
| Type | Description | Currency |
|---|
| SEPA | European payments via IBAN | EUR |
| ACH | US domestic transfers | USD |
| Wire | US wire transfers | USD |
| RTP | US Real-Time Payments | USD |
| SWIFT | International transfers | Multiple |
| CHAPS | UK high-value payments | GBP |
| FPS | UK Faster Payments | GBP |
Register a bank account
Register a bank account for a customer. The request structure varies based on the payment rail.
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",
"swift_code": "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",
"country": { "code": "GB" },
"postal_code": "E14 5HQ"
},
"is_third_party": false
}
}'
SWIFT is currently available for payouts only, with originators based in the US. We are actively working toward a global solution.
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": { "code": "EUR" },
"bank_account_identifier": {
"type": "SEPA",
"iban": "DE89XXXXXXXXXXXX3000"
},
"country": "DE",
"bank_name": "Deutsche Bank",
"ownership_verified": true,
"is_third_party": false
}
The bank_account_identifier in the response is partially masked for security.
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.
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 |
