Customers API

Customers

POST /customers

Create a customer.

Field	Type	Required	Description
`email`	string	yes	Customer email address
`name`	string	no	Full name
`phone`	string	no	E.164 format
`currency`	string	no	Default currency (ISO 4217)
`metadata`	object	no

curl https://api.xtopay.co/v1/customers \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ama@example.com", "name": "Ama Owusu" }'

Response 201

{
  "id": "cus_a1b2c3",
  "email": "ama@example.com",
  "name": "Ama Owusu",
  "phone": null,
  "currency": "GHS",
  "created_at": "2026-05-24T10:00:00Z"
}

GET /customers/:id

Retrieve a customer with their subscriptions and payment methods.

PATCH /customers/:id

Update customer fields. Any field except id can be updated.

DELETE /customers/:id

Delete a customer. Cancels all active subscriptions immediately.

GET /customers

List customers.

Parameter	Description
`email`	Search by exact email
`limit`	1–100, default 20
`after`	Cursor for next page

Payment Methods

POST /setup-intents

Create a setup intent to securely collect and save a payment method.

curl https://api.xtopay.co/v1/setup-intents \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cus_a1b2c3" }'

Response

{
  "id": "si_a1b2c3",
  "customer_id": "cus_a1b2c3",
  "setup_url": "https://checkout.xtopay.co/setup/tok_xyz",
  "expires_at": "2026-05-24T10:30:00Z"
}

GET /payment-methods/:id

Retrieve a saved payment method.

GET /payment-methods

List payment methods for a customer.

curl "https://api.xtopay.co/v1/payment-methods?customer_id=cus_a1b2c3" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

DELETE /payment-methods/:id

Detach a payment method from the customer.

Customer Portal

POST /customer-portal/sessions

Create a portal session.

Field	Type	Required	Description
`customer_id`	string	yes
`return_url`	string	yes	URL to return to after portal visit

Response

{
  "id": "cps_a1b2c3",
  "url": "https://billing.xtopay.co/portal/sess_xyz",
  "expires_at": "2026-05-24T10:30:00Z"
}

On this page