Beneficiaries

Create a beneficiary

Saves a person (INDIVIDUAL) or company (BUSINESS) you pay, with its payment accounts. It starts as PENDING until KryptaPay approves it.

An INDIVIDUAL can only hold EUR / USD bank accounts. A BUSINESS must send its trade register extract (rccm) and its manager’s ID (id_director) in documents. When the beneficiary has an EUR or USD bank account, email is required and we email them an identity verification link. See Beneficiaries.

The request body can be up to 50 MB.

API key scope: payouts:write

POST

counterparties

Create a beneficiary

curl --request POST \
  --url https://staging.api.krypta-pay.com/v1/counterparties \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityType": "INDIVIDUAL",
  "fullName": "Jean Dupont",
  "country": "FR",
  "email": "jean.dupont@example.com",
  "accounts": [
    {
      "kind": "BANK",
      "currency": "EUR",
      "bankName": "BNP Paribas",
      "accountHolder": "Jean Dupont",
      "iban": "FR7630006000011234567890189",
      "swiftBic": "BNPAFRPP"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entityType: 'INDIVIDUAL',
    fullName: 'Jean Dupont',
    country: 'FR',
    email: 'jean.dupont@example.com',
    accounts: [
      {
        kind: 'BANK',
        currency: 'EUR',
        bankName: 'BNP Paribas',
        accountHolder: 'Jean Dupont',
        iban: 'FR7630006000011234567890189',
        swiftBic: 'BNPAFRPP'
      }
    ]
  })
};

fetch('https://staging.api.krypta-pay.com/v1/counterparties', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://staging.api.krypta-pay.com/v1/counterparties"

payload = {
    "entityType": "INDIVIDUAL",
    "fullName": "Jean Dupont",
    "country": "FR",
    "email": "jean.dupont@example.com",
    "accounts": [
        {
            "kind": "BANK",
            "currency": "EUR",
            "bankName": "BNP Paribas",
            "accountHolder": "Jean Dupont",
            "iban": "FR7630006000011234567890189",
            "swiftBic": "BNPAFRPP"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging.api.krypta-pay.com/v1/counterparties",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entityType' => 'INDIVIDUAL',
    'fullName' => 'Jean Dupont',
    'country' => 'FR',
    'email' => 'jean.dupont@example.com',
    'accounts' => [
        [
                'kind' => 'BANK',
                'currency' => 'EUR',
                'bankName' => 'BNP Paribas',
                'accountHolder' => 'Jean Dupont',
                'iban' => 'FR7630006000011234567890189',
                'swiftBic' => 'BNPAFRPP'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "ok": true,
  "data": {
    "id": "cmh1a2b3c0001xyz",
    "entityType": "INDIVIDUAL",
    "fullName": "Jean Dupont",
    "type": "FOURNISSEUR",
    "country": "FR",
    "email": "jean.dupont@example.com",
    "approvalStatus": "PENDING",
    "rejectionReason": null,
    "isBlacklisted": false,
    "verificationRequiredAt": "2026-11-11T10:15:00.000Z",
    "verification": {
      "status": "NOT_STARTED",
      "tosAccepted": false,
      "nameMismatch": false,
      "lastSentAt": "2026-11-11T10:15:00.000Z",
      "rejectionReasons": []
    },
    "accounts": [
      {
        "id": "cmh1a2b3c0002xyz",
        "kind": "BANK",
        "currency": "EUR",
        "label": null,
        "bankName": "BNP Paribas",
        "accountHolder": "Jean Dupont",
        "iban": "FR7630006000011234567890189",
        "swiftBic": "BNPAFRPP"
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"
  }
}

{
  "ok": false,
  "error": {
    "code": "kyb_required",
    "message": "Your organization must complete KYB verification."
  }
}

{
  "ok": false,
  "error": {
    "code": "validation_error",
    "message": "amount: Invalid amount"
  }
}

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded, retry in 1 minute"
  }
}

Authorizations

Authorization

string

header

required

Secret API key from Dashboard → Developers: kp_sandbox_… for Sandbox, kp_live_… for Production. Server-side only.

Body

application/json

fullName

string

required

Required string length: 1 - 180

country

string

required

Required string length: 2

type

enum<string>

default:CLIENT

Available options:

CLIENT,

FOURNISSEUR,

PARTENAIRE,

EMPLOYE,

FILIALE,

PRESTATAIRE

entityType

enum<string>

default:BUSINESS

INDIVIDUAL or BUSINESS (default). Cannot be changed later.

Available options:

INDIVIDUAL,

BUSINESS

tradeName

string

Maximum string length: 180

legalForm

string

Maximum string length: 60

registrationNumber

string

Maximum string length: 80

taxId

string

Maximum string length: 80

address

string

Maximum string length: 300

contactName

string

Maximum string length: 180

contactRole

string

Maximum string length: 120

contactPhone

string

Maximum string length: 32

bankName

string

Maximum string length: 160

msisdn

string

Required string length: 8 - 20

string<email>

Required when the beneficiary has an EUR or USD bank account: the verification link is sent there. An email already used to verify the other entity type is refused (422 email_used_by_other_entity_type).

Maximum string length: 180

iban

string

Required string length: 15 - 34

swiftBic

string

Required string length: 8 - 11

bankAccount

string

Maximum string length: 40

walletAddress

string

Required string length: 20 - 80

walletChain

enum<string>

Available options:

MTN_BJ,

MTN_CI,

MTN_CM,

ORANGE_CI,

ORANGE_SN,

ORANGE_ML,

ORANGE_BF,

ORANGE_CM,

MOOV_BJ,

MOOV_TG,

MOOV_CI,

MOOV_BF,

WAVE_CI,

WAVE_SN,

FREE_SN,

TMONEY_TG,

MOBICASH_ML,

MOBICASH_BF,

DJAMO_CI,

MIXX_SN,

MTN_CG,

AIRTEL_CG,

ORANGE_CD,

AIRTEL_CD,

VODACOM_CD,

AFRICELL_CD,

AIRTEL_GA,

MOMO_NG,

AIRTEL_NG,

OPAY_NG,

MTN_GH,

VODAFONE_GH,

AIRTELTIGO_GH,

BANK_XOF,

BANK_XAF,

BANK_NGN,

BANK_GHS,

BANK_CDF,

BANK_EUR,

BANK_USD,

ETH,

POLYGON,

TRON

methodDetails

object

Show child attributes

documents

object[]

Company documents, each { kind, filename, mimeType, base64 }. Not accepted for an INDIVIDUAL.

Maximum array length: 8

Show child attributes

accounts

object[]

At most one account per kind and currency.

Maximum array length: 20

Show child attributes

Response

Success

enum<boolean>

required

Available options:

true

data

object

required

Show child attributes

Create a beneficiary

curl --request POST \
  --url https://staging.api.krypta-pay.com/v1/counterparties \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityType": "INDIVIDUAL",
  "fullName": "Jean Dupont",
  "country": "FR",
  "email": "jean.dupont@example.com",
  "accounts": [
    {
      "kind": "BANK",
      "currency": "EUR",
      "bankName": "BNP Paribas",
      "accountHolder": "Jean Dupont",
      "iban": "FR7630006000011234567890189",
      "swiftBic": "BNPAFRPP"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entityType: 'INDIVIDUAL',
    fullName: 'Jean Dupont',
    country: 'FR',
    email: 'jean.dupont@example.com',
    accounts: [
      {
        kind: 'BANK',
        currency: 'EUR',
        bankName: 'BNP Paribas',
        accountHolder: 'Jean Dupont',
        iban: 'FR7630006000011234567890189',
        swiftBic: 'BNPAFRPP'
      }
    ]
  })
};

fetch('https://staging.api.krypta-pay.com/v1/counterparties', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://staging.api.krypta-pay.com/v1/counterparties"

payload = {
    "entityType": "INDIVIDUAL",
    "fullName": "Jean Dupont",
    "country": "FR",
    "email": "jean.dupont@example.com",
    "accounts": [
        {
            "kind": "BANK",
            "currency": "EUR",
            "bankName": "BNP Paribas",
            "accountHolder": "Jean Dupont",
            "iban": "FR7630006000011234567890189",
            "swiftBic": "BNPAFRPP"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging.api.krypta-pay.com/v1/counterparties",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entityType' => 'INDIVIDUAL',
    'fullName' => 'Jean Dupont',
    'country' => 'FR',
    'email' => 'jean.dupont@example.com',
    'accounts' => [
        [
                'kind' => 'BANK',
                'currency' => 'EUR',
                'bankName' => 'BNP Paribas',
                'accountHolder' => 'Jean Dupont',
                'iban' => 'FR7630006000011234567890189',
                'swiftBic' => 'BNPAFRPP'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "ok": true,
  "data": {
    "id": "cmh1a2b3c0001xyz",
    "entityType": "INDIVIDUAL",
    "fullName": "Jean Dupont",
    "type": "FOURNISSEUR",
    "country": "FR",
    "email": "jean.dupont@example.com",
    "approvalStatus": "PENDING",
    "rejectionReason": null,
    "isBlacklisted": false,
    "verificationRequiredAt": "2026-11-11T10:15:00.000Z",
    "verification": {
      "status": "NOT_STARTED",
      "tosAccepted": false,
      "nameMismatch": false,
      "lastSentAt": "2026-11-11T10:15:00.000Z",
      "rejectionReasons": []
    },
    "accounts": [
      {
        "id": "cmh1a2b3c0002xyz",
        "kind": "BANK",
        "currency": "EUR",
        "label": null,
        "bankName": "BNP Paribas",
        "accountHolder": "Jean Dupont",
        "iban": "FR7630006000011234567890189",
        "swiftBic": "BNPAFRPP"
      }
    ]
  }
}

{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"
  }
}

{
  "ok": false,
  "error": {
    "code": "kyb_required",
    "message": "Your organization must complete KYB verification."
  }
}

{
  "ok": false,
  "error": {
    "code": "validation_error",
    "message": "amount: Invalid amount"
  }
}

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded, retry in 1 minute"
  }
}

Overview

Payins

Payouts

Beneficiaries

Fees

FX

Wallets

Transactions

Networks and status

Create a beneficiary

Authorizations

Body

Response