# Lookup data

> Retrieve reference data like countries, payment methods, purposes, and payer types.

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](/docs/api-keys.md) to authenticate your requests.

> **Note — JSON examples show the unwrapped `data` payload**
>
> Every success response on the wire is `{ "data": { ... } }`. The JSON examples in this guide show the inner `data` value — what you get after `const { data } = await response.json()`. Error responses are **not** wrapped — see [Errors](/docs/errors.md).

## 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:

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/lookup/countries' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'
```

**JavaScript**

```javascript
try {
  const response = await fetch('https://api.nexpay.com.au/v2/lookup/countries', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

  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);
}
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret',
])->get('https://api.nexpay.com.au/v2/lookup/countries');

$data = $response->json('data');

print_r($data);
```

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

> **Note — Caching**
>
> Country data is cached for 60 minutes. You can safely cache this data on your side as well — it changes infrequently.

---

## Payment methods

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

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/lookup/payment-methods/42' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'
```

**JavaScript**

```javascript
try {
  const response = await fetch('https://api.nexpay.com.au/v2/lookup/payment-methods/42', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

  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);
}
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret',
])->get('https://api.nexpay.com.au/v2/lookup/payment-methods/42');

$data = $response->json('data');

print_r($data);
```

```javascript
{
  "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](/docs/guides/getting-quotes.md#understanding-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 intent](/docs/guides/payment-intents-manual.md):

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/lookup/purposes/provider' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'
```

**JavaScript**

```javascript
try {
  const response = await fetch('https://api.nexpay.com.au/v2/lookup/purposes/provider', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

  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);
}
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret',
])->get('https://api.nexpay.com.au/v2/lookup/purposes/provider');

$data = $response->json('data');

print_r($data);
```

```javascript
{
  "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 intent](/docs/guides/payment-intents-manual.md):

**cURL**

```bash
curl 'https://api.nexpay.com.au/v2/lookup/payer-types/provider' \
  -H 'X-API-Key: nxp_ck_your-client-id:nxp_sk_your-secret'
```

**JavaScript**

```javascript
try {
  const response = await fetch('https://api.nexpay.com.au/v2/lookup/payer-types/provider', {
    method: 'GET',
    headers: {
      'X-API-Key': 'nxp_ck_your-client-id:nxp_sk_your-secret',
    },
  });

  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);
}
```

**PHP (Laravel)**

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-Key' => 'nxp_ck_your-client-id:nxp_sk_your-secret',
])->get('https://api.nexpay.com.au/v2/lookup/payer-types/provider');

$data = $response->json('data');

print_r($data);
```

```javascript
{
  "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](/docs/currencies-countries.md#countries) and currency codes follow [ISO 4217](/docs/currencies-countries.md#currencies).
* 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.