Enviar Documentos de Identidade KYC e KYB

Upload Document

curl --request POST \
  --url https://api.spherepay.co/v2/document \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form country=USA \
  --form 'description=Passport photo page' \
  --form documentType=passport \
  --form 'file=(binary)' \
  --form side=front \
  --form target=customer \
  --form targetId=customer_66c4168d418a410eae282b83883bdc39

import requests

url = "https://api.spherepay.co/v2/document"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001--"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "multipart/form-data"
}

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

print(response.text)

const form = new FormData();
form.append('country', 'USA');
form.append('description', 'Passport photo page');
form.append('documentType', 'passport');
form.append('file', '(binary)');
form.append('side', 'front');
form.append('target', 'customer');
form.append('targetId', 'customer_66c4168d418a410eae282b83883bdc39');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.spherepay.co/v2/document', 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.spherepay.co/v2/document",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$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.spherepay.co/v2/document"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001--")

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

	req.Header.Add("Authorization", "Bearer <token>")

	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.spherepay.co/v2/document")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/document")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001--"

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

{
  "country": "USA",
  "createdAt": "2025-12-31T10:30:00.000Z",
  "description": "Passport photo page",
  "documentType": "passport",
  "fileName": "passport_front_20250101.pdf",
  "fileSize": 2048576,
  "id": "documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "mimeType": "application/pdf",
  "side": "front",
  "target": "customer",
  "targetId": "customer_66c4168d418a410eae282b83883bdc39"
}

{
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Invalid request parameters",
  "status": 400
}

{
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Resource not found",
  "status": 404
}

{
  "code": "customer/onboarding-v3-managed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "This customer cannot be used with this route.",
  "status": 409
}

{
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Validation failed",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ],
  "status": 422
}

Upload Document

curl --request POST \
  --url https://api.spherepay.co/v2/document \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form country=USA \
  --form 'description=Passport photo page' \
  --form documentType=passport \
  --form 'file=(binary)' \
  --form side=front \
  --form target=customer \
  --form targetId=customer_66c4168d418a410eae282b83883bdc39

import requests

url = "https://api.spherepay.co/v2/document"

payload = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001--"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "multipart/form-data"
}

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

print(response.text)

const form = new FormData();
form.append('country', 'USA');
form.append('description', 'Passport photo page');
form.append('documentType', 'passport');
form.append('file', '(binary)');
form.append('side', 'front');
form.append('target', 'customer');
form.append('targetId', 'customer_66c4168d418a410eae282b83883bdc39');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.spherepay.co/v2/document', 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.spherepay.co/v2/document",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$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.spherepay.co/v2/document"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001--")

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

	req.Header.Add("Authorization", "Bearer <token>")

	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.spherepay.co/v2/document")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/document")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"description\"\r\n\r\nPassport photo page\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001--"

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

{
  "country": "USA",
  "createdAt": "2025-12-31T10:30:00.000Z",
  "description": "Passport photo page",
  "documentType": "passport",
  "fileName": "passport_front_20250101.pdf",
  "fileSize": 2048576,
  "id": "documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "mimeType": "application/pdf",
  "side": "front",
  "target": "customer",
  "targetId": "customer_66c4168d418a410eae282b83883bdc39"
}

{
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Invalid request parameters",
  "status": 400
}

{
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Resource not found",
  "status": 404
}

{
  "code": "customer/onboarding-v3-managed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "This customer cannot be used with this route.",
  "status": 409
}

{
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Validation failed",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ],
  "status": 422
}

Envie um documento de identidade para um cliente ou representante empresarial como parte do processo de verificação KYC ou KYB. Os documentos são submetidos como dados de formulário multipart. Os formatos de arquivo aceitos são PDF, JPEG e PNG, validados pela assinatura do arquivo e não pela extensão. O tamanho máximo é de 10 MB por arquivo, ou de 8 MB para documentos de identidade (passport, drivers, id_card, residence_permit, br_digital_drivers, br_digital_id). Os campos target e documentType determinam como o SpherePay roteará e processará o envio — clientes individuais, clientes empresariais e representantes empresariais possuem seus próprios conjuntos de tipos de documentos aceitos.

Documentos para clientes individuais são enviados com target: "customer". Documentos para representantes empresariais (UBOs) usam target: "business_representative" e o targetId deve ser o ID do representante, não o do cliente.

Autorizações

Authorization

string

header

obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Corpo

multipart/form-data

Upload identity documents for individual customers. Requires country of issuance and optionally the document side (front/back).

country

string

obrigatório

The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See Country Codes.

Exemplo:

"USA"

documentType

enum<string>

obrigatório

ID documents for individual customers. See Document Guideline for requirements.

Opções disponíveis:

passport,

drivers,

id_card,

residence_permit,

br_digital_drivers,

br_digital_id

Exemplo:

"passport"

file

obrigatório

The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 8MB. Minimum file size: 10KB.

target

enum<string>

obrigatório

The target entity for which the document is being uploaded

Opções disponíveis:

customer

Exemplo:

"customer"

targetId

string

obrigatório

The unique identifier of the target entity for which the document is being uploaded

Minimum string length: 1

Exemplo:

"customer_66c4168d418a410eae282b83883bdc39"

description

string

Optional description or notes about the document

Exemplo:

"Front side of driver's license"

side

enum<string>

The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents.

Opções disponíveis:

front,

back

Exemplo:

"front"

Resposta

Response for an ID document uploaded for an individual customer.

country

string

obrigatório

The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA)

Exemplo:

"USA"

createdAt

string

obrigatório

The date and time the document was created

Exemplo:

"2025-12-31T10:30:00.000Z"

description

string

obrigatório

The description of the document

Exemplo:

"Passport photo page"

documentType

enum<string>

obrigatório

The type of the document

Opções disponíveis:

drivers,

passport,

id_card,

residence_permit,

br_digital_drivers,

br_digital_id

Exemplo:

"passport"

fileName

string

obrigatório

The name of the document file

Exemplo:

"passport_front_20250101.pdf"

fileSize

number

obrigatório

The size of the document in bytes

Exemplo:

2048576

string

obrigatório

The unique identifier of the document

Exemplo:

"documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

mimeType

string

obrigatório

The MIME type of the document file

Exemplo:

"application/pdf"

side

enum<string>

obrigatório

The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents.

Opções disponíveis:

front,

back

Exemplo:

"front"

target

enum<string>

obrigatório

The target entity for which the document is being uploaded

Opções disponíveis:

customer

Exemplo:

"customer"

targetId

string

obrigatório

The unique identifier of the target entity for which the document is being uploaded

Exemplo:

"customer_66c4168d418a410eae282b83883bdc39"

Última modificação em 19 de agosto de 2026

Onboarding

Contas

Movimentação de dinheiro

Webhooks

Enviar Documentos de Identidade KYC e KYB

Autorizações

Corpo

Resposta