# Supported Countries

Retrieve supported countries for KYC and transaction flows as part of the configuration data required to build onboarding and transaction flows.
**Use Cases**:
- Populate country dropdowns during customer onboarding
- Determine which countries are enabled for your merchant configuration
- Retrieve state or province options for countries that require region selection
- Filter valid options based on customer location

**Response Structure**: Each country includes:
- `id`: Two-letter ISO country code
- `description`: Human-readable country name
- `states`: List of supported states or provinces for that country, if applicable

Endpoint: GET /eapi/v0/countries
Version: 0 BETA
Security: HMACAuth

## Security:

  - `HMACAuth` (unknown)
    apiKey in header Authorization

## Response 200:

  - `200` (unknown)
    Successful response with supported countries and their states or provinces where applicable.

## Response 200 fields (application/json):

  - `id` (string, required)
    Two-letter ISO 3166-1 alpha-2 country code.
    Example: US

  - `description` (string, required)
    Human-readable name of the country.
    Example: United States

  - `states` (array, required)
    List of supported states or provinces for the country. Empty when the country does not require region selection.

  - `states.id` (string, required)
    Short code identifying the state or province.
    Example: CA

  - `states.description` (string, required)
    Human-readable name of the state or province.
    Example: California

## Response 400:

  - `400` (unknown)
    Bad request due to invalid input.
**Common Causes**:
- Malformed JSON in request body
- Invalid data types
- Missing required fields
- Invalid request structure

## Response 400 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Bad Request

  - `code` (integer)
    HTTP status code
    Example: 400

  - `traceId` (string)
    Unique identifier for this error instance. Use this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 401:

  - `401` (unknown)
    Authentication failed or missing credentials.
**Common Causes**:
- Missing Authorization header
- Invalid API key
- Expired or invalid HMAC signature
- Incorrect timestamp (must be within 5 minutes of server time)

## Response 401 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Unauthenticated.

  - `code` (integer)
    HTTP status code
    Example: 401

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 429:

  - `429` (unknown)
    Rate limit exceeded.
**Rate Limits**:
- General API: 100 requests per minute
- Price endpoint: 60 requests per minute

**Action**: Wait for the duration specified in `Retry-After` header before retrying.

## Response 429 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Too Many Requests. Please try again later.

  - `code` (integer)
    HTTP status code
    Example: 429

  - `traceId` (string)
    Unique identifier for this error instance
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 429 headers (application/json):

  - `Retry-After` (integer)
    Number of seconds to wait before retrying.

**Important**: Always respect this header to avoid further rate limiting.
    Example: 60

## Response 500:

  - `500` (unknown)
    Unexpected server error.
**Action**:
- Retry with exponential backoff (up to 3 attempts)
- If error persists, contact support with the traceId

**Note**: This is a temporary issue on our side, not a problem with your request.

## Response 500 fields (application/json):

  - `message` (string)
    Human-readable error message
    Example: Server Error

  - `code` (integer)
    HTTP status code
    Example: 500

  - `traceId` (string)
    Unique identifier for this error instance. **Important**: Include this when contacting support.
    Example: 2b6fc5d0-57e4-4b5a-9e3c-6cfbb6d8023f

## Response 200 examples:

  - `Supported countries response` (unknown)
    Example response showing countries with and without state or province lists.