Description
Purpose and use
Countries define the jurisdiction and formatting data needed for onboarding, addresses, bank accounts, IBAN validation, payments, risk review, and reporting.
Who uses this. Onboarding teams, payment operations, compliance officers, product administrators, and support teams use country records when validating customer and payment data.
How it works. Each country stores ISO identifiers, activity state, currency context, IBAN metadata, regional attributes, and optional risk or payment flags.
What users do. Users review supported countries, validate country codes, confirm IBAN requirements, and deactivate countries that should not be used for new activity.
Outcomes and side effects. Country changes can affect onboarding validation, transfer eligibility, address forms, and risk rules. They do not change existing ledger balances.
Related manuals: Addresses, NOGA, Risk Assessment, Transfers.
Overview
The countries package provides functionality for managing country data, including ISO codes, IBAN formats, and regional settings. It supports country-specific validations for banking operations.
API Methods
Get All Countries
GET /v1/countries
Retrieves a list of all supported countries with their details.
Response
{
"countries": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Switzerland",
"iso_alpha_2": "CH",
"iso_alpha_3": "CHE",
"iso_numeric": "756",
"iban_length": 21,
"iban_format": "CH[0-9]{2}[0-9]{5}[A-Z0-9]{12}",
"currency_code": "CHF",
"active": true,
"metadata": {
"eu_member": false,
"sepa_member": true,
"risk_level": "low"
}
}
],
"total": 195,
"page": 1,
"per_page": 20
}Get Country by ID
GET /v1/countries/{id}
Retrieves detailed information about a specific country.
Get Country by ISO Code
GET /v1/countries/iso/{code}
Retrieves country information using ISO alpha-2 or alpha-3 code.
Response
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Switzerland",
"iso_alpha_2": "CH",
"iso_alpha_3": "CHE",
"iso_numeric": "756",
"iban_length": 21,
"iban_format": "CH[0-9]{2}[0-9]{5}[A-Z0-9]{12}",
"currency_code": "CHF",
"active": true,
"metadata": {
"eu_member": false,
"sepa_member": true,
"risk_level": "low",
"supported_documents": ["passport", "id_card", "residence_permit"]
},
"created_at": "2024-03-20T10:00:00Z",
"updated_at": "2024-03-20T10:00:00Z"
}Create Country
POST /v1/countries
Creates a new country entry in the system.
Request
{
"name": "Switzerland",
"iso_alpha_2": "CH",
"iso_alpha_3": "CHE",
"iso_numeric": "756",
"iban_length": 21,
"iban_format": "CH[0-9]{2}[0-9]{5}[A-Z0-9]{12}",
"currency_code": "CHF",
"active": true,
"metadata": {
"eu_member": false,
"sepa_member": true,
"risk_level": "low",
"supported_documents": ["passport", "id_card", "residence_permit"]
}
}Response
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Switzerland",
"iso_alpha_2": "CH",
"iso_alpha_3": "CHE",
"iso_numeric": "756",
"iban_length": 21,
"iban_format": "CH[0-9]{2}[0-9]{5}[A-Z0-9]{12}",
"currency_code": "CHF",
"active": true,
"metadata": {
"eu_member": false,
"sepa_member": true,
"risk_level": "low",
"supported_documents": ["passport", "id_card", "residence_permit"]
},
"created_at": "2024-03-20T10:00:00Z",
"updated_at": "2024-03-20T10:00:00Z"
}Update Country
PUT /v1/countries/{id}
Updates an existing country's information.
Input
{
"name": "string",
"iso_alpha_2": "string",
"iso_alpha_3": "string",
"iso_numeric": "string",
"iban_length": "number",
"currency_code": "string",
"active": true,
"metadata": {}
}Delete Country
DELETE /v1/countries/{id}
Deactivates a country in the system.
Error Codes
| Code | Description |
|---|---|
| countries_m.bad_record_id | Invalid country record ID provided |
| countries_m.failed_to_serialize | Failed to serialize or deserialize request/response payload |
| countries_m.country_not_found | Country not found |
Dependencies
common/errs- Error handlingcommon/auth- Authenticationcommon/logger- Logging functionalitycommon/rbac- Role-based access controlmodules/currencies- Currency validation