# Payout Intel API

## Authentication

**Bearer**

For accessing the API a valid token must be passed in all the queries in the 'Authorization' header. A valid token is obtained from `POST /api/v1/authorize` with the `client_id` and `client_secret` of an API key generated in Admin section of your account. The token is valid for the number of seconds returned in `valid_for` (6000); after that, request a new one.

The following syntax must be used in the 'Authorization' header :

    Bearer <<token>>

So Authorization header can be like:

    Authorization: Bearer SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU


## Errors

Errors are returned as JSON. Send `Accept: application/json` with every request.

401 - invalid `client_id` / `client_secret` in `POST /api/v1/authorize`
```
{
    "errors": "Bad credentials. Check your credentials or contact support."
}
```

401 - missing or invalid token
```
{
    "errors": "Unauthorized access. Check your token."
}
```

401 - expired token
```
{
    "errors": "Unauthorized access. Token is expired."
}
```

429 - after 5 failed `POST /api/v1/authorize` attempts for the same `client_id` within 5 minutes; retry after the number of seconds in the `Retry-After` header
```
{
    "errors": "Too many failed authentication attempts for this client. Try again in a few minutes."
}
```


## Authorize (receive 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: Bearer <token>` header of all other requests. The token is valid for `valid_for` seconds.

After 5 failed attempts for the same `client_id` within 5 minutes, the endpoint responds with `429` and a `Retry-After: 300` 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

### 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"
     }'
```


## Show AML limit in given country, in specified currency

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

This request returns limit in given currency in specified country.

If no limit is known for the given `check_type` in the country, a `message` is returned instead of the limit. Returns `400` if invalid `currency` or `country` is given.

| Name | Type | Description|
| ------ | ------ | ------ |
| `currency` | string | ISO 3 currency code (default `EUR`) |
| `country` | string | ISO 2 country code (default `SK`) |
| `check_type` | string | Check type can be <"AML4", "AML5"> (default `AML4`) |

### Parameters

- `currency` (query) — ISO 3 currency code
- `country` (query) — ISO 2 country code
- `check_type` (query) — Check type

### Response 200

- `limit` — number · Limit converted to the requested currency · e.g. 4284.784
- `country` — string · ISO 2 country code · e.g. SK
- `currency` — string · ISO 3 currency code · e.g. PLN
- `check_type` — string · Check type · e.g. AML5
- `message` — string · Returned instead of the other fields when no limit is known · e.g. No known AML5 limit in AD

### Example

```bash
curl -X GET 'https://sandbox.payout.one/api/v1/intel/limits' \
  -H "Authorization: Bearer $TOKEN"
```


## Search Customer Intel

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

# ID Validation states
* **valid** - ID is valid for existing person
* **not_valid** - ID is not valid
* **unknown** - it was not possible to validate ID

# AML Check states
* **found** - exact one result
* **found_many** - more results 
* **not_found** - zero results

### Request body

- `name` — string (required) · First name · e.g. Juraj
- `surname` — string (required) · Last name/surname · e.g. Novak
- `birthdate` — string · Date in format YYYY-MM-DD · e.g. 1980-05-14
- `id` — string · ID number · e.g. AB1234

### Response 200

- `id` — string<uuid> · ID of search result · e.g. 5a395a80-5e9a-4691-9674-28d0c91755b9
- `url` — string · URL with result details in our system · e.g. https://sandbox.payout.one/intelboard/requests/5a395a80-5e9a-4691-9674-28d0c91755b9
- `valid_id` — string · Result state of ID validation · one of valid, not_valid, unknown · e.g. valid
- `aml` — string · Result state of AML check · one of found, found_many, not_found · e.g. not_found

### 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"
     }'
```