Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Countries

Country reference data and payment constraints, including supported instruction priorities, SLA execution timeouts, currency amount ranges (min/max), and purpose-code requirements.

Retrieve All Countries in Nexus

get

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.

Field
Type
Presence
Nullable
Constraints

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 equal currencies[].decimalPlaces; JSON numbers, exponent notation and grouping separators are prohibited.

  • currencies lists only active currencies.

  • sla.highPaymentMaxExecutionTimeout is present only when the country supports HIGH priority (omitted otherwise); it therefore never appears unless supportedInstructionPriorities contains HIGH.

  • requiredMessageElements.getQuotes is present only for multi-IPS destination countries and then contains destinationPsp.

  • supportedInstructionPriorities is the union across the country's IPSes; sla values 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.

Required scopes
This endpoint requires the following scopes:
  • : Read country and currency reference data
Authorizations
mutualTLS

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).

OAuth2clientCredentialsRequired

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.

Token URL:
Header parameters
AcceptstringRequired

/

Default: */*Example: */*
If-None-MatchstringOptional

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.

Example: "a1b2c3"
Signature-Inputstring · max: 512Required

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.

Example: 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"$
Signaturestring · min: 520 · max: 1400Required

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.

Example: nexus=:LawWG0POl/CUi7FibnReb4xwyjSBDCyBydn6cSvUUvNCGTOhMK4ZvXp3EaIZFIgBx0rY5gxaLJ6BsbMjaZatNSDJMjT0MjZnkZbSi7KX1tDgYX7nQ8bwwV5fo4n22oVkZkmkSAI5HyhWAjUs8o6gI/RcwoCHh7Y+XzOq/3YohNzYSg71/Z/A020bbRQsKIKvim1pFKIxnTjz7f7V2sRXjpBPu6zjzd0j4BLte5QkVfqBsd36NJtTpNPaMM5cYib0oMqBxlbjkhGIs+PA3nWurx3bdxsPeJLeTQHTBfUamOMTTtgPTn3wEuSv4OGAMa7rs62o6bpOQM9eKsvC4n4j92ek+AQnhb/zuryE9i7GqMTmD3gNnzgFDZM/uzEFPyVK3hC7/NpMzdetg8kP/xRQkppXyJV6JvnW06a1uVTvfj+foMKyaiBj7KZUUAD1ibiU3ualzSxyJZCT70l5mEZofiAWZqxYy+OTjCBmxqd2djmT2CNo115iC3GOPf4iJNDH:Pattern: ^nexus=:[A-Za-z0-9+/]+={0,2}:$
Responses
200

A list of countries with payment details.

application/json
get/v1/countries
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
      }
    }
  ]
}

Retrieve a Single Country

get

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.

Field
Type
Presence
Nullable
Constraints

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

  • countryCode equals the countryCode path parameter.

  • currencies[].minAmount / currencies[].maxAmount: fractional digits exactly equal currencies[].decimalPlaces; JSON numbers, exponent notation and grouping separators are prohibited.

  • currencies lists only active currencies.

  • sla.highPaymentMaxExecutionTimeout is present only when the country supports HIGH priority (omitted otherwise); it therefore never appears unless supportedInstructionPriorities contains HIGH.

  • requiredMessageElements.getQuotes is present only for multi-IPS destination countries and then contains destinationPsp.

  • supportedInstructionPriorities is the union across the country's IPSes; sla values 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.

Required scopes
This endpoint requires the following scopes:
  • : Read country and currency reference data
Authorizations
mutualTLS

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).

OAuth2clientCredentialsRequired

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.

Token URL:
Path parameters
countryCodestring · min: 2 · max: 2Required

ISO 3166-1 alpha-2 uppercase destination code

Example: IDPattern: ^[A-Z]{2}$
Header parameters
AcceptstringRequired

/

Default: */*Example: */*
If-None-MatchstringOptional

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.

Example: "a1b2c3"
Signature-Inputstring · max: 512Required

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.

Example: 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"$
Signaturestring · min: 520 · max: 1400Required

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.

Example: nexus=:LawWG0POl/CUi7FibnReb4xwyjSBDCyBydn6cSvUUvNCGTOhMK4ZvXp3EaIZFIgBx0rY5gxaLJ6BsbMjaZatNSDJMjT0MjZnkZbSi7KX1tDgYX7nQ8bwwV5fo4n22oVkZkmkSAI5HyhWAjUs8o6gI/RcwoCHh7Y+XzOq/3YohNzYSg71/Z/A020bbRQsKIKvim1pFKIxnTjz7f7V2sRXjpBPu6zjzd0j4BLte5QkVfqBsd36NJtTpNPaMM5cYib0oMqBxlbjkhGIs+PA3nWurx3bdxsPeJLeTQHTBfUamOMTTtgPTn3wEuSv4OGAMa7rs62o6bpOQM9eKsvC4n4j92ek+AQnhb/zuryE9i7GqMTmD3gNnzgFDZM/uzEFPyVK3hC7/NpMzdetg8kP/xRQkppXyJV6JvnW06a1uVTvfj+foMKyaiBj7KZUUAD1ibiU3ualzSxyJZCT70l5mEZofiAWZqxYy+OTjCBmxqd2djmT2CNo115iC3GOPf4iJNDH:Pattern: ^nexus=:[A-Za-z0-9+/]+={0,2}:$
Responses
200

Country information.

application/json
get/v1/countries/{countryCode}
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