curl -X POST "https://api-sandbox.paywithsoap.com/api/v1/customers" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "customer@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "5551234567",
"date_of_birth": "1990-01-01",
"internal_id": "3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b"
}'
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api-sandbox.paywithsoap.com/api/v1/customers')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
email: 'customer@example.com',
first_name: 'John',
last_name: 'Doe',
phone_number: '5551234567',
date_of_birth: '1990-01-01',
internal_id: '3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b'
}.to_json
response = http.request(request)
puts response.body
const axios = require('axios');
const createCustomer = async () => {
try {
const response = await axios.post('https://api-sandbox.paywithsoap.com/api/v1/customers', {
email: 'customer@example.com',
first_name: 'John',
last_name: 'Doe',
phone_number: '5551234567',
date_of_birth: '1990-01-01',
internal_id: '3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b'
}, {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
createCustomer();
import requests
import json
url = "https://api-sandbox.paywithsoap.com/api/v1/customers"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"email": "customer@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "5551234567",
"date_of_birth": "1990-01-01",
"internal_id": "3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
{
"id": "cus_A3GuXEbThpqk2t6UTxEuoceVJyUEAX7V",
"internal_id": "cust_123",
"email": "customer@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "1234567890",
"date_of_birth": "1990-01-01",
"created_at": "2025-03-10T16:08:14.427Z"
}
API Endpoints
Create Customer
Creates a new customer in the Soap system
POST
/
api
/
v1
/
customers
curl -X POST "https://api-sandbox.paywithsoap.com/api/v1/customers" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "customer@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "5551234567",
"date_of_birth": "1990-01-01",
"internal_id": "3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b"
}'
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api-sandbox.paywithsoap.com/api/v1/customers')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
email: 'customer@example.com',
first_name: 'John',
last_name: 'Doe',
phone_number: '5551234567',
date_of_birth: '1990-01-01',
internal_id: '3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b'
}.to_json
response = http.request(request)
puts response.body
const axios = require('axios');
const createCustomer = async () => {
try {
const response = await axios.post('https://api-sandbox.paywithsoap.com/api/v1/customers', {
email: 'customer@example.com',
first_name: 'John',
last_name: 'Doe',
phone_number: '5551234567',
date_of_birth: '1990-01-01',
internal_id: '3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b'
}, {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
createCustomer();
import requests
import json
url = "https://api-sandbox.paywithsoap.com/api/v1/customers"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"email": "customer@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "5551234567",
"date_of_birth": "1990-01-01",
"internal_id": "3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
{
"id": "cus_A3GuXEbThpqk2t6UTxEuoceVJyUEAX7V",
"internal_id": "cust_123",
"email": "customer@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "1234567890",
"date_of_birth": "1990-01-01",
"created_at": "2025-03-10T16:08:14.427Z"
}
Creates a new customer with the provided information. The customer can then be used for creating checkouts and other operations.
Every Soap API request is authenticated with a bearer token in the
Your API key is in the Soap Dashboard under the Developers section. It looks like
Authorization header:
Authorization: Bearer YOUR_API_KEY
key_....
Requests with a missing or invalid API key return 422 — never 401 — with a JSON error field, usually {"error": "API key not found."}. Branch on the status code rather than the message: GET /api/v1/device_pings/latest_geo_check does not yet return the same wording.
Never expose your API key in client-side code — it is server-side only.
Legal name. In production, when KYC is enabled for a checkout type, every checkout of that type with a verified identity checks that the verified identity’s name is consistent with the customer profile’s current
first_name and last_name. Use the customer’s legal first name and surname as shown on their ID, with no nicknames, middle names, initials or suffixes in those fields. A mismatch restricts the customer with reason code KYC_DOES_NOT_MATCH_PROFILE_NAME; fix the profile with Update Customer and lift the restriction in the dashboard.curl -X POST "https://api-sandbox.paywithsoap.com/api/v1/customers" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "customer@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "5551234567",
"date_of_birth": "1990-01-01",
"internal_id": "3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b"
}'
require 'net/http'
require 'uri'
require 'json'
uri = URI.parse('https://api-sandbox.paywithsoap.com/api/v1/customers')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri.path)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
email: 'customer@example.com',
first_name: 'John',
last_name: 'Doe',
phone_number: '5551234567',
date_of_birth: '1990-01-01',
internal_id: '3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b'
}.to_json
response = http.request(request)
puts response.body
const axios = require('axios');
const createCustomer = async () => {
try {
const response = await axios.post('https://api-sandbox.paywithsoap.com/api/v1/customers', {
email: 'customer@example.com',
first_name: 'John',
last_name: 'Doe',
phone_number: '5551234567',
date_of_birth: '1990-01-01',
internal_id: '3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b'
}, {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
console.log(response.data);
} catch (error) {
console.error(error);
}
};
createCustomer();
import requests
import json
url = "https://api-sandbox.paywithsoap.com/api/v1/customers"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
data = {
"email": "customer@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "5551234567",
"date_of_birth": "1990-01-01",
"internal_id": "3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b"
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
{
"id": "cus_A3GuXEbThpqk2t6UTxEuoceVJyUEAX7V",
"internal_id": "cust_123",
"email": "customer@example.com",
"first_name": "John",
"last_name": "Doe",
"phone_number": "1234567890",
"date_of_birth": "1990-01-01",
"created_at": "2025-03-10T16:08:14.427Z"
}
Authorizations
Bearer token authentication using your API key (key_...). Used for every endpoint except POST /api/v1/device_pings.
Body
application/json
The required list below reflects the default account configuration (email, first_name and last_name). Other accounts are configured to require first_name and last_name plus either email or phone_number, or email alone; if that is you, treat this schema's required list as advisory and ask Soap which rule applies. Unknown fields are rejected.
Email address of the customer. Required on the default configuration. Must be unique within your business.
Example:
"john@acme.com"
Customer's legal first name as shown on their ID, with no nicknames, middle names or initials. In production this is checked against the verified identity on KYC-enabled checkouts.
Minimum string length:
1Example:
"John"
Customer's legal surname as shown on their ID, with no suffixes. In production this is checked against the verified identity on KYC-enabled checkouts.
Minimum string length:
1Example:
"Doe"
10-digit US phone number with no country code, spaces or punctuation (for example 5551234567). Must be unique within your business.
Pattern:
^\d{10}$Example:
"8008001234"
Date of birth of the customer as YYYY-MM-DD.
Example:
"1990-01-01"
Your own identifier for the customer. A string or an integer; when present it must be unique within your business (creating a second customer with the same internal_id fails).
Example:
"3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b"
Response
Customer created.
Unique identifier for the customer to be used for future transactions.
Example:
"cus_pQsQ4kz3Af6Mb9rCupnWj6VFzxJsmkYK"
Your identifier for the customer, as supplied; null when none was given.
Example:
"3f1b8c4e-7c2e-4c2c-8d2f-179cf0efb36b"
Example:
"john@acme.com"
Null only on accounts configured to create customers without names.
Example:
"John"
Null only on accounts configured to create customers without names.
Example:
"Doe"
Example:
"8008001234"
Example:
"1990-01-01"
Example:
"2025-03-05T18:26:43.069Z"