Countries
Country reference data and payment constraints, including supported instruction priorities, SLA execution timeouts, currency amount ranges (min/max), and purpose-code requirements.
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.
Response validation rules
200 OK — the body MUST conform to the response schema below. Response objects are open: additional properties may be introduced in later minor versions, and clients MUST ignore properties they do not recognise.
countries
array
Required
N
—
countries[].countryId
integer
Required
N
format int32; ≥ 1; ≤ 999
countries[].countryCode
string
Required
N
pattern ^[A-Z]{2}$; length 2
countries[].name
string
Required
N
min length 1; max length 100
countries[].currencies
array
Required
N
≥ 1 item(s)
countries[].currencies[].currencyCode
string
Required
N
pattern ^[A-Z]{3}$; length 3
countries[].currencies[].currencyName
string
Required
N
min length 1; max length 50
countries[].currencies[].symbol
string
Required
N
min length 1; max length 5
countries[].currencies[].decimalPlaces
integer
Required
N
format int32; ≥ 0; ≤ 4
countries[].currencies[].minAmount
string
Optional
N
pattern ^[0-9]+(\.[0-9]+)?$; max length 18
countries[].currencies[].maxAmount
string
Required
N
pattern ^[0-9]+(\.[0-9]+)?$; max length 18
countries[].requiredMessageElements
object
Required
N
—
countries[].requiredMessageElements.pacs008
array
Required
N
each item: pattern ^/Document/.+
countries[].requiredMessageElements.getQuotes
array
Conditional — present only for multi-IPS destination countries
N
each item: one of destinationPsp
countries[].supportedInstructionPriorities
array
Required
N
unique items; each item: one of NORM, HIGH
countries[].sla
object
Required
N
—
countries[].sla.normalPaymentMaxExecutionTimeout
integer
Required
N
format int32; ≥ 0
countries[].sla.highPaymentMaxExecutionTimeout
integer
Conditional — present only when the country supports HIGH priority; omitted otherwise
N
format int32; ≥ 0
Cross-field rules
currencies[].minAmount/currencies[].maxAmount: fractional digits exactly equalcurrencies[].decimalPlaces; JSON numbers, exponent notation and grouping separators are prohibited.currencieslists only active currencies.sla.highPaymentMaxExecutionTimeoutis present only when the country supportsHIGHpriority (omitted otherwise); it therefore never appears unlesssupportedInstructionPrioritiescontainsHIGH.requiredMessageElements.getQuotesis present only for multi-IPS destination countries and then containsdestinationPsp.supportedInstructionPrioritiesis the union across the country's IPSes;slavalues are the most relaxed (longest) MET across the country's IPSes, in whole seconds.
Response signature — every 200 and 304 response carries Signature-Input and Signature (plus Content-Digest on 200) per the Nexus HTTP Message Signature Profile v1, signed by the responding server. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.
Error responses (4xx/5xx with a body) — the body MUST conform to ErrorApiResponse: statusCode = RJCT; reasonCode matches ^[A-Z]{2}[0-9]{3}$; name is UPPER_SNAKE_CASE (≤ 50); description ≤ 500 characters and MUST NOT contain PII. reasonCode values for this operation: TE099, AE001, AE002, AE003, AE005, AE006, AE004. Gateway errors (405, 429, 502, 503, 504) carry no body.
- : Read country and currency reference data
Mutual TLS: the IPSO presents its X.509 client certificate on every connection, validated during the TLS handshake (fail-closed). The same certificate is the RFC 8705 binding anchor for the OAuth access token (see nexusOAuth).
OAuth2 client-credentials access token issued per participant, presented as Authorization: Bearer <token>. Tokens are certificate-bound per RFC 8705: the token carries a cnf."x5t#S256" confirmation claim recording the SHA-256 thumbprint of the IPSO's mTLS client certificate, and the request is rejected (AE006) when the certificate presented on the connection does not match that thumbprint.
/
*/*Example: */*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.
"a1b2c3"RFC 9421 signature metadata for a request without a body, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). One dictionary member labelled nexus whose covered components are exactly "@method" "@authority" "@path" "@query", followed by "if-none-match" when that header is sent. @query is always covered; an empty query serialises as ?, so query parameters cannot be added or removed undetected. Signature parameters, emitted in this order: created and expires (Unix seconds; expires = created + 300; the receiver rejects created more than ±5 minutes from its clock or a signature past expires), keyid (base64url SHA-256 thumbprint of the signer's signing public key, registered at onboarding; a missing, unknown, expired or revoked key id is rejected - never resolved to a default key), alg (always rsa-pss-sha512) and tag (always nexus-v1). The signature parameters are signed through the @signature-params line of the signature base. A missing, malformed or non-conforming value is rejected with AE005.
nexus=("@method" "@authority" "@path" "@query");created=1786339201;expires=1786339501;keyid="NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs";alg="rsa-pss-sha512";tag="nexus-v1"Pattern: ^nexus=\("@method" "@authority" "@path" "@query"( "if-none-match")?\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid="[A-Za-z0-9_-]{43}";alg="rsa-pss-sha512";tag="nexus-v1"$RFC 9421 signature value: one dictionary member labelled nexus holding an RFC 8941 byte sequence - the standard base64 (not base64url) RSASSA-PSS signature using SHA-512 (rsa-pss-sha512), computed over the RFC 9421 signature base built from the components and parameters declared in Signature-Input. Produced with the sender's own signing private key; the receiver verifies it against the sender's registered signing public key resolved from keyid. With the minimum RSA-3072 key the signature is 384 bytes, i.e. 512 base64 characters. A missing, malformed or non-verifying signature is rejected with AE005.
nexus=:LawWG0POl/CUi7FibnReb4xwyjSBDCyBydn6cSvUUvNCGTOhMK4ZvXp3EaIZFIgBx0rY5gxaLJ6BsbMjaZatNSDJMjT0MjZnkZbSi7KX1tDgYX7nQ8bwwV5fo4n22oVkZkmkSAI5HyhWAjUs8o6gI/RcwoCHh7Y+XzOq/3YohNzYSg71/Z/A020bbRQsKIKvim1pFKIxnTjz7f7V2sRXjpBPu6zjzd0j4BLte5QkVfqBsd36NJtTpNPaMM5cYib0oMqBxlbjkhGIs+PA3nWurx3bdxsPeJLeTQHTBfUamOMTTtgPTn3wEuSv4OGAMa7rs62o6bpOQM9eKsvC4n4j92ek+AQnhb/zuryE9i7GqMTmD3gNnzgFDZM/uzEFPyVK3hC7/NpMzdetg8kP/xRQkppXyJV6JvnW06a1uVTvfj+foMKyaiBj7KZUUAD1ibiU3ualzSxyJZCT70l5mEZofiAWZqxYy+OTjCBmxqd2djmT2CNo115iC3GOPf4iJNDH:Pattern: ^nexus=:[A-Za-z0-9+/]+={0,2}:$A list of countries with payment details.
Not Modified. The resource has not changed since the last request.
Authentication Failure
Authorization Failure
Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.
Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.
Internal Server Error
Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.
Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.
Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.
GET /v1/countries HTTP/1.1
Host: prod.payments.nexus.net
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
Signature-Input: text
Signature: text
{
"countries": [
{
"countryId": 344,
"countryCode": "HK",
"name": "Hong Kong",
"currencies": [
{
"currencyCode": "HKD",
"currencyName": "Hong Kong Dollar",
"symbol": "HK$",
"decimalPlaces": 2,
"minAmount": "100.00",
"maxAmount": "10000.00"
},
{
"currencyCode": "CNY",
"currencyName": "Yuan Renminbi",
"symbol": "¥",
"decimalPlaces": 2,
"minAmount": "100.00",
"maxAmount": "20000.00"
}
],
"requiredMessageElements": {
"getQuotes": [
"destinationPsp"
],
"pacs008": [
"/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/Purp/Cd"
]
},
"supportedInstructionPriorities": [
"NORM",
"HIGH"
],
"sla": {
"normalPaymentMaxExecutionTimeout": 60,
"highPaymentMaxExecutionTimeout": 60
}
},
{
"countryId": 360,
"countryCode": "ID",
"name": "Indonesia",
"currencies": [
{
"currencyCode": "IDR",
"currencyName": "Rupiah",
"symbol": "Rp",
"decimalPlaces": 0,
"minAmount": "100",
"maxAmount": "15000000"
}
],
"requiredMessageElements": {
"pacs008": [
"/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/PmtTpInf/CtgyPurp/Cd"
]
},
"supportedInstructionPriorities": [
"NORM"
],
"sla": {
"normalPaymentMaxExecutionTimeout": 60
}
},
{
"countryId": 458,
"countryCode": "MY",
"name": "Malaysia",
"currencies": [
{
"currencyCode": "MYR",
"currencyName": "Ringgit",
"symbol": "RM",
"decimalPlaces": 2,
"minAmount": "100.00",
"maxAmount": "10000000.00"
}
],
"requiredMessageElements": {
"pacs008": [
"/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/Purp/Cd"
]
},
"supportedInstructionPriorities": [
"NORM",
"HIGH"
],
"sla": {
"normalPaymentMaxExecutionTimeout": 60,
"highPaymentMaxExecutionTimeout": 60
}
},
{
"countryId": 702,
"countryCode": "SG",
"name": "Singapore",
"currencies": [
{
"currencyCode": "SGD",
"currencyName": "Dollar",
"symbol": "$",
"decimalPlaces": 2,
"minAmount": "100.00",
"maxAmount": "200000.00"
}
],
"requiredMessageElements": {
"pacs008": [
"/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/Purp/Cd"
]
},
"supportedInstructionPriorities": [
"NORM",
"HIGH"
],
"sla": {
"normalPaymentMaxExecutionTimeout": 60,
"highPaymentMaxExecutionTimeout": 60
}
},
{
"countryId": 608,
"countryCode": "PH",
"name": "Philippines",
"currencies": [
{
"currencyCode": "PHP",
"currencyName": "Peso",
"symbol": "₱",
"decimalPlaces": 2,
"maxAmount": "50000.00"
}
],
"requiredMessageElements": {
"pacs008": [
"/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/PmtTpInf/CtgyPurp/Cd"
]
},
"supportedInstructionPriorities": [
"NORM"
],
"sla": {
"normalPaymentMaxExecutionTimeout": 60
}
},
{
"countryId": 764,
"countryCode": "TH",
"name": "Thailand",
"currencies": [
{
"currencyCode": "THB",
"currencyName": "Baht",
"symbol": "฿",
"decimalPlaces": 2,
"minAmount": "100.00",
"maxAmount": "2000000.00"
}
],
"requiredMessageElements": {
"pacs008": [
"/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/PmtTpInf/CtgyPurp/Cd"
]
},
"supportedInstructionPriorities": [
"NORM"
],
"sla": {
"normalPaymentMaxExecutionTimeout": 60
}
}
]
}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.
Response validation rules
200 OK — the body MUST conform to the response schema below. Response objects are open: additional properties may be introduced in later minor versions, and clients MUST ignore properties they do not recognise.
countryId
integer
Required
N
format int32; ≥ 1; ≤ 999
countryCode
string
Required
N
pattern ^[A-Z]{2}$; length 2
name
string
Required
N
min length 1; max length 100
currencies
array
Required
N
≥ 1 item(s)
currencies[].currencyCode
string
Required
N
pattern ^[A-Z]{3}$; length 3
currencies[].currencyName
string
Required
N
min length 1; max length 50
currencies[].symbol
string
Required
N
min length 1; max length 5
currencies[].decimalPlaces
integer
Required
N
format int32; ≥ 0; ≤ 4
currencies[].minAmount
string
Optional
N
pattern ^[0-9]+(\.[0-9]+)?$; max length 18
currencies[].maxAmount
string
Required
N
pattern ^[0-9]+(\.[0-9]+)?$; max length 18
requiredMessageElements
object
Required
N
—
requiredMessageElements.pacs008
array
Required
N
each item: pattern ^/Document/.+
requiredMessageElements.getQuotes
array
Conditional — present only for multi-IPS destination countries
N
each item: one of destinationPsp
supportedInstructionPriorities
array
Required
N
unique items; each item: one of NORM, HIGH
sla
object
Required
N
—
sla.normalPaymentMaxExecutionTimeout
integer
Required
N
format int32; ≥ 0
sla.highPaymentMaxExecutionTimeout
integer
Conditional — present only when the country supports HIGH priority; omitted otherwise
N
format int32; ≥ 0
Cross-field rules
countryCodeequals thecountryCodepath parameter.currencies[].minAmount/currencies[].maxAmount: fractional digits exactly equalcurrencies[].decimalPlaces; JSON numbers, exponent notation and grouping separators are prohibited.currencieslists only active currencies.sla.highPaymentMaxExecutionTimeoutis present only when the country supportsHIGHpriority (omitted otherwise); it therefore never appears unlesssupportedInstructionPrioritiescontainsHIGH.requiredMessageElements.getQuotesis present only for multi-IPS destination countries and then containsdestinationPsp.supportedInstructionPrioritiesis the union across the country's IPSes;slavalues are the most relaxed (longest) MET across the country's IPSes, in whole seconds.
Response signature — every 200 and 304 response carries Signature-Input and Signature (plus Content-Digest on 200) per the Nexus HTTP Message Signature Profile v1, signed by the responding server. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.
Error responses (4xx/5xx with a body) — the body MUST conform to ErrorApiResponse: statusCode = RJCT; reasonCode matches ^[A-Z]{2}[0-9]{3}$; name is UPPER_SNAKE_CASE (≤ 50); description ≤ 500 characters and MUST NOT contain PII. reasonCode values for this operation: TE001, BE001, BE002, TE099, AE001, AE002, AE003, AE005, AE006, AE004. Gateway errors (405, 429, 502, 503, 504) carry no body.
- : Read country and currency reference data
Mutual TLS: the IPSO presents its X.509 client certificate on every connection, validated during the TLS handshake (fail-closed). The same certificate is the RFC 8705 binding anchor for the OAuth access token (see nexusOAuth).
OAuth2 client-credentials access token issued per participant, presented as Authorization: Bearer <token>. Tokens are certificate-bound per RFC 8705: the token carries a cnf."x5t#S256" confirmation claim recording the SHA-256 thumbprint of the IPSO's mTLS client certificate, and the request is rejected (AE006) when the certificate presented on the connection does not match that thumbprint.
ISO 3166-1 alpha-2 uppercase destination code
IDPattern: ^[A-Z]{2}$/
*/*Example: */*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.
"a1b2c3"RFC 9421 signature metadata for a request without a body, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). One dictionary member labelled nexus whose covered components are exactly "@method" "@authority" "@path" "@query", followed by "if-none-match" when that header is sent. @query is always covered; an empty query serialises as ?, so query parameters cannot be added or removed undetected. Signature parameters, emitted in this order: created and expires (Unix seconds; expires = created + 300; the receiver rejects created more than ±5 minutes from its clock or a signature past expires), keyid (base64url SHA-256 thumbprint of the signer's signing public key, registered at onboarding; a missing, unknown, expired or revoked key id is rejected - never resolved to a default key), alg (always rsa-pss-sha512) and tag (always nexus-v1). The signature parameters are signed through the @signature-params line of the signature base. A missing, malformed or non-conforming value is rejected with AE005.
nexus=("@method" "@authority" "@path" "@query");created=1786339201;expires=1786339501;keyid="NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs";alg="rsa-pss-sha512";tag="nexus-v1"Pattern: ^nexus=\("@method" "@authority" "@path" "@query"( "if-none-match")?\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid="[A-Za-z0-9_-]{43}";alg="rsa-pss-sha512";tag="nexus-v1"$RFC 9421 signature value: one dictionary member labelled nexus holding an RFC 8941 byte sequence - the standard base64 (not base64url) RSASSA-PSS signature using SHA-512 (rsa-pss-sha512), computed over the RFC 9421 signature base built from the components and parameters declared in Signature-Input. Produced with the sender's own signing private key; the receiver verifies it against the sender's registered signing public key resolved from keyid. With the minimum RSA-3072 key the signature is 384 bytes, i.e. 512 base64 characters. A missing, malformed or non-verifying signature is rejected with AE005.
nexus=:LawWG0POl/CUi7FibnReb4xwyjSBDCyBydn6cSvUUvNCGTOhMK4ZvXp3EaIZFIgBx0rY5gxaLJ6BsbMjaZatNSDJMjT0MjZnkZbSi7KX1tDgYX7nQ8bwwV5fo4n22oVkZkmkSAI5HyhWAjUs8o6gI/RcwoCHh7Y+XzOq/3YohNzYSg71/Z/A020bbRQsKIKvim1pFKIxnTjz7f7V2sRXjpBPu6zjzd0j4BLte5QkVfqBsd36NJtTpNPaMM5cYib0oMqBxlbjkhGIs+PA3nWurx3bdxsPeJLeTQHTBfUamOMTTtgPTn3wEuSv4OGAMa7rs62o6bpOQM9eKsvC4n4j92ek+AQnhb/zuryE9i7GqMTmD3gNnzgFDZM/uzEFPyVK3hC7/NpMzdetg8kP/xRQkppXyJV6JvnW06a1uVTvfj+foMKyaiBj7KZUUAD1ibiU3ualzSxyJZCT70l5mEZofiAWZqxYy+OTjCBmxqd2djmT2CNo115iC3GOPf4iJNDH:Pattern: ^nexus=:[A-Za-z0-9+/]+={0,2}:$Country information.
Not Modified. The resource has not changed since the last request.
Invalid Request
Authentication Failure
Authorization Failure
Resource Not Found
Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.
Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.
Internal Server Error
Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.
Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.
Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.
GET /v1/countries/{countryCode} HTTP/1.1
Host: prod.payments.nexus.net
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*
Signature-Input: text
Signature: text
{
"countryId": 360,
"countryCode": "ID",
"name": "Indonesia",
"currencies": [
{
"currencyCode": "IDR",
"currencyName": "Rupiah",
"symbol": "Rp",
"decimalPlaces": 0,
"minAmount": "1000",
"maxAmount": "15000000"
}
],
"requiredMessageElements": {
"pacs008": [
"/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/PmtTpInf/CtgyPurp/Cd"
]
},
"supportedInstructionPriorities": [
"NORM"
],
"sla": {
"normalPaymentMaxExecutionTimeout": 60
}
}Last updated
