# Payout Intel API

Run AML checks on people and look up AML limits by country.

## Environments

- Sandbox (for test purposes only): `https://sandbox.payout.one`
- Production: `https://app.payout.one`

## Authentication

Send a Bearer token in the `Authorization` header of every request except
[Get API token](#authorize_receive_api_token):

```http
Authorization: Bearer SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU
```

Get the token from [Get API token](#authorize_receive_api_token) with the `client_id` and
`client_secret` of an API key generated in the Admin section of your account. The token is valid
for `valid_for` seconds (6000); then request a new one.


## Errors

Errors are JSON objects with an `errors` message. Send `Accept: application/json` with every
request.

```json
{
  "errors": "Unauthorized access. Check your token."
}
```

| Status | Message | When |
| ------ | ------- | ---- |
| 401 | `Bad credentials. Check your credentials or contact support.` | Wrong or missing `client_id` or `client_secret` at [Get API token](#authorize_receive_api_token) |
| 401 | `Unauthorized access. Check your token.` | The token is missing or invalid |
| 401 | `Unauthorized access. Token is expired.` | The token has expired |
| 429 | `Too many failed authentication attempts for this client. Try again in a few minutes.` | 5 failed token requests for the same `client_id` within 5 minutes. Retry after the number of seconds in the `Retry-After` header |

[Get AML limit](#show_aml_limit_in_given_country_in_specified_currency) returns its `400` errors
under an `error` key instead.


## Get API token

`POST https://sandbox.payout.one/api/v1/authorize`

Exchanges the `client_id` and `client_secret` of your API key for a Bearer token. Send the
token in the `Authorization` header of all other requests. The token is valid for `valid_for`
seconds; then request a new one.

After 5 failed attempts for the same `client_id` within 5 minutes, the endpoint responds with
`429`. Retry after the number of seconds in the `Retry-After` header.

### Request body

- `client_id` — string (required) · API key (client ID) · e.g. `8b0f3c52-6d1e-4a7b-9c2d-5e4f3a2b1c0d`
- `client_secret` — string (required) · API key secret · e.g. `example-client-secret-not-real`

### Response 200

- `token` — string · Bearer token for the `Authorization` header · e.g. `SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU`
- `valid_for` — integer · Token validity in seconds · e.g. `6000`

### Responses

- `200` — Success
- `401` — Wrong `client_id` or `client_secret`, or one of them is missing.
- `429` — 5 failed attempts for this `client_id` within 5 minutes. Retry after `Retry-After` seconds.

### Example

```bash
curl -X POST 'https://sandbox.payout.one/api/v1/authorize' \
  -H "Content-Type: application/json" \
  -d '{
       "client_id": "8b0f3c52-6d1e-4a7b-9c2d-5e4f3a2b1c0d",
       "client_secret": "example-client-secret-not-real"
     }'
```


## Get AML limit

`GET https://sandbox.payout.one/api/v1/intel/limits`

Returns the AML limit of a country, converted to the requested currency.

If no limit of that `check_type` is set for the country, the response has only a `message`.

### Parameters

- `currency` (query) — ISO 4217 currency code, case-insensitive. Must be a currency with an exchange rate for today (default `EUR`)
- `country` (query) — ISO 3166-1 alpha-2 country code, case-insensitive (default `SK`)
- `check_type` (query) — Limit type, case-insensitive (default `AML4`)
  - `AML4`
  - `AML5`

### Response 200

- `limit` — number · The limit in `currency`. Limits are set in EUR and converted at today's exchange rate. · e.g. `4284.784`
- `country` — string · ISO 3166-1 alpha-2 country code · e.g. `SK`
- `currency` — string · ISO 4217 currency code · e.g. `PLN`
- `check_type` — string · Limit type · e.g. `AML5`
- `message` — string · Returned instead of all other fields when no limit is set · e.g. `No known AML5 limit in AD`

### Responses

- `200` — Success
- `400` — `currency` has no exchange rate for today, or `country` is not an ISO 3166-1 alpha-2 code. The body has an `error` key, not `errors`.
- `401` — Missing, invalid or expired bearer token.

### Example

```bash
curl -X GET 'https://sandbox.payout.one/api/v1/intel/limits?currency=PLN&country=SK&check_type=AML5' \
  -H "Authorization: Bearer $TOKEN"
```


## Search customer intel

`POST https://sandbox.payout.one/api/v1/intel`

Runs an AML check on a person and checks their identity document number (see `valid_id`).
Payout stores the search; open `url` to see the people it found.

### Repeated searches

If the same `name`, `surname` and `birthdate` were searched before, the people found by the
latest such search are returned again, without a new lookup.

### PEP alerts

When a new lookup finds a politically exposed person (PEP), every user of your account gets
an e-mail alert.

### Request body

- `name` — string (required) · First name · e.g. `Juraj`
- `surname` — string (required) · Last name · e.g. `Novak`
- `birthdate` — string<date> · Date of birth, `YYYY-MM-DD` · e.g. `1980-05-14`
- `id` — string · Number of the person's identity document, checked for `valid_id`. It is not stored with the search and is not the response `id`. · e.g. `AB1234`

### Response 200

- `id` — string<uuid> · ID of the stored search (not the identity document number). `url` ends with it. · e.g. `5a395a80-5e9a-4691-9674-28d0c91755b9`
- `url` — string · Page with the search details in Payout · e.g. `https://sandbox.payout.one/intelboard/requests/5a395a80-5e9a-4691-9674-28d0c91755b9`
- `valid_id` — string · Result of the check of the request `id`. No identity document registry is connected yet, so real document numbers return `unknown`. · e.g. `valid`
  - `valid` — The document number is valid; currently only for the test value `AB1234`
  - `not_valid` — The document number is not valid; currently only for the test value `XY1234`
  - `unknown` — The document number could not be checked; currently every other value, or no `id`
- `aml` — string · Result of the AML check · e.g. `not_found`
  - `found` — Exactly one person found
  - `found_many` — More than one person found
  - `not_found` — No person found

### Responses

- `200` — Success
- `401` — Missing, invalid or expired bearer token.
- `408` — The AML lookup timed out.
- `422` — The search could not be completed, for example because `birthdate` is not a valid `YYYY-MM-DD` date (the message then starts with `Bad Date format.`).

### Example

```bash
curl -X POST 'https://sandbox.payout.one/api/v1/intel' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "Juraj",
       "surname": "Novak",
       "birthdate": "1980-05-14",
       "id": "AB1234"
     }'
```