Customers

Overview

A customer object represents one of your users in Xtopay. Customers are the anchor for payments, subscriptions, payment methods, invoices, and refund history. Creating a customer before a payment enables you to track full lifetime value and payment history.

Create a customer

const customer = await xtopay.customers.create({
  email: "ama@example.com",
  name: "Ama Owusu",
  phone: "+233244000000",
  metadata: {
    user_id: "usr_internal_abc123",
    plan: "pro",
  },
});

Customer object

{
  "id": "cus_a1b2c3",
  "email": "ama@example.com",
  "name": "Ama Owusu",
  "phone": "+233244000000",
  "currency": "GHS",
  "payment_methods": [...],
  "subscriptions": [...],
  "metadata": { "user_id": "usr_internal_abc123" },
  "created_at": "2026-01-15T09:00:00Z"
}

Update a customer

await xtopay.customers.update("cus_a1b2c3", {
  email: "ama.new@example.com",
  metadata: { plan: "enterprise" },
});

Payment methods

Save a customer's payment method for future charges without re-entering details:

// Create a setup intent to securely collect payment details
const setup = await xtopay.setupIntents.create({
  customer_id: "cus_a1b2c3",
});

// Frontend: redirect customer to setup.setup_url
// After completion, the payment method is attached to the customer

// List saved methods
const methods = await xtopay.paymentMethods.list({
  customer_id: "cus_a1b2c3",
});

Delete a customer

await xtopay.customers.delete("cus_a1b2c3");

Deleting a customer cancels all active subscriptions immediately and removes all saved payment methods. Historical payments and invoices are retained for 7 years for compliance.

Next steps

Customer Portal

Let customers self-serve their billing.