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.

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"

Responses

200

A list of countries with payment details.

application/json

304

Not Modified. The resource has not changed since the last request.

401

Authentication Failure

application/json

403

Authorization Failure

application/json

405

Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.

429

Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.

500

Internal Server Error

application/json

502

Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.

503

Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.

504

Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.

get/v1/countries

GET /v1/countries HTTP/1.1
Host: prod.payments.nexus.net
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "countries": [
    {
      "countryId": 344,
      "countryCode": "HK",
      "name": "Hong Kong",
      "currencies": [
        {
          "currencyCode": "HKD",
          "currencyName": "Hong Kong Dollar",
          "symbol": "HK$",
          "decimalPlaces": 2,
          "minAmount": "100",
          "maxAmount": "10000"
        },
        {
          "currencyCode": "CNY",
          "currencyName": "Yuan Renminbi",
          "symbol": "¥",
          "decimalPlaces": 2,
          "minAmount": "100",
          "maxAmount": "20000"
        }
      ],
      "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",
          "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",
          "maxAmount": "200000"
        }
      ],
      "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"
        }
      ],
      "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",
          "maxAmount": "2000000"
        }
      ],
      "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.

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"

Responses

200

Country information.

application/json

304

Not Modified. The resource has not changed since the last request.

400

Invalid Request

application/json

401

Authentication Failure

application/json

403

Authorization Failure

application/json

404

Resource Not Found

application/json

405

Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.

429

Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.

500

Internal Server Error

application/json

502

Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate.

503

Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff.

504

Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff.

get/v1/countries/{countryCode}

GET /v1/countries/{countryCode} HTTP/1.1
Host: prod.payments.nexus.net
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "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
  }
}