Lookup data

The Lookup API provides read-only access to reference data you'll need when building payment forms and integrations. Use these endpoints to populate dropdowns, validate inputs, and display the correct options to your users.

Before you start

You will need a valid API key to authenticate your requests.

Countries

Retrieve the list of supported countries with their available currencies. This is useful for populating country selectors and determining which currencies are available for a given country:

try {
  const response = await fetch('https://api.nexpay.com/v2/lookup/countries', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

{
  "countries": [
    {
      "countryCode": "AU",
      "name": "Australia",
      "currencies": ["AUD"]
    },
    {
      "countryCode": "US",
      "name": "United States",
      "currencies": ["USD"]
    },
    {
      "countryCode": "GB",
      "name": "United Kingdom",
      "currencies": ["GBP"]
    }
  ]
}

Payment methods

Get the available payment methods for a specific payee. The methods returned depend on the payee's country and currency configuration:

try {
  const response = await fetch('https://api.nexpay.com/v2/lookup/payment-methods/42', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

{
  "paymentMethods": [
    {
      "settlementMethod": "dmt",
      "displayName": "Direct Money Transfer"
    },
    {
      "settlementMethod": "bank-transfer",
      "displayName": "Bank Transfer"
    }
  ]
}

The settlementMethod values here correspond to the settlement methods returned in quote variants.

Transaction purposes

Retrieve the available payment purposes for a given payment type. Use this to populate the purpose field when creating a payment:

try {
  const response = await fetch('https://api.nexpay.com/v2/lookup/purposes/provider', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

{
  "purposes": [
    { "id": 1, "name": "Tuition Fee" },
    { "id": 2, "name": "Accommodation" },
    { "id": 3, "name": "Living Expenses" }
  ]
}

The :type path parameter corresponds to the transactionType — use provider, company, or private.

Payer types

Retrieve the available payer types for a given payment type. Use this to populate the payerType field in payer details when creating a payment:

try {
  const response = await fetch('https://api.nexpay.com/v2/lookup/payer-types/provider', {
    method: 'GET',
    headers: {
      'Authorization': 'ApiKey your-api-key-here',
    },
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

{
  "payerTypes": [
    { "id": 1, "name": "Student" },
    { "id": 2, "name": "Parent" },
    { "id": 3, "name": "Agent" }
  ]
}

The :type path parameter corresponds to the transactionType — use provider, company, or private.

Things to know

• All lookup endpoints are read-only (GET only).
• Responses are cached server-side: countries and purposes for 60 minutes, payment methods for 5 minutes.
• Country codes follow ISO 3166-1 alpha-2 and currency codes follow ISO 4217.
• Payment methods vary per payee — always fetch them dynamically based on the selected payee.
• Purposes and payer types vary per transaction type — always pass the correct :type parameter.