# Create deposit instruction

Source: https://business-api-docs.youhodler.com/api/reference/deposit-instructions/deposit-instructions-create

**Authentication:** Send `Authorization: Bearer <access_token>`.

Creates a fiat deposit instruction against the pooled fiat route (delegated to `fiat-rails-service`). Crypto is rejected: crypto deposit addresses are minted through funding-endpoint provisioning. `funding_endpoint_id` optionally links a previously provisioned endpoint; null mints a standalone instruction. This is a pooled payment-reference route: virtual-account routes such as an individually provisioned CVU refuse instruction creation with 422 and reason `fiat_unsupported_mode`; use the funding endpoint itself for that route. The pooled route owner is derived server-side and never accepted from the caller. The instruction carries the payment reference that makes pooled coordinates usable, so every request — standalone or linked to an endpoint — is first checked for account admission, before the route availability, the route owner or the endpoint mode is resolved: the account must not be suspended or closed; a client account needs a verified client and an enterprise master account a verified enterprise, and the enterprise behind the account (the parent of the client, or the owner of the master account) must be operational and unrestricted (one still being admitted, offboarding, terminated or restricted is refused); a master account owned by a platform operator is decided on its own status alone. A refused account returns `422` with `code = not_admissible`, `data.reason` one of `CLIENT_NOT_VERIFIED`, `ENTERPRISE_NOT_VERIFIED`, `ENTERPRISE_NOT_OPERATIONAL`, `ENTERPRISE_RESTRICTED`, `ACCOUNT_SUSPENDED`, `ACCOUNT_CLOSED`, `CLIENT_SUSPENDED`, `CLIENT_CLOSED` and `data.source` naming the check that refused (`verification`, `lifecycle`); when admission cannot be checked the request returns `503 temporarily_unavailable`. Neither response creates an instruction. An idempotent retry is checked again, so an account refused since its first request gets the refusal instead of the stored instruction. Idempotent on the required `Idempotency-Key` header; an `idempotency_key` body field is rejected. On fiat resources, `fiat_routing.bank_details` carries the receive details a provider issues — `provider_payment_reference` (`required` says whether a payment without it can fail), `account_holder_address`, `bank_address` and `correspondent_bank` — always present, `null` when the provider issued none. `provider_payment_reference` is the provider's own reference, separate from the pooled ISO 11649 `reference`.

## Parameters

| Name | Location | Type | Required | Description and constraints |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | Yes | Client-generated key, 1-128 characters. Accepted on POST requests and required where marked. For the same concrete path and caller/subject/tenant scope, an identical body replays the original status and body; a different body returns 409 idempotency_conflict. Keep query parameters unchanged when retrying. minLength: 1; maxLength: 128 |

## Request

Required request body.

### Request body schema

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_ref` | string | Yes | pattern: `^(master-accounts\|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$` |
| `funding_endpoint_id` | string or null | No |  |
| `rail_class` | "fiat" | Yes |  |
| `routing` | object | Yes | No additional fields |

Additional fields are not accepted.

#### Request body schema.funding_endpoint_id

At least one alternative must match.

##### Request body schema.funding_endpoint_id: alternative 1

Type: `string`. format: uuid; pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$`

##### Request body schema.funding_endpoint_id: alternative 2

Type: `null`. 

#### Request body schema.routing

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `bank_details` | object or object or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `reference` | string or null | No |  |

Additional fields are not accepted.

##### Request body schema.routing.bank_details

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1

Exactly one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `provider_payment_reference` | object or null | No |  |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.account_holder_address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_name

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bank_name: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bic

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### Request body schema.routing.bank_details: alternative 1: alternative 1.bic: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 1.provider_payment_reference

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `provider_payment_reference` | object or null | No |  |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_holder_address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.account_type: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_name

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bank_name: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bic

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### Request body schema.routing.bank_details: alternative 1: alternative 2.bic: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.provider_payment_reference

At least one alternative must match.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 2

Type: `null`. 

###### Request body schema.routing.bank_details: alternative 1: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### Request body schema.routing.bank_details: alternative 1: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### Request body schema.routing.bank_details: alternative 2

Type: `null`. 

##### Request body schema.routing.reference

At least one alternative must match.

###### Request body schema.routing.reference: alternative 1

Type: `string`. 

###### Request body schema.routing.reference: alternative 2

Type: `null`.

**Request URL — POST**
```http
POST /deposit-instructions
```

**Request Body — application/json**
```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "funding_endpoint_id": null,
  "rail_class": "fiat",
  "routing": {
    "asset": "EUR",
    "fiat_rail": "sepa_credit_transfer"
  }
}
```

## Responses

**201 Resource created successfully**

Resource created successfully.

```json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "asset": "EUR",
  "created_at": "2026-05-01T10:00:00Z",
  "crypto_routing": null,
  "expires_at": null,
  "fiat_routing": {
    "asset": "EUR",
    "bank_details": {
      "account_holder_address": null,
      "account_holder_name": "Example Treasury",
      "bank_address": null,
      "bank_name": "Demo Bank",
      "bic": "COBADEFFXXX",
      "correspondent_bank": null,
      "country": "DE",
      "iban": "DE89370400440532013000",
      "provider_payment_reference": null,
      "scheme": "iban"
    },
    "fiat_rail": "sepa_credit_transfer",
    "reference": "RF18539007547034"
  },
  "funding_endpoint_id": null,
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "rail_class": "fiat",
  "updated_at": "2026-05-01T10:00:00Z"
}
```

**400 Invalid request payload**

Invalid request payload, query, or parameter shape.

**401 Caller is not authenticated or the bearer token is invalid**

Caller is not authenticated or the bearer token is invalid.

**403 Caller lacks the required capability or permitted scope**

Caller lacks the required capability or permitted scope.

**404 Resource not found**

Resource not found.

**409 State conflict — the request cannot be applied to the current resource state**

State conflict — the request cannot be applied to the current resource state.

**422 The request cannot be processed under the resource or route contract**

The request cannot be processed under the resource or route contract. Depending on the endpoint, code can be not_admissible or unsupported_currency; inspect the documented code and data.reason.

**500 An unexpected internal failure occurred**

An unexpected internal failure occurred. The public error code is temporarily_unavailable; internal details are not exposed.

**502 Upstream service returned an unexpected error**

Upstream service returned an unexpected error.

**503 Service is temporarily unavailable**

Service is temporarily unavailable; retry with backoff.
### Response 201 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_ref` | string | Yes | pattern: `^(master-accounts\|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$` |
| `asset` | string or null | No |  |
| `created_at` | string | Yes | format: date-time; pattern: `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$` |
| `crypto_routing` | object or null | No |  |
| `expires_at` | string or null | No |  |
| `fiat_routing` | object or null | No |  |
| `funding_endpoint_id` | string or null | Yes |  |
| `id` | string | Yes | format: uuid; pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$` |
| `rail_class` | "fiat" / "crypto" | Yes |  |
| `updated_at` | string | Yes | format: date-time; pattern: `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$` |

Additional fields are not accepted.

##### application/json body.asset

At least one alternative must match.

###### application/json body.asset: alternative 1

Currency code (ISO-4217 or on-chain ticker)

Type: `string`. pattern: `^[A-Z0-9]{1,16}$`

###### application/json body.asset: alternative 2

Type: `null`. 

##### application/json body.crypto_routing

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `endpoint` | object | Yes | No additional fields |
| `network` | string | Yes | minLength: 1 |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.endpoint

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `address` | string | Yes | minLength: 1; maxLength: 256 |
| `memo` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.crypto_routing: alternative 1.endpoint.memo

At least one alternative must match.

###### application/json body.crypto_routing: alternative 1.endpoint.memo: alternative 1

Type: `string`. 

###### application/json body.crypto_routing: alternative 1.endpoint.memo: alternative 2

Type: `null`. 

###### application/json body.crypto_routing: alternative 2

Type: `null`. 

##### application/json body.expires_at

At least one alternative must match.

###### application/json body.expires_at: alternative 1

Type: `string`. format: date-time; pattern: `^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$`

###### application/json body.expires_at: alternative 2

Type: `null`. 

##### application/json body.fiat_routing

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `bank_details` | object or object or null | No |  |
| `fiat_rail` | "sepa_credit_transfer" / "faster_payments" / "swift" / "local_bank_transfer" / "fedwire" | Yes |  |
| `reference` | string or null | No |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1

Exactly one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `iban` | string | Yes | minLength: 1; maxLength: 34 |
| `provider_payment_reference` | object or null | No |  |
| `scheme` | "iban" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 1.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `account_holder_address` | object or null | No |  |
| `account_holder_name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string | Yes | minLength: 1; maxLength: 64 |
| `account_type` | "checking" / "savings" or null | No | Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept. |
| `bank_address` | object or null | No | Postal address of the bank that holds the account. |
| `bank_name` | string or null | Yes |  |
| `bic` | string or null | Yes |  |
| `correspondent_bank` | object or null | No |  |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `provider_payment_reference` | object or null | No |  |
| `routing_codes` | object[] | Yes | minItems: 1; maxItems: 16 |
| `scheme` | "local_account" | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_holder_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type

Checking or savings. Required by some payout rails (a US domestic wire); null or absent where the rail has no such concept.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 1

Type: `"checking" / "savings"`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.account_type: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address

Postal address of the bank that holds the account.

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bank_name: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 1

Type: `string`. minLength: 1; maxLength: 11

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.bic: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `name` | string | Yes | minLength: 1; maxLength: 140 |
| `account_number` | string or null | Yes |  |
| `address` | object or null | Yes |  |
| `bic` | string | Yes | minLength: 1; maxLength: 11 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 1

Type: `string`. minLength: 1; maxLength: 64

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.account_number: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `city` | string | Yes | minLength: 1; maxLength: 140 |
| `country` | string | Yes | pattern: `^[A-Z]{2}$` |
| `lines` | string[] | Yes | minItems: 1; maxItems: 4 |
| `postal_code` | string or null | Yes |  |
| `region` | string or null | Yes |  |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines

Type: `string[]`. minItems: 1; maxItems: 4

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.lines item

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 1

Type: `string`. minLength: 1; maxLength: 32

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.postal_code: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 1

Type: `string`. minLength: 1; maxLength: 140

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 1.region: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 1.address: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.correspondent_bank: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 1

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `required` | boolean | Yes |  |
| `value` | string | Yes | minLength: 1; maxLength: 140 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.provider_payment_reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes

Type: `object[]`. minItems: 1; maxItems: 16

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 1: alternative 2.routing_codes item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `type` | string | Yes | minLength: 1; maxLength: 64 |
| `value` | string | Yes | minLength: 1; maxLength: 64 |

Additional fields are not accepted.

###### application/json body.fiat_routing: alternative 1.bank_details: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 1.reference

At least one alternative must match.

###### application/json body.fiat_routing: alternative 1.reference: alternative 1

Type: `string`. 

###### application/json body.fiat_routing: alternative 1.reference: alternative 2

Type: `null`. 

###### application/json body.fiat_routing: alternative 2

Type: `null`. 

##### application/json body.funding_endpoint_id

At least one alternative must match.

###### application/json body.funding_endpoint_id: alternative 1

Type: `string`. format: uuid; pattern: `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$`

###### application/json body.funding_endpoint_id: alternative 2

Type: `null`.

### Response 400 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string | Yes |  |
| `data` | object | No | No additional fields |
| `details` | object | No | Additional fields allowed |
| `message` | string | Yes |  |

Additional fields are not accepted.

##### application/json body.data

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `acr_values` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `blockers` | object[] | No | For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition. |
| `code` | string | No | For legal refusals: the document code the refusal is about. |
| `max_age` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `max_source_amount` | object | No | For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum. No additional fields |
| `min_source_amount` | object | No | For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included. No additional fields |
| `published_version` | string | No | For `document_version_superseded`: the version currently published. |
| `reason` | string | No | Typed refinement of `code`, from the failing service's contract. |
| `resource` | string | No | Resource kind a `resource_not_found` refers to. |
| `retry_after_ms` | integer | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
| `source` | string | No | For `not_admissible`: the gate that denied (verification, lifecycle, policy, compliance). |

Additional fields are not accepted.

###### application/json body.data.blockers

For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition.

Type: `object[]`. 

###### application/json body.data.blockers item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string | Yes |  |
| `type` | "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes |  |
| `assets` | object[] | No | minItems: 1 |
| `count` | integer | No | minimum: 0; maximum: 9007199254740991 |

Additional fields are not accepted.

###### application/json body.data.blockers item.assets

Type: `object[]`. minItems: 1

###### application/json body.data.blockers item.assets item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `kind` | "balance" / "held" / "owed" / "unsettled" | Yes |  |

Additional fields are not accepted.

###### application/json body.data.max_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

###### application/json body.data.min_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

### Response 401 schema

Content type: `application/json`.

#### application/json body

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `code` | string | Yes |  |
| `data` | object | No | No additional fields |
| `details` | object | No | Additional fields allowed |
| `message` | string | Yes |  |

Additional fields are not accepted.

##### application/json body.data

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `acr_values` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `blockers` | object[] | No | For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition. |
| `code` | string | No | For legal refusals: the document code the refusal is about. |
| `max_age` | string | No | RFC 9470 step-up challenge (`insufficient_user_authentication`). |
| `max_source_amount` | object or null | No | For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum. No additional fields |
| `min_source_amount` | object | No | For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included. No additional fields |
| `published_version` | string | No | For `document_version_superseded`: the version currently published. |
| `reason` | string | No | Typed refinement of `code`, from the failing service's contract. |
| `resource` | string | No | Resource kind a `resource_not_found` refers to. |
| `retry_after_ms` | integer or null | No | Suggested back-off in milliseconds for throttling or temporary unavailability; null means no delay is known. minimum: 0 |
| `source` | string | No | For `not_admissible`: the gate that denied (verification, lifecycle, policy, compliance). |

Additional fields are not accepted.

###### application/json body.data.blockers

For `closure_preconditions_not_met` on a terminal lifecycle verb: what must be resolved before the transition.

Type: `object[]`. 

###### application/json body.data.blockers item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `description` | string | Yes |  |
| `type` | "non_zero_balance" / "active_sub_resources" / "pending_operations" / "active_users" / "active_service_accounts" / "active_role_assignments" | Yes |  |
| `assets` | object[] | No | minItems: 1 |
| `count` | integer | No | minimum: 0; maximum: 9007199254740991 |

Additional fields are not accepted.

###### application/json body.data.blockers item.assets

Type: `object[]`. minItems: 1

###### application/json body.data.blockers item.assets item

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `asset` | string | Yes | Currency code (ISO-4217 or on-chain ticker) pattern: `^[A-Z0-9]{1,16}$` |
| `kind` | "balance" / "held" / "owed" / "unsettled" | Yes |  |

Additional fields are not accepted.

###### application/json body.data.max_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the product maximum in source asset units; null means no maximum.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

###### application/json body.data.min_source_amount

For `amount_below_minimum` / `amount_above_maximum`: the effective minimum in source asset units, fees included.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `currency` | string | Yes |  |
| `value` | string | Yes |  |

Additional fields are not accepted.

### Response 403 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 404 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 409 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 422 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 500 schema

Content type: `application/json`.

See [response 401 schema](#response-401-schema).

### Response 502 schema

Content type: `application/json`.

See [response 400 schema](#response-400-schema).

### Response 503 schema

Content type: `application/json`.

See [response 400 schema](#response-400-schema).
