Customers

The customer object lets you create a reusable identity before you create payments, save payment methods, or issue refunds.

Create a Customer

POST /customers

GET //sandbox.perfectpay.ai/customers

curl https://sandbox.perfectpay.ai/customers \
  -X POST \
  -H "api-key: YOUR_SECRET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "5555550100",
    "phone_country_code": "+1",
    "metadata": {
      "segment": "beta"
    }
  }'

Response excerpt:

JSON

{
  "customer_id": "cus_abc123",
  "name": "Jane Doe",
  "email": "[email protected]",
  "created_at": "2026-03-22T14:35:42Z"
}

Retrieve a Customer

GET /customers/{customer_id}

GET //sandbox.perfectpay.ai/customers/cus_abc123

curl https://sandbox.perfectpay.ai/customers/cus_abc123 \
  -H "api-key: YOUR_SECRET_API_KEY"

List Customers

GET /customers/list

GET //sandbox.perfectpay.ai/customers/list

curl https://sandbox.perfectpay.ai/customers/list \
  -H "api-key: YOUR_SECRET_API_KEY"

Delete a Customer

DELETE /customers/{customer_id}

GET //sandbox.perfectpay.ai/customers/cus_abc123

curl https://sandbox.perfectpay.ai/customers/cus_abc123 \
  -X DELETE \
  -H "api-key: YOUR_SECRET_API_KEY"

List Customer Payment Methods

GET /customers/{customer_id}/payment_methods

GET //sandbox.perfectpay.ai/customers/cus_abc123/payment_methods

curl https://sandbox.perfectpay.ai/customers/cus_abc123/payment_methods \
  -H "api-key: YOUR_SECRET_API_KEY"

This returns all saved payment methods tied to the customer.

When To Create Customers First

Create the customer up front when you need any of the following:

saved payment methods
repeat purchases
wallet reuse across future checkouts
customer-scoped refund and event reporting
subscription billing