SafePays API

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/customer

Request Body

FieldTypeRequiredDescription
api_keystringYesYour API key for authentication
namestringYesCustomer's full name
emailstringYesCustomer's email address (must be valid format)
groupstringNoCustomer group/segment for organization
preferred_currencystringNoPreferred currency code (default: USD)
address_line1stringNoStreet address
address_line2stringNoApartment, suite, etc.
citystringNoCity
statestringNoState/Province
zipstringNoZIP/Postal code
countrystringNoCountry

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_here

Path Parameters

ParameterTypeRequiredDescription
customer_idstringYesThe unique customer ID (UUID)

Query Parameters

ParameterTypeRequiredDescription
api_keystringYesYour 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

FieldTypeDescription
customerobjectCustomer profile information
customer_urlstringDirect URL to view customer in dashboard
paid_invoicesarrayList of all paid invoices (newest first)
total_paid_countintegerTotal number of paid invoices
total_paid_amountobjectTotal 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

  1. Creation: Customer profile created with basic information
  2. Invoice Association: Customer ID used when creating invoices
  3. Payment Tracking: All paid invoices linked to customer
  4. Analytics: View payment history and total revenue per customer

On this page