Add bank payment method

Adds a new bank account payment method for a payee. Supports pay-to-bank transfers with account and routing number details for United States and Great Britain bank accounts. **Path Parameters** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `payee_id` | UUID | Yes | ID of the payee to add the payment method to | **Request Body — bank account shapes** Send **`country_code`**, **`currency_code`**, **`routing_number_type`**, **`account_number`**, and **`routing_number`** consistent with one of the supported rows below. Internally inconsistent combinations (for example US country with an IBAN-shaped account, or GB with ABA routing) return **`400`** validation errors. | Region | `country_code` | `currency_code` | `routing_number_type` | `account_number` | `routing_number` | |--------|----------------|-----------------|------------------------|------------------|------------------| | United States | `US` | `USD` | `aba` (default) | Domestic US account number (digits; not IBAN-shaped) | 9-digit ABA routing number | | Great Britain | `GB` | `GBP` | `bic` | Valid **GB** IBAN | BIC / SWIFT (**8** or **11** characters) | **When `country_code` and `currency_code` are omitted** They default to **`US`** and **`USD`**; `routing_number_type` defaults to **`aba`**. **Great Britain notes** - IBAN must validate structurally (including check digits) and use the **`GB`** country prefix for v1. - On create, verification may return **`pending`**; use GET list/detail on payment methods or webhooks to observe **`verified`** or **`failed`**. **Request Body fields** | Field | Type | Required | Description | Validation Rules | |-------|------|----------|-------------|-----------------| | `account_number` | String | Yes | Account identifier | **US:** digits-only domestic account (max length per API). **GB:** IBAN (GB prefix, valid checksum). | | `routing_number` | String | Yes | Routing identifier | **US:** 9-digit ABA. **GB:** BIC/SWIFT per `routing_number_type` `bic`. | | `routing_number_type` | String | No | `aba` or `bic` | Must match `country_code` row in the matrix above (GB requires `bic`). | | `currency_code` | String | No | ISO 4217 code | Must pair with `country_code` per supported pairs (`USD`↔`US`, `GBP`↔`GB`). | | `country_code` | String | No | ISO 3166-1 alpha-2 | `US` or `GB` for supported payee bank accounts. | **Response Body** | Field | Type | Description | |-------|------|-------------| | `id` | UUID | Unique identifier for the payment method | | `payee_id` | UUID | ID of the payee associated with the payment method | | `account_last_four` | String | Last four characters/digits derived from the account number for display | | `routing_number` | String | Routing identifier stored for the payment method | | `currency_code` | String | ISO 4217 currency code of the account | | `country_code` | String | ISO 3166-1 alpha-2 country code of the bank account | | `verification_status` | String | Current verification status (`pending`, `verified`, or `failed`) | | `is_default` | Boolean | Whether this is the default payment method for the payee | | `supported_rails` | Array | Rails available for this payment method given country, currency, and bank configuration | | `created_at` | DateTime | Timestamp when the payment method was created | | `updated_at` | DateTime | Timestamp when the payment method was last updated | | `warning` | String | Optional. Present on 207 responses when the payment method was created but not set as default | **Success Responses** | Status Code | Description | |-------------|-------------| | 201 | Created - The payment method was successfully added and set as default (if requested) | | 207 | Multi-Status - The payment method was created but not set as default due to verification status. Check `warning` for details. | **Error Responses** | Status Code | Error Code | Description | |-------------|------------|-------------| | 400 | VALIDATION_ERROR | The provided data failed validation | | 401 | AUTHENTICATION_ERROR | Authentication credentials are invalid or missing | | 403 | AUTHORIZATION_ERROR | You do not have permission to perform this action | | 404 | NOT_FOUND | The specified payee was not found | | 409 | DUPLICATE_RESOURCE | A payment method with these details already exists | | 422 | INVALID_PAYMENT_DETAILS | The payment details are invalid or incomplete |