> For the complete documentation index, see [llms.txt](https://docs.nexusglobalpayments.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexusglobalpayments.org/apis/countries.md).

# Countries

## Countries

## Retrieve All Countries in Nexus

> Returns all countries available on the Nexus network, along with key reference data for sending payments to those countries, such as maximum transaction amounts and requirements for category purpose codes.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"Countries","description":"Country reference data and payment constraints, including supported instruction priorities, SLA execution timeouts, currency amount ranges (min/max), and purpose-code requirements."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusOAuth":["countries.read"]}],"components":{"securitySchemes":{"nexusOAuth":{"type":"oauth2","description":"OAuth2 client credentials token issued per participant.","flows":{"clientCredentials":{"tokenUrl":"https://auth.nexus.net/realms/nexus/protocol/openid-connect/token","scopes":{"countries.read":"Read country and currency reference data","address.read":"Read address types and input definitions","institutions.read":"Read the financial institution directory","quotes.read":"Retrieve FX quotes for a corridor and amount","quote.read":"Compute fees and settlement amounts from a PSP supplied rate","fees.read":"Retrieve the Destination Agent fee formula","payment.process":"Submit and receive ISO 20022 payment messages","admin.downtime.notify":"Submit admi.004 downtime notifications for a Direct Participant IPS","fxp.payment.read":"Query the FXP's own completed payments","rates.read":"Read FXP rate records.","rates.write":"Create or withdraw FXP rate records.","tiers.read":"Read FXP tier records.","tiers.write":"Create or withdraw FXP tier records.","relationships.read":"Read FXP–PSP relationship records.","relationships.write":"Create, update, or delete FXP–PSP relationship records."}}}}},"schemas":{"CountriesResponse":{"type":"object","description":"Response containing a list of supported countries.","properties":{"countries":{"type":"array","description":"List of supported countries.","items":{"$ref":"#/components/schemas/CountryResponse"}}},"required":["countries"]},"CountryResponse":{"type":"object","description":"Country reference data with supported currencies, SLA configuration, and message requirements.","properties":{"countryId":{"type":"integer","format":"int32","description":"Internal country identifier."},"countryCode":{"type":"string","description":"The ISO 3166 alpha-2 country code","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"},"name":{"type":"string","description":"Country display name."},"currencies":{"type":"array","description":"Supported currencies with optional IPS max amount.","items":{"$ref":"#/components/schemas/CountryCurrencyResponse"}},"requiredMessageElements":{"$ref":"#/components/schemas/RequiredMessageElementsResponse","description":"Required ISO 20022 message elements for routing."},"supportedInstructionPriorities":{"type":"array","description":"Supported instruction priorities for payments to this country.","items":{"type":"string"}},"sla":{"$ref":"#/components/schemas/SlaResponse","description":"SLA timeout configuration for payment execution."}},"required":["countryCode","countryId","currencies","name"]},"CountryCurrencyResponse":{"type":"object","description":"Currency configuration for a country.","properties":{"currencyCode":{"type":"string","description":"The ISO 4217 alpha-3 currency code","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"},"currencyName":{"type":"string","description":"Currency name."},"symbol":{"type":"string","description":"Currency symbol."},"decimalPlaces":{"type":"integer","format":"int32","description":"Currency decimal places."},"minAmount":{"type":"number","description":"Minimum allowed amount for payments in this currency."},"maxAmount":{"type":"number","description":"Optional IPS max amount for the country and currency."}}},"RequiredMessageElementsResponse":{"type":"object","description":"Required ISO 20022 message elements.","properties":{"pacs008":{"type":"array","description":"Required pacs.008 message elements.","items":{"type":"string"}},"getQuotes":{"type":"array","description":"Lists additional parameters the Source PSP must supply on GET /v1/quotes. Present only when the destination country operates multiple IPSes, where it lists destinationPsp to indicate that destFinInstId and destFinInstIdType are required; absent for single-IPS countries.","items":{"type":"string"}}}},"SlaResponse":{"type":"object","description":"SLA timeout configuration for payment execution.","properties":{"normalPaymentMaxExecutionTimeout":{"type":"integer","format":"int32","description":"Maximum execution timeout for normal priority payments, in seconds."},"highPaymentMaxExecutionTimeout":{"type":"integer","format":"int32","description":"Maximum execution timeout for high priority payments, in seconds. Omitted if HIGH priority not supported."}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/countries":{"get":{"tags":["Countries"],"summary":"Retrieve All Countries in Nexus","description":"Returns all countries available on the Nexus network, along with key reference data for sending payments to those countries, such as maximum transaction amounts and requirements for category purpose codes.","operationId":"listCountries","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"If-None-Match","in":"header","description":"Optional. ETag value from a previous response for conditional GET. If it matches the current entity tag, the server returns 304 Not Modified with no body.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A list of countries with payment details.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountriesResponse"}}}},"304":{"description":"Not Modified. The resource has not changed since the last request.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```

## Retrieve a Single Country

> Returns a specified country based on the 2-letter countryCode provided, along with key reference data for sending payments to that country, such as maximum transaction amounts and requirements for category purpose codes.

```json
{"openapi":"3.1.0","info":{"title":"Nexus API","version":"v1"},"tags":[{"name":"Countries","description":"Country reference data and payment constraints, including supported instruction priorities, SLA execution timeouts, currency amount ranges (min/max), and purpose-code requirements."}],"servers":[{"url":"http://localhost:8080","description":"Local simulator (make run / make docker-run)"},{"url":"https://nexus-ai-simulator-683365449922.asia-southeast1.run.app","description":"Deployed simulator (Cloud Run, asia-southeast1) - indicative, not authoritative"}],"security":[{"nexusOAuth":["countries.read"]}],"components":{"securitySchemes":{"nexusOAuth":{"type":"oauth2","description":"OAuth2 client credentials token issued per participant.","flows":{"clientCredentials":{"tokenUrl":"https://auth.nexus.net/realms/nexus/protocol/openid-connect/token","scopes":{"countries.read":"Read country and currency reference data","address.read":"Read address types and input definitions","institutions.read":"Read the financial institution directory","quotes.read":"Retrieve FX quotes for a corridor and amount","quote.read":"Compute fees and settlement amounts from a PSP supplied rate","fees.read":"Retrieve the Destination Agent fee formula","payment.process":"Submit and receive ISO 20022 payment messages","admin.downtime.notify":"Submit admi.004 downtime notifications for a Direct Participant IPS","fxp.payment.read":"Query the FXP's own completed payments","rates.read":"Read FXP rate records.","rates.write":"Create or withdraw FXP rate records.","tiers.read":"Read FXP tier records.","tiers.write":"Create or withdraw FXP tier records.","relationships.read":"Read FXP–PSP relationship records.","relationships.write":"Create, update, or delete FXP–PSP relationship records."}}}}},"schemas":{"CountryResponse":{"type":"object","description":"Country reference data with supported currencies, SLA configuration, and message requirements.","properties":{"countryId":{"type":"integer","format":"int32","description":"Internal country identifier."},"countryCode":{"type":"string","description":"The ISO 3166 alpha-2 country code","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"},"name":{"type":"string","description":"Country display name."},"currencies":{"type":"array","description":"Supported currencies with optional IPS max amount.","items":{"$ref":"#/components/schemas/CountryCurrencyResponse"}},"requiredMessageElements":{"$ref":"#/components/schemas/RequiredMessageElementsResponse","description":"Required ISO 20022 message elements for routing."},"supportedInstructionPriorities":{"type":"array","description":"Supported instruction priorities for payments to this country.","items":{"type":"string"}},"sla":{"$ref":"#/components/schemas/SlaResponse","description":"SLA timeout configuration for payment execution."}},"required":["countryCode","countryId","currencies","name"]},"CountryCurrencyResponse":{"type":"object","description":"Currency configuration for a country.","properties":{"currencyCode":{"type":"string","description":"The ISO 4217 alpha-3 currency code","maxLength":3,"minLength":3,"pattern":"^[A-Z]{3}$"},"currencyName":{"type":"string","description":"Currency name."},"symbol":{"type":"string","description":"Currency symbol."},"decimalPlaces":{"type":"integer","format":"int32","description":"Currency decimal places."},"minAmount":{"type":"number","description":"Minimum allowed amount for payments in this currency."},"maxAmount":{"type":"number","description":"Optional IPS max amount for the country and currency."}}},"RequiredMessageElementsResponse":{"type":"object","description":"Required ISO 20022 message elements.","properties":{"pacs008":{"type":"array","description":"Required pacs.008 message elements.","items":{"type":"string"}},"getQuotes":{"type":"array","description":"Lists additional parameters the Source PSP must supply on GET /v1/quotes. Present only when the destination country operates multiple IPSes, where it lists destinationPsp to indicate that destFinInstId and destFinInstIdType are required; absent for single-IPS countries.","items":{"type":"string"}}}},"SlaResponse":{"type":"object","description":"SLA timeout configuration for payment execution.","properties":{"normalPaymentMaxExecutionTimeout":{"type":"integer","format":"int32","description":"Maximum execution timeout for normal priority payments, in seconds."},"highPaymentMaxExecutionTimeout":{"type":"integer","format":"int32","description":"Maximum execution timeout for high priority payments, in seconds. Omitted if HIGH priority not supported."}}},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the auth sidecar or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, e.g. AE001–AE004, sidecar-enforced), BE (Business Error). BE001–BE020 are raised by the Payments endpoints; BE021–BE027 are raised by the FXP endpoints.","enum":["AE001","AE002","AE003","AE004","BE001","BE002","BE005","BE006","BE007","BE008","BE009","BE011","BE012","BE016","BE017","BE018","BE019","BE020","BE021","BE022","BE023","BE024","BE025","BE026","BE027","TE001","TE002","TE099"],"maxLength":5,"pattern":"[A-Z]{2}[0-9]{3}"},"name":{"type":"string","description":"Machine-readable business error name from the reason code catalogue.","maxLength":50,"pattern":"[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*"},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII (CD-INV-09).","maxLength":500}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/countries/{countryCode}":{"get":{"tags":["Countries"],"summary":"Retrieve a Single Country","description":"Returns a specified country based on the 2-letter countryCode provided, along with key reference data for sending payments to that country, such as maximum transaction amounts and requirements for category purpose codes.","operationId":"getCountryByCode","parameters":[{"name":"Accept","in":"header","description":"application/json","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"countryCode","in":"path","description":"ISO 3166-1 alpha-2 uppercase destination code","required":true,"schema":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"}},{"name":"If-None-Match","in":"header","description":"Optional. ETag value from a previous response for conditional GET. If it matches the current entity tag, the server returns 304 Not Modified with no body.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Country information.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryResponse"}}}},"304":{"description":"Not Modified. The resource has not changed since the last request.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```