Countries

Access country reference data including country codes, names, and supported currencies.

List Countries

Get a list of all available countries.

Endpoint

GET /api/v1/countries

Authentication: API Key + Secret required

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Number of results per page (default: 50, max: 10000)
page	number	No	Page number (default: 1)
search	string	No	Search countries by name or code

Response

Headers

X-Page: 1
X-Per-Page: 50
X-Total-Count: 195
X-Total-Pages: 4
X-Page-Size: 50
X-Has-More: true

Body

[
  {
    "id": 1,
    "code": "US",
    "name": "United States",
    "currency_code": "USD",
    "is_active": true,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  },
  {
    "id": 2,
    "code": "GB",
    "name": "United Kingdom",
    "currency_code": "GBP",
    "is_active": true,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z"
  }
]

Pagination Headers

Header	Type	Description
X-Page	number	Current page number
X-Per-Page	number	Items per page
X-Total-Count	number	Total number of items
X-Total-Pages	number	Total number of pages
X-Page-Size	number	Actual items in current page
X-Has-More	boolean	Whether more pages are available

Country Object

Field	Type	Description
id	number	Unique country identifier
code	string	ISO 3166-1 alpha-2 country code
name	string	Country display name
currency_code	string	ISO 4217 currency code
is_active	boolean	Whether country is active/supported
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Examples

# Get all countries (use -i to see headers)
curl -X GET "{{host}}/api/v1/countries" -i \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

# Search for specific countries with pagination headers
curl -X GET "{{host}}/api/v1/countries?search=united&limit=10" -i \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

Get Country by ID

Get details for a specific country.

Endpoint

GET /api/v1/countries/{id}

Authentication: API Key + Secret required

Path Parameters

Parameter	Type	Required	Description
id	number	Yes	Country ID

Response

{
  "id": 1,
  "code": "US",
  "name": "United States",
  "currency_code": "USD",
  "is_active": true,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z"
}

Error Responses

404 Not Found

{
  "error": "Not Found",
  "message": "Country not found"
}

Examples

curl -X GET "{{host}}/api/v1/countries/1" \
  -H "X-API-Key: sk_live_abc123def456" \
  -H "X-API-Secret: your-secret-here"

Countries

On this page