Saltar al contenido principal
Create a Customer
curl --request POST \
  --url https://api.spherepay.co/v2/customer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "individual",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "address": {
    "line1": "233 South Wacker Drive",
    "city": "Chicago",
    "country": "USA",
    "line2": "Suite 4700",
    "state": "IL",
    "postalCode": "60606"
  },
  "firstName": "Jane",
  "lastName": "Smith",
  "middleName": "Anne",
  "dateOfBirth": "2026-01-01",
  "meta": {}
}
'
import requests

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

payload = {
    "type": "individual",
    "email": "jane.smith@example.com",
    "phone": "+14155550123",
    "address": {
        "line1": "233 South Wacker Drive",
        "city": "Chicago",
        "country": "USA",
        "line2": "Suite 4700",
        "state": "IL",
        "postalCode": "60606"
    },
    "firstName": "Jane",
    "lastName": "Smith",
    "middleName": "Anne",
    "dateOfBirth": "2026-01-01",
    "meta": {}
}
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({
    type: 'individual',
    email: 'jane.smith@example.com',
    phone: '+14155550123',
    address: {
      line1: '233 South Wacker Drive',
      city: 'Chicago',
      country: 'USA',
      line2: 'Suite 4700',
      state: 'IL',
      postalCode: '60606'
    },
    firstName: 'Jane',
    lastName: 'Smith',
    middleName: 'Anne',
    dateOfBirth: '2026-01-01',
    meta: {}
  })
};

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([
    'type' => 'individual',
    'email' => 'jane.smith@example.com',
    'phone' => '+14155550123',
    'address' => [
        'line1' => '233 South Wacker Drive',
        'city' => 'Chicago',
        'country' => 'USA',
        'line2' => 'Suite 4700',
        'state' => 'IL',
        'postalCode' => '60606'
    ],
    'firstName' => 'Jane',
    'lastName' => 'Smith',
    'middleName' => 'Anne',
    'dateOfBirth' => '2026-01-01',
    'meta' => [
        
    ]
  ]),
  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  \"type\": \"individual\",\n  \"email\": \"jane.smith@example.com\",\n  \"phone\": \"+14155550123\",\n  \"address\": {\n    \"line1\": \"233 South Wacker Drive\",\n    \"city\": \"Chicago\",\n    \"country\": \"USA\",\n    \"line2\": \"Suite 4700\",\n    \"state\": \"IL\",\n    \"postalCode\": \"60606\"\n  },\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"middleName\": \"Anne\",\n  \"dateOfBirth\": \"2026-01-01\",\n  \"meta\": {}\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  \"type\": \"individual\",\n  \"email\": \"jane.smith@example.com\",\n  \"phone\": \"+14155550123\",\n  \"address\": {\n    \"line1\": \"233 South Wacker Drive\",\n    \"city\": \"Chicago\",\n    \"country\": \"USA\",\n    \"line2\": \"Suite 4700\",\n    \"state\": \"IL\",\n    \"postalCode\": \"60606\"\n  },\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"middleName\": \"Anne\",\n  \"dateOfBirth\": \"2026-01-01\",\n  \"meta\": {}\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  \"type\": \"individual\",\n  \"email\": \"jane.smith@example.com\",\n  \"phone\": \"+14155550123\",\n  \"address\": {\n    \"line1\": \"233 South Wacker Drive\",\n    \"city\": \"Chicago\",\n    \"country\": \"USA\",\n    \"line2\": \"Suite 4700\",\n    \"state\": \"IL\",\n    \"postalCode\": \"60606\"\n  },\n  \"firstName\": \"Jane\",\n  \"lastName\": \"Smith\",\n  \"middleName\": \"Anne\",\n  \"dateOfBirth\": \"2026-01-01\",\n  \"meta\": {}\n}"

response = http.request(request)
puts response.read_body
{
  "id": "customer_f31121c389624d3697cbf3ea8830b7a4",
  "verificationProfiles": [
    {
      "name": "kyc_profile_a",
      "status": "incomplete",
      "criteria": {
        "complete": [
          "email_address",
          "phone_number",
          "residential_address",
          "tax_identification_number"
        ],
        "pending": [],
        "required": [
          "identity_document",
          "liveness_report_document"
        ],
        "errors": []
      }
    }
  ],
  "tosStatus": "incomplete",
  "createdAt": "2026-03-09T20:46:31.305Z",
  "updatedAt": "2026-03-09T20:46:31.305Z",
  "type": "individual",
  "email": "jane.smith@example.com",
  "phone": "+14155550123",
  "meta": {},
  "firstName": "Jane",
  "lastName": "Smith",
  "dateOfBirth": "1990-01-15",
  "personalInformation": {
    "taxIdentificationNumberType": "ssn",
    "taxIdentificationNumberCountry": "USA",
    "taxIdentificationNumberDescription": "<string>",
    "gender": "male",
    "countryOfBirth": "USA",
    "nationality": "USA",
    "middleName": "James",
    "occupationSocCode": "15-1132",
    "residencyCountry": "USA",
    "sourceOfFunds": "salary"
  }
}
{
  "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"
    }
  ]
}
Antes de poder iniciar cualquier transferencia, debes crear un registro de cliente (customer) en SpherePay. Este endpoint registra un cliente individual o empresarial y devuelve un objeto de cliente con un ID único y un array verificationProfiles que rastrea el estado de completitud de KYC/KYB. Debes especificar type desde el inicio — no puede cambiarse después de la creación.

Autorizaciones

​
Authorization
string
header
requerido

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

Cuerpo

application/json
​
type
enum<string>
requerido
Opciones disponibles:
individual
​
email
string<email>
requerido

The customer email address

Maximum string length: 254
Ejemplo:

"jane.smith@example.com"

​
phone
string
requerido

The customer phone number in E.164 format

Pattern: ^\+(?:[0-9]){6,14}[0-9]$
Ejemplo:

"+14155550123"

​
address
object
requerido

The customer's address.

​
firstName
string

The customer's legal first name.

Required string length: 1 - 100
Ejemplo:

"Jane"

​
lastName
string

The customer's legal last name.

Required string length: 1 - 100
Ejemplo:

"Smith"

​
middleName
string

The customer's legal middle name.

Required string length: 1 - 100
Ejemplo:

"Anne"

​
dateOfBirth
string

The date string in YYYY-MM-DD format

Ejemplo:

"2026-01-01"

​
personalInformation
object

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.

​
meta
object

Additional metadata associated with the customer

Respuesta

Response containing information about an individual customer.

​
id
string
requerido

Customer ID

Ejemplo:

"customer_f31121c389624d3697cbf3ea8830b7a4"

​
verificationProfiles
object[]
requerido

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.

Ejemplo:
[
  {
    "name": "kyc_profile_a",
    "status": "incomplete",
    "criteria": {
      "complete": [
        "email_address",
        "phone_number",
        "residential_address",
        "tax_identification_number"
      ],
      "pending": [],
      "required": [
        "identity_document",
        "liveness_report_document"
      ],
      "errors": []
    }
  }
]
​
tosStatus
enum<string>
requerido

Customer Terms of Service acceptance status (incomplete | pending | approved).

Opciones disponibles:
incomplete,
pending,
approved
Ejemplo:

"incomplete"

​
createdAt
string
requerido

ISO 8601 formatted customer creation timestamp

Ejemplo:

"2026-03-09T20:46:31.305Z"

​
updatedAt
string
requerido

ISO 8601 formatted customer update timestamp

Ejemplo:

"2026-03-09T20:46:31.305Z"

​
type
enum<string>
requerido

Customer type

Opciones disponibles:
individual
Ejemplo:

"individual"

​
email
string

Customer email address

Ejemplo:

"jane.smith@example.com"

​
phone
string

Customer phone number

Ejemplo:

"+14155550123"

​
meta
object
​
firstName
string

Customer first name (individual customers only)

Ejemplo:

"Jane"

​
lastName
string

Customer last name (individual customers only)

Ejemplo:

"Smith"

​
dateOfBirth
string

The customer's date of birth in YYYY-MM-DD format (individual customers only).

Ejemplo:

"1990-01-15"

​
personalInformation
object

Personal information for an individual customer, echoed back from the most recent submission. The tax identification number is omitted from responses for privacy.

Última modificación el 22 de junio de 2026