Customers

Customers represent the people or businesses you charge. You need a customer to save a card or create an invoice. For one-off payments via payment intents or checkout sessions, a customer is optional.

Creating a customer

API reference

The Idempotency-Key header lets you safely retry the request if it fails — see Idempotency.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/customers \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "full_name": "Jane Smith",
      "email": "[email protected]",
      "phone": "+447700900000"
    }
  }'

Response

{
  "name": "accounts/acct_YOUR_ACCOUNT/customers/cus_CUSTOMER_ID",
  "full_name": "Jane Smith",
  "email": "[email protected]",
  "phone": "+447700900000",
  "create_time": "2025-10-27T19:09:47Z",
  "update_time": "2025-10-27T19:09:47Z"
}

Retrieving a customer

API reference

curl https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/customers/cus_CUSTOMER_ID \
  -H "Authorization: Api-Key $API_KEY"

Listing customers

API reference

curl -X POST https://api.synaptopay.com/v1/accounts/acct_YOUR_ACCOUNT/customers:list \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Customer fields

Field	Description
`name`	Resource name (e.g. `accounts/acct_.../customers/cus_...`)
`full_name`	Customer's name or business name
`email`	Email address
`phone`	Phone number in E.164 format (e.g. `+447700900000`)
`address`	Billing postal address (shown on invoices)
`metadata`	Key-value pairs for your own use (max 50 keys, key max 40 chars, value max 500 chars)