Capture the buyer KYC dossier and deliver a ToS link (async)

curl --request POST \
  --url https://api.example.com/v1/buyer-kyc/request-tos \
  --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/request-tos"

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/request-tos', 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/request-tos",
  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/request-tos"

	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/request-tos")
  .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/request-tos")

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

{
  "buyerId": "ckbuy001",
  "acceptUrl": "https://api.caratuva.com/v1/public/tos/start?t=abc123",
  "emailSent": true
}

Accounts

Capture the buyer KYC dossier and deliver a ToS link (async)

Opt-in async alternative to POST /buyer-kyc. Captures the buyer’s KYC dossier (same body) and mints a single-use link to accept the settlement partner’s terms; the BlindPay submission fires automatically once the buyer accepts. delivery: 'email' (default) has Caratuva email the buyer; delivery: 'link' returns the acceptUrl for you to deliver yourself. Use this when the buyer should accept their own terms; use POST /buyer-kyc when you manage ToS yourself.

POST

buyer-kyc

request-tos

curl --request POST \
  --url https://api.example.com/v1/buyer-kyc/request-tos \
  --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/request-tos"

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/request-tos', 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/request-tos",
  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/request-tos"

	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/request-tos")
  .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/request-tos")

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

{
  "buyerId": "ckbuy001",
  "acceptUrl": "https://api.caratuva.com/v1/public/tos/start?t=abc123",
  "emailSent": true
}

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

delivery

enum<string>

default:email

Available options:

email,

link

Response

201 - application/json

KYC dossier captured; ToS acceptance link returned (and emailed when delivery=email)

buyerId

string

required

acceptUrl

string<uri>

required

emailSent

boolean

required

Overview

Integration

Endpoints

Capture the buyer KYC dossier and deliver a ToS link (async)

Authorizations

Body

Response