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": "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",
"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": "USD",
"label": "US Business Account",
"bank_details": {
"recipient": {
"type": "Business",
"name": "Acme Corp Inc"
},
"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": "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 | Currency code (e.g. EUR, USD, GBP) |
label | No | Optional label for the account |
bank_details.recipient | Yes | Recipient name (Individual or Business) |
bank_details.provider_name | Yes | Bank name |
bank_details.provider_country | Yes | Bank’s country |
bank_details.account_identifier | Yes | Account details (varies by payment rail) |
bank_details.address | Yes | Recipient’s postal address |
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": "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
| Status | Description |
|---|
RegistrationPending | Registration is being processed |
Registered | Account is active and ready for payouts |
RegistrationFailed | Registration failed (check account details) |
AuthorizationRequired | Additional authorization needed |
AuthorizationFailed | Authorization was rejected |
Third-party accounts
You can register bank accounts that belong to third parties (not the customer). Set is_third_party: true in the request.
Third-party payouts may be subject to additional compliance checks and restrictions depending on your partner agreement.
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 |
