API reference

Payout Intel API

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

Environments

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

Authentication

View as Markdown Spec

Send a Bearer token in the Authorization header of every request except Get API token:

HTTP

Authorization: Bearer SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU

Get the token from Get 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

View as Markdown Spec

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
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 returns its 400 errors under an error key instead.

POST

Get API token

View as Markdown Spec

/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

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

const res = await fetch("https://sandbox.payout.one/api/v1/authorize", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "client_id": "8b0f3c52-6d1e-4a7b-9c2d-5e4f3a2b1c0d",
    "client_secret": "example-client-secret-not-real"
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://sandbox.payout.one/api/v1/authorize",
    json={
        "client_id": "8b0f3c52-6d1e-4a7b-9c2d-5e4f3a2b1c0d",
        "client_secret": "example-client-secret-not-real",
    },
)
data = res.json()

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://sandbox.payout.one/api/v1/authorize");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "client_id" => "8b0f3c52-6d1e-4a7b-9c2d-5e4f3a2b1c0d",
  "client_secret" => "example-client-secret-not-real"
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response 200

{
  "token": "SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU",
  "valid_for": 6000
}

Request body

client_id requiredstring

API key (client ID)

Example 8b0f3c52-6d1e-4a7b-9c2d-5e4f3a2b1c0d

client_secret requiredstring

API key secret

Example example-client-secret-not-real

Response 200

tokenstring

Bearer token for the Authorization header

Example SFMyNTY.EXAMPLE-TOKEN.dGhpcy1pcy1hLWZha2Utc2lnbmF0dXJlLWV4YW1wbGU

valid_forinteger

Token validity in seconds

Example 6000

Other responses

401

Wrong client_id or client_secret, or one of them is missing.

Example

{
  "errors": "Bad credentials. Check your credentials or contact support."
}

429

5 failed attempts for this client_id within 5 minutes. Retry after Retry-After seconds.

Example

{
  "errors": "Too many failed authentication attempts for this client. Try again in a few minutes."
}

GET

Get AML limit

View as Markdown Spec

/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.

Request

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

const res = await fetch("https://sandbox.payout.one/api/v1/intel/limits?currency=PLN&country=SK&check_type=AML5", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.PAYOUT_TOKEN}`,
  },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://sandbox.payout.one/api/v1/intel/limits?currency=PLN&country=SK&check_type=AML5",
    headers={"Authorization": f"Bearer {os.environ['PAYOUT_TOKEN']}"},
)
data = res.json()

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://sandbox.payout.one/api/v1/intel/limits?currency=PLN&country=SK&check_type=AML5");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer " . getenv("PAYOUT_TOKEN")]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response 200

{
  "check_type": "AML5",
  "country": "SK",
  "currency": "PLN",
  "limit": 4284.784
}

Parameters

currencyquery · string

ISO 4217 currency code, case-insensitive. Must be a currency with an exchange rate for today.

Default EUR · Example PLN

countryquery · string

ISO 3166-1 alpha-2 country code, case-insensitive

Default SK

check_typequery · string

Limit type, case-insensitive

One of AML4, AML5 · Default AML4 · Example AML5

Response 200

limitnumber

The limit in currency. Limits are set in EUR and converted at today's exchange rate.

Example 4284.784

countrystring

ISO 3166-1 alpha-2 country code

Example SK

currencystring

ISO 4217 currency code

Example PLN

check_typestring

Limit type

Example AML5

messagestring

Returned instead of all other fields when no limit is set

Example No known AML5 limit in AD

Other responses

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.

Example

{
  "error": "Invalid currency code"
}

401

Missing, invalid or expired bearer token.

Example

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

POST

Search customer intel

View as Markdown Spec

/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

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

const res = await fetch("https://sandbox.payout.one/api/v1/intel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYOUT_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Juraj",
    "surname": "Novak",
    "birthdate": "1980-05-14",
    "id": "AB1234"
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://sandbox.payout.one/api/v1/intel",
    headers={"Authorization": f"Bearer {os.environ['PAYOUT_TOKEN']}"},
    json={
        "name": "Juraj",
        "surname": "Novak",
        "birthdate": "1980-05-14",
        "id": "AB1234",
    },
)
data = res.json()

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://sandbox.payout.one/api/v1/intel");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "name" => "Juraj",
  "surname" => "Novak",
  "birthdate" => "1980-05-14",
  "id" => "AB1234"
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer " . getenv("PAYOUT_TOKEN"), "Content-Type: application/json"]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Response 200

{
  "id": "5a395a80-5e9a-4691-9674-28d0c91755b9",
  "url": "https://sandbox.payout.one/intelboard/requests/5a395a80-5e9a-4691-9674-28d0c91755b9",
  "valid_id": "valid",
  "aml": "not_found"
}

Request body

name requiredstring

First name

Max length 255 · Example Juraj

surname requiredstring

Last name

Max length 255 · Example Novak

birthdatestring<date>

Date of birth, YYYY-MM-DD

Example 1980-05-14

idstring

Number of the person's identity document, checked for valid_id. It is not stored with the search and is not the response id.

Example AB1234

Response 200

idstring<uuid>

ID of the stored search (not the identity document number). url ends with it.

Example 5a395a80-5e9a-4691-9674-28d0c91755b9

urlstring

Page with the search details in Payout

Example https://sandbox.payout.one/intelboard/requests/5a395a80-5e9a-4691-9674-28d0c91755b9

valid_idstring

Result of the check of the request id. No identity document registry is connected yet, so real document numbers return unknown.

validThe document number is valid; currently only for the test value AB1234
not_validThe document number is not valid; currently only for the test value XY1234
unknownThe document number could not be checked; currently every other value, or no id

amlstring

Result of the AML check

foundExactly one person found
found_manyMore than one person found
not_foundNo person found

Other responses

401

Missing, invalid or expired bearer token.

Example

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

408

The AML lookup timed out.

Example

{
  "errors": "Timeout"
}

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

{
  "errors": "Couldn't save intel request"
}

Was this page helpful?

Need help? Contact support.
Questions? Contact sales.
Service status? status.payout.one.
LLM? Read llms.txt.