Upload Document
curl --request POST \
--url https://api.spherepay.co/v2/document \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form targetId=customer_66c4168d418a410eae282b83883bdc39 \
--form target=customer \
--form documentType=passport \
--form country=USA \
--form side=front \
--form 'description=Passport photo page' \
--form 'file=(binary)' \
--form 0.file='@example-file' \
--form 1.file='@example-file' \
--form 2.file='@example-file' \
--form 3.file='@example-file' \
--form 4.file='@example-file' \
--form 5.file='@example-file'import requests
url = "https://api.spherepay.co/v2/document"
files = {
"0.file": ("example-file", open("example-file", "rb")),
"1.file": ("example-file", open("example-file", "rb")),
"2.file": ("example-file", open("example-file", "rb")),
"3.file": ("example-file", open("example-file", "rb")),
"4.file": ("example-file", open("example-file", "rb")),
"5.file": ("example-file", open("example-file", "rb"))
}
payload = {
"targetId": "customer_66c4168d418a410eae282b83883bdc39",
"target": "customer",
"documentType": "passport",
"country": "USA",
"side": "front",
"description": "Passport photo page",
"file": "(binary)"
}
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('targetId', 'customer_66c4168d418a410eae282b83883bdc39');
form.append('target', 'customer');
form.append('documentType', 'passport');
form.append('country', 'USA');
form.append('side', 'front');
form.append('description', 'Passport photo page');
form.append('file', '(binary)');
form.append('0.file', '{
"fileName": "example-file"
}');
form.append('1.file', '{
"fileName": "example-file"
}');
form.append('2.file', '{
"fileName": "example-file"
}');
form.append('3.file', '{
"fileName": "example-file"
}');
form.append('4.file', '{
"fileName": "example-file"
}');
form.append('5.file', '{
"fileName": "example-file"
}');
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=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\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=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\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=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\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=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\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=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\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=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\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=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\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=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"id": "documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"targetId": "customer_66c4168d418a410eae282b83883bdc39",
"target": "customer",
"documentType": "passport",
"country": "USA",
"side": "front",
"description": "Passport photo page",
"fileName": "passport_front_20250101.pdf",
"fileSize": 2048576,
"mimeType": "application/pdf",
"createdAt": "2025-12-31T10:30:00.000Z"
}{
"status": 400,
"detail": "Invalid request parameters",
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}{
"status": 404,
"detail": "Resource not found",
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}{
"status": 422,
"detail": "Validation failed",
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
]
}Documentos y Verificación
Subir Documentos de Identidad KYC y KYB
Upload a document for a customer.
Upload Document
curl --request POST \
--url https://api.spherepay.co/v2/document \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form targetId=customer_66c4168d418a410eae282b83883bdc39 \
--form target=customer \
--form documentType=passport \
--form country=USA \
--form side=front \
--form 'description=Passport photo page' \
--form 'file=(binary)' \
--form 0.file='@example-file' \
--form 1.file='@example-file' \
--form 2.file='@example-file' \
--form 3.file='@example-file' \
--form 4.file='@example-file' \
--form 5.file='@example-file'import requests
url = "https://api.spherepay.co/v2/document"
files = {
"0.file": ("example-file", open("example-file", "rb")),
"1.file": ("example-file", open("example-file", "rb")),
"2.file": ("example-file", open("example-file", "rb")),
"3.file": ("example-file", open("example-file", "rb")),
"4.file": ("example-file", open("example-file", "rb")),
"5.file": ("example-file", open("example-file", "rb"))
}
payload = {
"targetId": "customer_66c4168d418a410eae282b83883bdc39",
"target": "customer",
"documentType": "passport",
"country": "USA",
"side": "front",
"description": "Passport photo page",
"file": "(binary)"
}
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, data=payload, files=files, headers=headers)
print(response.text)const form = new FormData();
form.append('targetId', 'customer_66c4168d418a410eae282b83883bdc39');
form.append('target', 'customer');
form.append('documentType', 'passport');
form.append('country', 'USA');
form.append('side', 'front');
form.append('description', 'Passport photo page');
form.append('file', '(binary)');
form.append('0.file', '{
"fileName": "example-file"
}');
form.append('1.file', '{
"fileName": "example-file"
}');
form.append('2.file', '{
"fileName": "example-file"
}');
form.append('3.file', '{
"fileName": "example-file"
}');
form.append('4.file', '{
"fileName": "example-file"
}');
form.append('5.file', '{
"fileName": "example-file"
}');
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=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\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=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\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=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\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=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\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=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\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=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\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=\"targetId\"\r\n\r\ncustomer_66c4168d418a410eae282b83883bdc39\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"target\"\r\n\r\ncustomer\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"documentType\"\r\n\r\npassport\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"country\"\r\n\r\nUSA\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"side\"\r\n\r\nfront\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=\"file\"\r\n\r\n(binary)\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"0.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"1.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"2.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"3.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"4.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"5.file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"
response = http.request(request)
puts response.read_body{
"id": "documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"targetId": "customer_66c4168d418a410eae282b83883bdc39",
"target": "customer",
"documentType": "passport",
"country": "USA",
"side": "front",
"description": "Passport photo page",
"fileName": "passport_front_20250101.pdf",
"fileSize": 2048576,
"mimeType": "application/pdf",
"createdAt": "2025-12-31T10:30:00.000Z"
}{
"status": 400,
"detail": "Invalid request parameters",
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}{
"status": 404,
"detail": "Resource not found",
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c"
}{
"status": 422,
"detail": "Validation failed",
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
]
}Sube un documento de identidad para un cliente o representante empresarial como parte del proceso de verificación KYC o KYB. Los documentos se envían como datos de formulario multipart. Los formatos de archivo aceptados son PDF, JPEG y PNG, validados por la firma del archivo y no por la extensión. El tamaño máximo es de 10 MB por archivo, o de 8 MB para documentos de identidad (
passport, drivers, id_card, residence_permit, br_digital_drivers, br_digital_id). Los campos target y documentType determinan cómo SpherePay enruta y procesa la carga — los clientes individuales, los clientes empresariales y los representantes empresariales tienen cada uno su propio conjunto de tipos de documentos aceptados.
Los documentos para clientes individuales se suben con
target: "customer". Los documentos para representantes empresariales (UBOs) usan target: "business_representative" y el targetId debe ser el ID del representante, no el del cliente.Autorizaciones
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Cuerpo
multipart/form-data
- ID Document
- Other Document
- Business
- ID Document
- Other Document
- Transfer
Upload identity documents for individual customers. Requires country of issuance and optionally the document side (front/back).
The unique identifier of the target entity for which the document is being uploaded
Minimum string length:
1Ejemplo:
"customer_66c4168d418a410eae282b83883bdc39"
The document file to upload. Accepted formats: PDF, JPEG, PNG. Maximum file size: 10MB (8MB for passport, id_card, drivers, residence_permit, br_digital_drivers, and br_digital_id documents)
The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA). See Country Codes.
Ejemplo:
"USA"
The target entity for which the document is being uploaded
Opciones disponibles:
customer Ejemplo:
"customer"
ID documents for individual customers. See Document Guideline for requirements.
Opciones disponibles:
passport, drivers, id_card, residence_permit, br_digital_drivers, br_digital_id Ejemplo:
"passport"
Optional description or notes about the document
Ejemplo:
"Front side of driver's license"
The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents. Not applicable to br_digital_drivers / br_digital_id — these are single-sided; omit side.
Opciones disponibles:
front, back Ejemplo:
"front"
Respuesta
- ID Document
- Other Document
- Business Customer Document
- ID Document
- Other Document
- Transfer
Response for an ID document uploaded for an individual customer.
The unique identifier of the document
Ejemplo:
"documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
The unique identifier of the target entity for which the document is being uploaded
Ejemplo:
"customer_66c4168d418a410eae282b83883bdc39"
The date and time the document was created
Ejemplo:
"2025-12-31T10:30:00.000Z"
The name of the document file
Ejemplo:
"passport_front_20250101.pdf"
The size of the document in bytes
Ejemplo:
2048576
The MIME type of the document file
Ejemplo:
"application/pdf"
The description of the document
Ejemplo:
"Passport photo page"
The target entity for which the document is being uploaded
Opciones disponibles:
customer Ejemplo:
"customer"
The type of the document
Opciones disponibles:
drivers, passport, id_card, residence_permit, br_digital_drivers, br_digital_id Ejemplo:
"passport"
The ISO3166-1 Alpha-3 country code associated with the document (e.g., USA, GBR, FRA)
Ejemplo:
"USA"
The side of the document if it has multiple sides (e.g., front, back). Leave undefined for single-sided documents.
Opciones disponibles:
front, back Ejemplo:
"front"
Última modificación el 19 de agosto de 2026
⌘I