Customers
API endpoints for customer management
Overview
The Customer endpoints allow you to create and manage customer profiles in your SafePays account. Customers can be associated with multiple invoices for easier tracking and reporting.
Create Customer
Create a new customer profile.
Endpoint
POST /api/customerRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
api_key | string | Yes | Your API key for authentication |
name | string | Yes | Customer's full name |
email | string | Yes | Customer's email address (must be valid format) |
group | string | No | Customer group/segment for organization |
preferred_currency | string | No | Preferred currency code (default: USD) |
address_line1 | string | No | Street address |
address_line2 | string | No | Apartment, suite, etc. |
city | string | No | City |
state | string | No | State/Province |
zip | string | No | ZIP/Postal code |
country | string | No | Country |
Example Request
curl -X POST https://app.safepays.com/api/customer \
-H "Content-Type: application/json" \
-d '{
"api_key": "your_api_key_here",
"name": "John Doe",
"email": "john.doe@example.com",
"group": "Premium Customers",
"preferred_currency": "USD",
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "New York",
"state": "NY",
"zip": "10001",
"country": "USA"
}'const response = await fetch('https://app.safepays.com/api/customer', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
api_key: 'your_api_key_here',
name: 'John Doe',
email: 'john.doe@example.com',
group: 'Premium Customers',
preferred_currency: 'USD',
address_line1: '123 Main Street',
address_line2: 'Apt 4B',
city: 'New York',
state: 'NY',
zip: '10001',
country: 'USA'
})
});
const result = await response.json();
console.log(result);import requests
import json
url = 'https://app.safepays.com/api/customer'
headers = {'Content-Type': 'application/json'}
data = {
'api_key': 'your_api_key_here',
'name': 'John Doe',
'email': 'john.doe@example.com',
'group': 'Premium Customers',
'preferred_currency': 'USD',
'address_line1': '123 Main Street',
'address_line2': 'Apt 4B',
'city': 'New York',
'state': 'NY',
'zip': '10001',
'country': 'USA'
}
response = requests.post(url, headers=headers, data=json.dumps(data))
result = response.json()
print(result)<?php
$data = [
'api_key' => 'your_api_key_here',
'name' => 'John Doe',
'email' => 'john.doe@example.com',
'group' => 'Premium Customers',
'preferred_currency' => 'USD',
'address_line1' => '123 Main Street',
'address_line2' => 'Apt 4B',
'city' => 'New York',
'state' => 'NY',
'zip' => '10001',
'country' => 'USA'
];
$ch = curl_init('https://app.safepays.com/api/customer');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
?>Success Response
Status Code: 201 Created
{
"status": "success",
"message": "Customer created successfully",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "John Doe",
"email": "john.doe@example.com",
"group": "Premium Customers",
"preferred_currency": "USD",
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "New York",
"state": "NY",
"zip": "10001",
"country": "USA",
"created_on": "2024-01-15 10:30:00"
}
}Error Responses
400 Bad Request - Missing required fields or invalid email format
{
"error": "name and email are required"
}401 Unauthorized - Invalid API key
{
"error": "Invalid API Key"
}409 Conflict - Customer with this email already exists
{
"error": "Customer with this email already exists"
}Email addresses are unique per account. If you need to create multiple customers with the same email, consider using email aliases or a customer grouping strategy.
Get Customer Details
Retrieve customer information along with all their paid invoices.
Endpoint
GET /api/customer/{customer_id}?api_key=your_api_key_herePath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
customer_id | string | Yes | The unique customer ID (UUID) |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
api_key | string | Yes | Your API key for authentication |
Example Request
curl -X GET "https://app.safepays.com/api/customer/550e8400-e29b-41d4-a716-446655440000?api_key=your_api_key_here"const customerId = '550e8400-e29b-41d4-a716-446655440000';
const apiKey = 'your_api_key_here';
const response = await fetch(
`https://app.safepays.com/api/customer/${customerId}?api_key=${apiKey}`
);
const result = await response.json();
console.log(result);import requests
customer_id = '550e8400-e29b-41d4-a716-446655440000'
api_key = 'your_api_key_here'
url = f'https://app.safepays.com/api/customer/{customer_id}?api_key={api_key}'
response = requests.get(url)
result = response.json()
print(result)<?php
$customer_id = '550e8400-e29b-41d4-a716-446655440000';
$api_key = 'your_api_key_here';
$url = "https://app.safepays.com/api/customer/{$customer_id}?api_key={$api_key}";
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
?>Success Response
Status Code: 200 OK
{
"status": "success",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "John Doe",
"email": "john.doe@example.com",
"group": "Premium Customers",
"preferred_currency": "USD",
"address_line1": "123 Main Street",
"address_line2": "Apt 4B",
"city": "New York",
"state": "NY",
"zip": "10001",
"country": "USA",
"created_on": "2024-01-10 10:30:00"
},
"customer_url": "https://app.safepays.com/dashboard/customer/550e8400-e29b-41d4-a716-446655440000",
"paid_invoices": [
{
"id": "660e8400-e29b-41d4-a716-446655440001",
"amount": 125.00,
"currency": "USD",
"email": "john.doe@example.com",
"provider": "card",
"status": "Paid",
"created_on": "15 Jan, 2024",
"paid_on": "15 Jan, 2024",
"payment_link": "https://app.safepays.com/pay/660e8400-e29b-41d4-a716-446655440001",
"items": [
{
"name": "Product A",
"qty": 2,
"price": 50.00
},
{
"name": "Product B",
"qty": 1,
"price": 25.00
}
],
"due_date": "2024-12-31",
"customer_id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"total_paid_count": 1,
"total_paid_amount": {
"USD": 125.00
}
}Response Fields
| Field | Type | Description |
|---|---|---|
customer | object | Customer profile information |
customer_url | string | Direct URL to view customer in dashboard |
paid_invoices | array | List of all paid invoices (newest first) |
total_paid_count | integer | Total number of paid invoices |
total_paid_amount | object | Total amounts by currency |
Error Responses
400 Bad Request - Missing API key
{
"error": "api_key parameter is required"
}401 Unauthorized - Invalid API key
{
"error": "Invalid API Key"
}404 Not Found - Customer not found
{
"error": "Customer not found"
}Best Practices
Customer Groups
Use customer groups to organize your customers:
- By subscription tier: "Free", "Premium", "Enterprise"
- By region: "US-East", "EU", "APAC"
- By industry: "Retail", "Technology", "Healthcare"
- By status: "Active", "Churned", "Trial"
Email Validation
The API validates email addresses using standard regex patterns. Common issues:
- Missing @ symbol
- Invalid domain format
- Special characters not allowed
Address Management
While address fields are optional, providing complete address information helps with:
- Tax calculations
- Fraud prevention
- Customer communication
- Regulatory compliance
Store the customer ID returned after creation. You'll need it for creating invoices and retrieving customer information.
Customer Lifecycle
- Creation: Customer profile created with basic information
- Invoice Association: Customer ID used when creating invoices
- Payment Tracking: All paid invoices linked to customer
- Analytics: View payment history and total revenue per customer
Related Resources
- Create Invoice - Use customer ID for invoicing
- Webhooks - Receive notifications for customer events