Description

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 handling
common/auth - Authentication
common/logger - Logging functionality
common/rbac - Role-based access control
modules/currencies - Currency validation

Description

On this page