Create a Customer
curl --request POST \
--url https://api.spherepay.co/v2/customer \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual",
"dateOfBirth": "2026-01-01",
"firstName": "Jane",
"lastName": "Smith",
"meta": {},
"middleName": "Anne"
}
'import requests
url = "https://api.spherepay.co/v2/customer"
payload = {
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual",
"dateOfBirth": "2026-01-01",
"firstName": "Jane",
"lastName": "Smith",
"meta": {},
"middleName": "Anne"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
address: {
city: 'Chicago',
country: 'USA',
line1: '233 South Wacker Drive',
line2: 'Suite 4700',
postalCode: '60606',
state: 'IL'
},
email: 'jane.smith@example.com',
phone: '+14155550123',
type: 'individual',
dateOfBirth: '2026-01-01',
firstName: 'Jane',
lastName: 'Smith',
meta: {},
middleName: 'Anne'
})
};
fetch('https://api.spherepay.co/v2/customer', 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/customer",
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([
'address' => [
'city' => 'Chicago',
'country' => 'USA',
'line1' => '233 South Wacker Drive',
'line2' => 'Suite 4700',
'postalCode' => '60606',
'state' => 'IL'
],
'email' => 'jane.smith@example.com',
'phone' => '+14155550123',
'type' => 'individual',
'dateOfBirth' => '2026-01-01',
'firstName' => 'Jane',
'lastName' => 'Smith',
'meta' => [
],
'middleName' => 'Anne'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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/customer"
payload := strings.NewReader("{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"dateOfBirth\": \"2026-01-01\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.spherepay.co/v2/customer")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"dateOfBirth\": \"2026-01-01\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/customer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"dateOfBirth\": \"2026-01-01\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\"\n}"
response = http.request(request)
puts response.read_body{
"createdAt": "2026-03-09T20:46:31.305Z",
"id": "customer_f31121c389624d3697cbf3ea8830b7a4",
"tosStatus": "incomplete",
"type": "individual",
"updatedAt": "2026-03-09T20:46:31.305Z",
"verificationProfiles": [
{
"criteria": {
"complete": [
"email_address",
"phone_number",
"residential_address",
"tax_identification_number"
],
"errors": [],
"pending": [],
"required": [
"identity_document",
"liveness_report_document"
]
},
"name": "kyc_profile_a",
"status": "incomplete"
}
],
"dateOfBirth": "1990-01-15",
"email": "jane.smith@example.com",
"firstName": "Jane",
"lastName": "Smith",
"meta": {},
"personalInformation": {
"accountPurpose": "<string>",
"accountPurposeDescription": "<string>",
"actingAsIntermediary": false,
"countryOfBirth": "USA",
"employmentStatus": "<string>",
"expectedMonthlyPayments": "<string>",
"gender": "<string>",
"middleName": "James",
"nationality": "USA",
"occupationSocCode": "151252",
"residencyCountry": "USA",
"sourceOfFunds": "<string>",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberDescription": "<string>",
"taxIdentificationNumberType": "ssn"
},
"phone": "+14155550123"
}{
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Invalid request parameters",
"status": 400
}{
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Resource not found",
"status": 404
}{
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Validation failed",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
],
"status": 422
}Clientes
Criar um Cliente Individual ou Empresarial
Create a new customer.
Create a Customer
curl --request POST \
--url https://api.spherepay.co/v2/customer \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual",
"dateOfBirth": "2026-01-01",
"firstName": "Jane",
"lastName": "Smith",
"meta": {},
"middleName": "Anne"
}
'import requests
url = "https://api.spherepay.co/v2/customer"
payload = {
"address": {
"city": "Chicago",
"country": "USA",
"line1": "233 South Wacker Drive",
"line2": "Suite 4700",
"postalCode": "60606",
"state": "IL"
},
"email": "jane.smith@example.com",
"phone": "+14155550123",
"type": "individual",
"dateOfBirth": "2026-01-01",
"firstName": "Jane",
"lastName": "Smith",
"meta": {},
"middleName": "Anne"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
address: {
city: 'Chicago',
country: 'USA',
line1: '233 South Wacker Drive',
line2: 'Suite 4700',
postalCode: '60606',
state: 'IL'
},
email: 'jane.smith@example.com',
phone: '+14155550123',
type: 'individual',
dateOfBirth: '2026-01-01',
firstName: 'Jane',
lastName: 'Smith',
meta: {},
middleName: 'Anne'
})
};
fetch('https://api.spherepay.co/v2/customer', 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/customer",
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([
'address' => [
'city' => 'Chicago',
'country' => 'USA',
'line1' => '233 South Wacker Drive',
'line2' => 'Suite 4700',
'postalCode' => '60606',
'state' => 'IL'
],
'email' => 'jane.smith@example.com',
'phone' => '+14155550123',
'type' => 'individual',
'dateOfBirth' => '2026-01-01',
'firstName' => 'Jane',
'lastName' => 'Smith',
'meta' => [
],
'middleName' => 'Anne'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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/customer"
payload := strings.NewReader("{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"dateOfBirth\": \"2026-01-01\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.spherepay.co/v2/customer")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"dateOfBirth\": \"2026-01-01\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.spherepay.co/v2/customer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"address\": {\n \"city\": \"Chicago\",\n \"country\": \"USA\",\n \"line1\": \"233 South Wacker Drive\",\n \"line2\": \"Suite 4700\",\n \"postalCode\": \"60606\",\n \"state\": \"IL\"\n },\n \"email\": \"jane.smith@example.com\",\n \"phone\": \"+14155550123\",\n \"type\": \"individual\",\n \"dateOfBirth\": \"2026-01-01\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Smith\",\n \"meta\": {},\n \"middleName\": \"Anne\"\n}"
response = http.request(request)
puts response.read_body{
"createdAt": "2026-03-09T20:46:31.305Z",
"id": "customer_f31121c389624d3697cbf3ea8830b7a4",
"tosStatus": "incomplete",
"type": "individual",
"updatedAt": "2026-03-09T20:46:31.305Z",
"verificationProfiles": [
{
"criteria": {
"complete": [
"email_address",
"phone_number",
"residential_address",
"tax_identification_number"
],
"errors": [],
"pending": [],
"required": [
"identity_document",
"liveness_report_document"
]
},
"name": "kyc_profile_a",
"status": "incomplete"
}
],
"dateOfBirth": "1990-01-15",
"email": "jane.smith@example.com",
"firstName": "Jane",
"lastName": "Smith",
"meta": {},
"personalInformation": {
"accountPurpose": "<string>",
"accountPurposeDescription": "<string>",
"actingAsIntermediary": false,
"countryOfBirth": "USA",
"employmentStatus": "<string>",
"expectedMonthlyPayments": "<string>",
"gender": "<string>",
"middleName": "James",
"nationality": "USA",
"occupationSocCode": "151252",
"residencyCountry": "USA",
"sourceOfFunds": "<string>",
"taxIdentificationNumberCountry": "USA",
"taxIdentificationNumberDescription": "<string>",
"taxIdentificationNumberType": "ssn"
},
"phone": "+14155550123"
}{
"code": "address/invalid",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Invalid request parameters",
"status": 400
}{
"code": "resource/not-found",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Resource not found",
"status": 404
}{
"code": "validation/failed",
"correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
"detail": "Validation failed",
"errors": [
{
"detail": "Invalid email format",
"pointer": "/email"
},
{
"detail": "Name is required",
"pointer": "/name"
}
],
"status": 422
}Antes de iniciar qualquer transferência, você deve criar um registro de cliente (
customer) no SpherePay. Este endpoint registra um cliente individual ou empresarial e retorna um objeto customer com um ID único e um array verificationProfiles que rastreia o status de conclusão do KYC/KYB. Você deve especificar type antecipadamente — ele não pode ser alterado após a criação.
Clientes pessoas físicas residentes na região EEA+ e empresas constituídas na EEA+ têm campos adicionais que devem estar presentes antes da verificação. Esses campos são opcionais na criação. Consulte Residentes EEA+ e Empresas EEA+.Autorizações
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Corpo
application/json
- Individual Customer Create
- Business Customer Create
The customer's address.
Show child attributes
Show child attributes
The customer email address
Maximum string length:
254Exemplo:
"jane.smith@example.com"
The customer phone number in E.164 format
Pattern:
^\+(?:[0-9]){6,14}[0-9]$Exemplo:
"+14155550123"
Opções disponíveis:
individual The date string in YYYY-MM-DD format
Exemplo:
"2026-01-01"
The customer's legal first name.
Required string length:
1 - 100Exemplo:
"Jane"
The customer's legal last name.
Required string length:
1 - 100Exemplo:
"Smith"
Additional metadata associated with the customer
Show child attributes
Show child attributes
The customer's legal middle name.
Required string length:
1 - 100Exemplo:
"Anne"
Personal information including tax identification details for individual customers. When any tax identification field is provided, all tax identification fields (number, type, country) and address are required. Please refer to the Individual Verification Criteria for the full list of reference.
Show child attributes
Show child attributes
Resposta
- Individual
- Business
Response containing information about an individual customer.
ISO 8601 formatted customer creation timestamp
Exemplo:
"2026-03-09T20:46:31.305Z"
Customer ID
Exemplo:
"customer_f31121c389624d3697cbf3ea8830b7a4"
Customer Terms of Service acceptance status (incomplete | pending | approved).
Opções disponíveis:
incomplete, pending, approved Exemplo:
"incomplete"
Customer type
Opções disponíveis:
individual Exemplo:
"individual"
ISO 8601 formatted customer update timestamp
Exemplo:
"2026-03-09T20:46:31.305Z"
Array of verification profiles. For individual customers, this will include kyc_profile_a. For business customers, this will include kyb_profile_a. See KYC Flow for individuals or KYB Flow for businesses. See Verification Profile for individual status definitions and criteria breakdown or Verification Profile for business status definitions and criteria breakdown.
Show child attributes
Show child attributes
Exemplo:
[
{
"criteria": {
"complete": [
"email_address",
"phone_number",
"residential_address",
"tax_identification_number"
],
"errors": [],
"pending": [],
"required": [
"identity_document",
"liveness_report_document"
]
},
"name": "kyc_profile_a",
"status": "incomplete"
}
]
The customer's date of birth in YYYY-MM-DD format (individual customers only).
Exemplo:
"1990-01-15"
Customer email address
Exemplo:
"jane.smith@example.com"
Customer first name (individual customers only)
Exemplo:
"Jane"
Customer last name (individual customers only)
Exemplo:
"Smith"
Show child attributes
Show child attributes
Personal information for an individual customer, echoed back from the most recent submission. The tax identification number is omitted from responses for privacy.
Show child attributes
Show child attributes
Customer phone number
Exemplo:
"+14155550123"
Última modificação em 27 de agosto de 2026