Customers

Customers belong to the authenticated organization. The current public API supports customer create/list/read plus customer-scoped payment-method create and update.

Customer object

{
  "id": "cus_123",
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+2348012345678",
  "billing_address": {
    "line1": "1 Market Street",
    "city": "Lagos",
    "country": "NG"
  },
  "metadata": { "external_id": "user_123" },
  "created_at": "2026-06-17T10:30:00Z",
  "updated_at": "2026-06-17T10:30:00Z"
}

Create a customer

POST https://api.getpaidhq.com/api/customers

Body

email string required
first_name string
last_name string
phone string
billing_address object - first_name, last_name, email, phone, line1, line2, city, state, postal_code, country
metadata object - String key/value pairs

curl https://api.getpaidhq.com/api/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "metadata": { "external_id": "user_123" }
  }'

List customers

GET https://api.getpaidhq.com/api/customers

Query parameters are shared by list endpoints:

page integer - Default 0
limit integer - Default 10
sort_by string - Default created_at
sort_order string - Default desc

{
  "data": [
    {
      "id": "cus_123",
      "email": "customer@example.com",
      "first_name": "John",
      "last_name": "Doe"
    }
  ],
  "meta": { "total": 1, "page": 0, "limit": 10 }
}

Retrieve a customer

GET https://api.getpaidhq.com/api/customers/{id}

Add a payment method

POST https://api.getpaidhq.com/api/customers/{id}/payment-methods

The token is a reusable charge credential from your payment gateway. For Paystack, use an authorization_code from a successful charge. GetPaidHQ stores the token for future server-initiated charges and does not return it in API responses.

Body

psp string required - Paystack or CheckoutDotCom
name string required
type string required - For example, card
token string required
is_default boolean
billing_address object
details object
metadata object

curl https://api.getpaidhq.com/api/customers/cus_123/payment-methods \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "psp": "Paystack",
    "name": "Visa ending 4242",
    "type": "card",
    "token": "AUTH_pmx3upmp",
    "is_default": true
  }'

Response

{
  "id": "pm_123",
  "status": "active",
  "psp": "Paystack",
  "name": "Visa ending 4242",
  "customer_id": "cus_123",
  "type": "card",
  "details": null,
  "created_at": "2026-06-17T10:30:00Z",
  "updated_at": "2026-06-17T10:30:00Z"
}

Update a payment method

PUT https://api.getpaidhq.com/api/customers/{id}/payment-methods/{pmid}

Use this to update display details, metadata, the default flag, billing address, or the stored gateway token.

Not currently exposed

The current OpenAPI spec does not expose customer update/delete, customer search, customer balance, customer portal sessions, or customer-scoped payment-method list/delete endpoints.

Customers

On this page