---
updatedAt: 2026-06-05T14:02:48.000Z
---
Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# Register IBAN account
Register a new International Bank Account Number (IBAN) bank account.
IBAN is a standardized international system developed to identify bank accounts when making international transactions. For more information, refer to What Is an International Bank Account Number (IBAN) and How Does It Work.
To read about Pismo's banking offerings, see [Banking overview](doc:banking-overview).
This endpoint generates a Bank account registered event.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Banking - Bank accounts",
"version": "1.0.0",
"description": "API for managing bank accounts in global formats",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/intl-bankaccounts",
"description": "Sandbox API server for testing"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Bank accounts",
"description": "Bank account management endpoints"
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Account token - token encoded with Pismo account ID. Tokens can expire quickly, which can result in an **401 Unauthorized** error.",
"bearerFormat": "JWT"
}
},
"parameters": {
"accountIDpath": {
"name": "accountId",
"in": "path",
"description": "Pismo account ID",
"required": true,
"schema": {
"type": "string"
},
"example": "78123456"
},
"authHeader": {
"name": "Authorization",
"in": "header",
"description": "Account token - Token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a **401 Unauthorized** error. \n",
"required": true,
"schema": {
"type": "string"
},
"example": 1234
}
},
"schemas": {
"accountID": {
"type": "integer",
"description": "Account ID",
"example": 78123456
},
"creationDatetime": {
"type": "string",
"format": "date-time",
"description": "Account creation date time displayed in ISO 8601 format `2023-04-12T23:20:50.52Z`.",
"example": "2023-04-12T23:20:50.52Z"
},
"domain.Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error type code",
"example": "EIBA0001"
},
"details": {
"type": "string",
"description": "Error details",
"example": "Key not found"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Key not found"
}
}
},
"intlbankaccounts.IbanScheme": {
"type": "object",
"required": [
"iban"
],
"properties": {
"iban": {
"type": "string",
"maxLength": 34,
"description": "International Bank Account Number (IBAN).\n\nIBAN structure varies by country, but typically includes a 2 letter country code, two check digits for error detection, a bank identifier and an account number.\n",
"example": "GB29NWBK60161331926819"
}
}
},
"intlbankaccounts.IntlBankAccountIbanRequest": {
"type": "object",
"required": [
"scheme"
],
"properties": {
"scheme": {
"$ref": "#/components/schemas/intlbankaccounts.IbanScheme"
},
"metadata": {
"$ref": "#/components/schemas/metadata"
}
}
},
"intlbankaccounts.IntlBankAccountIbanResponse": {
"type": "object",
"required": [
"scheme"
],
"properties": {
"account_id": {
"$ref": "#/components/schemas/accountID"
},
"creation_datetime": {
"$ref": "#/components/schemas/creationDatetime"
},
"metadata": {
"$ref": "#/components/schemas/metadata"
},
"scheme": {
"$ref": "#/components/schemas/intlbankaccounts.IbanScheme"
}
}
},
"metadata": {
"additionalProperties": true,
"type": "object",
"description": "A set of key-value pairs used to store custom data or additional information.
\n\n**Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis).\n"
}
}
},
"paths": {
"/v2/accounts/{accountId}/bank-accounts/iban": {
"post": {
"tags": [
"Bank accounts"
],
"summary": "Register IBAN account",
"description": "Register a new International Bank Account Number (IBAN) bank account. \n\nIBAN is a standardized international system developed to identify bank accounts when making international transactions. For more information, refer to What Is an International Bank Account Number (IBAN) and How Does It Work.\n\nTo read about Pismo's banking offerings, see [Banking overview](https://developers.pismo.io/pismo-docs/docs/banking-overview).\n\nThis endpoint generates a Bank account registered event.\n",
"operationId": "post-intl-bank-accounts-v2-accounts-account-id-bank-accounts-iban",
"parameters": [
{
"$ref": "#/components/parameters/authHeader"
},
{
"$ref": "#/components/parameters/accountIDpath"
}
],
"requestBody": {
"description": "Register IBAN request Body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/intlbankaccounts.IntlBankAccountIbanRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Response body",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/intlbankaccounts.IntlBankAccountIbanResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIBA0009": {
"summary": "Validation Error",
"value": {
"code": "EIBA0009",
"message": "Validation error"
}
},
"EIBA0012": {
"summary": "Accounts API invalid request",
"value": {
"code": "EIBA0012",
"message": "Accounts - API returned 4xx error"
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIBA0006": {
"summary": "Missing tenant header",
"value": {
"code": "EIBA0006",
"message": "Missing required header: 'x-tenant'"
}
},
"EIBA0007": {
"summary": "Invalid account ID header",
"value": {
"code": "EIBA0007",
"message": "Invalid account ID header: 'x-account-id'"
}
},
"EIBA0023": {
"summary": "Account status not NORMAL",
"value": {
"code": "EIBA0023",
"message": "Account status not NORMAL"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIBA0010": {
"summary": "Account not found",
"value": {
"code": "EIBA0010",
"message": "Account not found"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIBA0028": {
"summary": "IntlBankAccount Already Exists",
"value": {
"code": "EIBA0028",
"message": "IntlBankAccount - Already Exists"
}
}
}
}
}
},
"500": {
"description": "Internal Server",
"headers": {
"x-cid": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/domain.Error"
},
"examples": {
"EIBA0005": {
"summary": "HTTP error",
"value": {
"code": "EIBA0005",
"message": "HTTP error"
}
},
"EIBA0011": {
"summary": "Accounts API server error",
"value": {
"code": "EIBA0011",
"message": "Accounts - API returned 5xx error"
}
},
"EIBA0013": {
"summary": "Accounts API timeout",
"value": {
"code": "EIBA0013",
"message": "Accounts - API timeout"
}
},
"EIBA0015": {
"summary": "Database error",
"value": {
"code": "EIBA0015",
"message": "Database internal error"
}
}
}
}
}
}
},
"x-codegen-request-body-name": "RequestBody"
}
}
}
}
```