Start buyer KYC via the settlement partner

curl --request POST \
  --url https://api.example.com/v1/buyer-kyc \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "entityType": "individual",
  "buyerEmail": "buyer@acme.com",
  "firstName": "Ana",
  "lastName": "Silva",
  "buyerCountry": "BR",
  "dateOfBirth": "1990-04-12",
  "taxId": "12345678900",
  "addressLine1": "Rua das Flores 123",
  "city": "Florianópolis",
  "stateProvinceRegion": "SC",
  "postalCode": "88000-000",
  "idDocCountry": "BR",
  "idDocType": "PASSPORT",
  "selfieFile": "https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg",
  "idDocFrontFile": "https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg"
}
'

import requests

url = "https://api.example.com/v1/buyer-kyc"

payload = {
    "entityType": "individual",
    "buyerEmail": "buyer@acme.com",
    "firstName": "Ana",
    "lastName": "Silva",
    "buyerCountry": "BR",
    "dateOfBirth": "1990-04-12",
    "taxId": "12345678900",
    "addressLine1": "Rua das Flores 123",
    "city": "Florianópolis",
    "stateProvinceRegion": "SC",
    "postalCode": "88000-000",
    "idDocCountry": "BR",
    "idDocType": "PASSPORT",
    "selfieFile": "https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg",
    "idDocFrontFile": "https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entityType: 'individual',
    buyerEmail: 'buyer@acme.com',
    firstName: 'Ana',
    lastName: 'Silva',
    buyerCountry: 'BR',
    dateOfBirth: '1990-04-12',
    taxId: '12345678900',
    addressLine1: 'Rua das Flores 123',
    city: 'Florianópolis',
    stateProvinceRegion: 'SC',
    postalCode: '88000-000',
    idDocCountry: 'BR',
    idDocType: 'PASSPORT',
    selfieFile: 'https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg',
    idDocFrontFile: 'https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg'
  })
};

fetch('https://api.example.com/v1/buyer-kyc', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/buyer-kyc",
  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',
    'buyerEmail' => 'buyer@acme.com',
    'firstName' => 'Ana',
    'lastName' => 'Silva',
    'buyerCountry' => 'BR',
    'dateOfBirth' => '1990-04-12',
    'taxId' => '12345678900',
    'addressLine1' => 'Rua das Flores 123',
    'city' => 'Florianópolis',
    'stateProvinceRegion' => 'SC',
    'postalCode' => '88000-000',
    'idDocCountry' => 'BR',
    'idDocType' => 'PASSPORT',
    'selfieFile' => 'https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg',
    'idDocFrontFile' => 'https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/buyer-kyc"

	payload := strings.NewReader("{\n  \"entityType\": \"individual\",\n  \"buyerEmail\": \"buyer@acme.com\",\n  \"firstName\": \"Ana\",\n  \"lastName\": \"Silva\",\n  \"buyerCountry\": \"BR\",\n  \"dateOfBirth\": \"1990-04-12\",\n  \"taxId\": \"12345678900\",\n  \"addressLine1\": \"Rua das Flores 123\",\n  \"city\": \"Florianópolis\",\n  \"stateProvinceRegion\": \"SC\",\n  \"postalCode\": \"88000-000\",\n  \"idDocCountry\": \"BR\",\n  \"idDocType\": \"PASSPORT\",\n  \"selfieFile\": \"https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg\",\n  \"idDocFrontFile\": \"https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/buyer-kyc")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityType\": \"individual\",\n  \"buyerEmail\": \"buyer@acme.com\",\n  \"firstName\": \"Ana\",\n  \"lastName\": \"Silva\",\n  \"buyerCountry\": \"BR\",\n  \"dateOfBirth\": \"1990-04-12\",\n  \"taxId\": \"12345678900\",\n  \"addressLine1\": \"Rua das Flores 123\",\n  \"city\": \"Florianópolis\",\n  \"stateProvinceRegion\": \"SC\",\n  \"postalCode\": \"88000-000\",\n  \"idDocCountry\": \"BR\",\n  \"idDocType\": \"PASSPORT\",\n  \"selfieFile\": \"https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg\",\n  \"idDocFrontFile\": \"https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/buyer-kyc")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityType\": \"individual\",\n  \"buyerEmail\": \"buyer@acme.com\",\n  \"firstName\": \"Ana\",\n  \"lastName\": \"Silva\",\n  \"buyerCountry\": \"BR\",\n  \"dateOfBirth\": \"1990-04-12\",\n  \"taxId\": \"12345678900\",\n  \"addressLine1\": \"Rua das Flores 123\",\n  \"city\": \"Florianópolis\",\n  \"stateProvinceRegion\": \"SC\",\n  \"postalCode\": \"88000-000\",\n  \"idDocCountry\": \"BR\",\n  \"idDocType\": \"PASSPORT\",\n  \"selfieFile\": \"https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg\",\n  \"idDocFrontFile\": \"https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "ckkyc001",
  "buyerId": "ckbuy001",
  "receiverId": "rcv_8f1a2b3c",
  "status": "verifying",
  "hostedFlowUrl": null,
  "submittedAt": "2026-06-30T12:00:00.000Z",
  "approvedAt": null,
  "rejectedAt": null
}

{
  "statusCode": 400,
  "error": "TosIdMismatch",
  "message": "tosId does not match the value previously recorded for this buyer (also: missing required fields for the entityType)."
}

Accounts

Start buyer KYC via the settlement partner

Submit an individual KYC or business KYB dossier for the buyer (identified by email; the Buyer record is upserted). The dossier is forwarded to our settlement partner for verification and a submission in the verifying state is returned. If the buyer is already verifying or approved, the existing submission is returned unchanged. File fields take pre-hosted HTTPS URLs (mint them via /buyer-kyc/{buyerId}/upload-url).

POST

buyer-kyc

curl --request POST \
  --url https://api.example.com/v1/buyer-kyc \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "entityType": "individual",
  "buyerEmail": "buyer@acme.com",
  "firstName": "Ana",
  "lastName": "Silva",
  "buyerCountry": "BR",
  "dateOfBirth": "1990-04-12",
  "taxId": "12345678900",
  "addressLine1": "Rua das Flores 123",
  "city": "Florianópolis",
  "stateProvinceRegion": "SC",
  "postalCode": "88000-000",
  "idDocCountry": "BR",
  "idDocType": "PASSPORT",
  "selfieFile": "https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg",
  "idDocFrontFile": "https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg"
}
'

import requests

url = "https://api.example.com/v1/buyer-kyc"

payload = {
    "entityType": "individual",
    "buyerEmail": "buyer@acme.com",
    "firstName": "Ana",
    "lastName": "Silva",
    "buyerCountry": "BR",
    "dateOfBirth": "1990-04-12",
    "taxId": "12345678900",
    "addressLine1": "Rua das Flores 123",
    "city": "Florianópolis",
    "stateProvinceRegion": "SC",
    "postalCode": "88000-000",
    "idDocCountry": "BR",
    "idDocType": "PASSPORT",
    "selfieFile": "https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg",
    "idDocFrontFile": "https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entityType: 'individual',
    buyerEmail: 'buyer@acme.com',
    firstName: 'Ana',
    lastName: 'Silva',
    buyerCountry: 'BR',
    dateOfBirth: '1990-04-12',
    taxId: '12345678900',
    addressLine1: 'Rua das Flores 123',
    city: 'Florianópolis',
    stateProvinceRegion: 'SC',
    postalCode: '88000-000',
    idDocCountry: 'BR',
    idDocType: 'PASSPORT',
    selfieFile: 'https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg',
    idDocFrontFile: 'https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg'
  })
};

fetch('https://api.example.com/v1/buyer-kyc', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/buyer-kyc",
  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',
    'buyerEmail' => 'buyer@acme.com',
    'firstName' => 'Ana',
    'lastName' => 'Silva',
    'buyerCountry' => 'BR',
    'dateOfBirth' => '1990-04-12',
    'taxId' => '12345678900',
    'addressLine1' => 'Rua das Flores 123',
    'city' => 'Florianópolis',
    'stateProvinceRegion' => 'SC',
    'postalCode' => '88000-000',
    'idDocCountry' => 'BR',
    'idDocType' => 'PASSPORT',
    'selfieFile' => 'https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg',
    'idDocFrontFile' => 'https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/buyer-kyc"

	payload := strings.NewReader("{\n  \"entityType\": \"individual\",\n  \"buyerEmail\": \"buyer@acme.com\",\n  \"firstName\": \"Ana\",\n  \"lastName\": \"Silva\",\n  \"buyerCountry\": \"BR\",\n  \"dateOfBirth\": \"1990-04-12\",\n  \"taxId\": \"12345678900\",\n  \"addressLine1\": \"Rua das Flores 123\",\n  \"city\": \"Florianópolis\",\n  \"stateProvinceRegion\": \"SC\",\n  \"postalCode\": \"88000-000\",\n  \"idDocCountry\": \"BR\",\n  \"idDocType\": \"PASSPORT\",\n  \"selfieFile\": \"https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg\",\n  \"idDocFrontFile\": \"https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/buyer-kyc")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityType\": \"individual\",\n  \"buyerEmail\": \"buyer@acme.com\",\n  \"firstName\": \"Ana\",\n  \"lastName\": \"Silva\",\n  \"buyerCountry\": \"BR\",\n  \"dateOfBirth\": \"1990-04-12\",\n  \"taxId\": \"12345678900\",\n  \"addressLine1\": \"Rua das Flores 123\",\n  \"city\": \"Florianópolis\",\n  \"stateProvinceRegion\": \"SC\",\n  \"postalCode\": \"88000-000\",\n  \"idDocCountry\": \"BR\",\n  \"idDocType\": \"PASSPORT\",\n  \"selfieFile\": \"https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg\",\n  \"idDocFrontFile\": \"https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/buyer-kyc")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityType\": \"individual\",\n  \"buyerEmail\": \"buyer@acme.com\",\n  \"firstName\": \"Ana\",\n  \"lastName\": \"Silva\",\n  \"buyerCountry\": \"BR\",\n  \"dateOfBirth\": \"1990-04-12\",\n  \"taxId\": \"12345678900\",\n  \"addressLine1\": \"Rua das Flores 123\",\n  \"city\": \"Florianópolis\",\n  \"stateProvinceRegion\": \"SC\",\n  \"postalCode\": \"88000-000\",\n  \"idDocCountry\": \"BR\",\n  \"idDocType\": \"PASSPORT\",\n  \"selfieFile\": \"https://storage.caratuva.com/kyc/ckbuy001/selfie.jpg\",\n  \"idDocFrontFile\": \"https://storage.caratuva.com/kyc/ckbuy001/id-front.jpg\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "ckkyc001",
  "buyerId": "ckbuy001",
  "receiverId": "rcv_8f1a2b3c",
  "status": "verifying",
  "hostedFlowUrl": null,
  "submittedAt": "2026-06-30T12:00:00.000Z",
  "approvedAt": null,
  "rejectedAt": null
}

{
  "statusCode": 400,
  "error": "TosIdMismatch",
  "message": "tosId does not match the value previously recorded for this buyer (also: missing required fields for the entityType)."
}

Authorizations

X-API-Key

string

header

required

Body

application/json

buyerEmail

string<email>

required

entityType

enum<string>

Available options:

individual,

business

buyerName

string

Required string length: 1 - 200

buyerCountry

string

Required string length: 2

phone

string

Required string length: 3 - 32

invoiceId

string

Minimum string length: 1

tosId

string

Minimum string length: 1

kycTier

enum<string>

Available options:

standard,

enhanced

firstName

string

Required string length: 1 - 100

lastName

string

Required string length: 1 - 100

dateOfBirth

string

taxId

string

Required string length: 1 - 64

addressLine1

string

Required string length: 1 - 200

addressLine2

string

Maximum string length: 200

city

string

Required string length: 1 - 120

stateProvinceRegion

string

Required string length: 1 - 120

postalCode

string

Required string length: 1 - 32

idDocCountry

string

Required string length: 2

idDocType

enum<string>

Available options:

PASSPORT,

ID_CARD,

DRIVERS

idDocNumber

string

Required string length: 1 - 64

selfieFile

string<uri>

idDocFrontFile

string<uri>

idDocBackFile

string<uri>

legalName

string

Required string length: 1 - 200

formationDate

string

website

string<uri>

incorporationDocFile

string<uri>

proofOfOwnershipDocFile

string<uri>

proofOfAddressDocType

enum<string>

Available options:

UTILITY_BILL,

BANK_STATEMENT,

RENTAL_AGREEMENT,

TAX_DOCUMENT,

GOVERNMENT_CORRESPONDENCE

proofOfAddressDocFile

string<uri>

owners

object[]

Required array length: 1 - 10 elements

Show child attributes

Response

Buyer KYC submission created (or the in-flight submission if one already exists)

string

required

buyerId

string

required

receiverId

string

required

status

enum<string>

required

Available options:

not_started,

pending,

verifying,

approved,

rejected

hostedFlowUrl

string | null

required

submittedAt

string

required

approvedAt

string | null

required

rejectedAt

string | null

required

Overview

Integration

Endpoints

Start buyer KYC via the settlement partner

Authorizations

Body

Response