Address Types

Address types and input field definitions for recipient account or proxy details, by country or address type.

Gets all the address types AND inputs for a specified Country

get

Returns all address types AND their associated inputs for a specified country.

Required scopes

This endpoint requires the following scopes:

• : Read address types and input definitions

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 country code used to scope the lookup. Must match the Sender’s selected destination country.

Example: PHPattern: ^[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

Address types and inputs for the specified country.

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}/address-types-and-inputs

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

[
  {
    "addressTypeId": "PHACCT",
    "countries": [
      "PH"
    ],
    "addressTypeCode": "ACCT",
    "clearingSystemId": "PHPINST",
    "displayOrder": 3,
    "inputs": [
      {
        "addressInputId": "PHINPT1",
        "label": {
          "addressTypeCode": "ACCT",
          "title": {
            "en": "Account number, 10-18 digits"
          }
        },
        "attributes": {
          "name": "accountOrProxyId",
          "type": "number",
          "pattern": "^\\d{10,18}$",
          "placeholder": "1234567890",
          "required": true
        },
        "iso20022XPath": {
          "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Acct/Id/Othr/Id",
          "pacs008": "/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/CdtrAcct/Id/Othr/Id"
        }
      },
      {
        "addressInputId": "PHINPT2",
        "label": {
          "addressTypeCode": "BICFI",
          "title": {
            "en": "BIC of the Recipient's Bank or Payment Service Provider"
          }
        },
        "attributes": {
          "name": "finInstId",
          "type": "text",
          "pattern": "^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?",
          "placeholder": "AAAAPHAAXXX",
          "required": true
        },
        "iso20022XPath": {
          "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Agt/FinInstnId/BICFI",
          "pacs008": "/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/CdtrAgt/FinInstnId/BICFI"
        }
      }
    ]
  },
  {
    "addressTypeId": "PHEMAL",
    "countries": [
      "PH"
    ],
    "addressTypeCode": "EMAL",
    "proxyDirectoryId": "PHPROXY",
    "displayOrder": 2,
    "inputs": [
      {
        "addressInputId": "PHINPT3",
        "label": {
          "addressTypeCode": "EMAL",
          "title": {
            "en": "Email address"
          }
        },
        "attributes": {
          "name": "accountOrProxyId",
          "type": "email",
          "pattern": null,
          "placeholder": "[email protected]",
          "required": true
        },
        "iso20022XPath": {
          "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Acct/Prxy/Id",
          "pacs008": null
        }
      },
      {
        "addressInputId": "PHINPT2",
        "label": {
          "addressTypeCode": "BICFI",
          "title": {
            "en": "BIC of the Recipient's Bank or Payment Service Provider"
          }
        },
        "attributes": {
          "name": "finInstId",
          "type": "text",
          "pattern": "^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?",
          "placeholder": "AAAAPHAAXXX",
          "required": true
        },
        "iso20022XPath": {
          "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Agt/FinInstnId/BICFI",
          "pacs008": "/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/CdtrAgt/FinInstnId/BICFI"
        }
      }
    ]
  },
  {
    "addressTypeId": "PHMBNO",
    "countries": [
      "PH"
    ],
    "addressTypeCode": "MBNO",
    "proxyDirectoryId": "PHPROXY",
    "displayOrder": 1,
    "inputs": [
      {
        "addressInputId": "PHINPT4",
        "label": {
          "addressTypeCode": "MBNO",
          "title": {
            "en": "Mobile phone number, including the country code"
          }
        },
        "attributes": {
          "name": "accountOrProxyId",
          "type": "tel",
          "pattern": "^\\+(?:[0-9] ?){6,14}[0-9]$",
          "placeholder": "[phone]",
          "required": true
        },
        "iso20022XPath": {
          "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Acct/Prxy/Id",
          "pacs008": null
        }
      },
      {
        "addressInputId": "PHINPT5",
        "label": {
          "addressTypeCode": "BICFI",
          "title": {
            "en": "BIC of the Recipient's Bank or Payment Service Provider"
          }
        },
        "attributes": {
          "name": "finInstId",
          "type": "text",
          "pattern": "^[A-Z]{6}[0-9A-Z]{2}([0-9A-Z]{3})?",
          "placeholder": "AAAAPHAAXXX",
          "required": true
        },
        "iso20022XPath": {
          "acmt023": "/Document/IdVrfctnReq/Vrfctn/PtyAndAcctId/Agt/FinInstnId/BICFI",
          "pacs008": "/Document/FIToFICstmrCdtTrf/CdtTrfTxInf/CdtrAgt/FinInstnId/BICFI"
        }
      }
    ]
  }
]