Subir Documentos de Identidad KYC y 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
}

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

Authorization

string

header

requerido

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

Cuerpo

multipart/form-data

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

country

string

requerido

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

Ejemplo:

"USA"

documentType

enum<string>

requerido

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"

file

requerido

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

target

enum<string>

requerido

The target entity for which the document is being uploaded

Opciones disponibles:

customer

Ejemplo:

"customer"

targetId

string

requerido

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

Minimum string length: 1

Ejemplo:

"customer_66c4168d418a410eae282b83883bdc39"

description

string

Optional description or notes about the document

Ejemplo:

"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.

Opciones disponibles:

front,

back

Ejemplo:

"front"

Respuesta

Response for an ID document uploaded for an individual customer.

country

string

requerido

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

Ejemplo:

"USA"

createdAt

string

requerido

The date and time the document was created

Ejemplo:

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

description

string

requerido

The description of the document

Ejemplo:

"Passport photo page"

documentType

enum<string>

requerido

The type of the document

Opciones disponibles:

drivers,

passport,

id_card,

residence_permit,

br_digital_drivers,

br_digital_id

Ejemplo:

"passport"

fileName

string

requerido

The name of the document file

Ejemplo:

"passport_front_20250101.pdf"

fileSize

number

requerido

The size of the document in bytes

Ejemplo:

2048576

string

requerido

The unique identifier of the document

Ejemplo:

"documentFile_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

mimeType

string

requerido

The MIME type of the document file

Ejemplo:

"application/pdf"

side

enum<string>

requerido

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"

target

enum<string>

requerido

The target entity for which the document is being uploaded

Opciones disponibles:

customer

Ejemplo:

"customer"

targetId

string

requerido

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

Ejemplo:

"customer_66c4168d418a410eae282b83883bdc39"

Última modificación el 19 de agosto de 2026

Incorporación

Cuentas

Movimiento de dinero

Webhooks

Subir Documentos de Identidad KYC y KYB

Autorizaciones

Cuerpo

Respuesta