Customers

A customer object ties together payments, saved payment methods, and subscriptions for one buyer — across every connector.

Why it matters in an orchestrated setup

Processors each have their own customer/token concept. SpicePay maintains the canonical customer record and maps it to per-processor tokens behind the scenes:

• Your support team sees one payment history per customer, regardless of which processor handled each payment.
• Saved payment methods stay usable even when you add or replace connectors — the vault, not the processor, is the source of truth.

Creating customers

You rarely need to create customers explicitly: pass customer_id (to reuse an existing record) or a customer object with name, email, phone on the payment create call and SpicePay creates or reuses the customer automatically.

To manage records directly, the customers API is there too:

curl https://api.spicepay.net/customers \
  -H "api-key: prd_****************" \
  -H "Content-Type: application/json" \
  -d @body.json

{
  "email": "ada@example.com",
  "name": "Ada Lovelace"
}

Saved payment methods

Pass setup_future_usage: "off_session" (for merchant-initiated charges like subscriptions) or "on_session" (for one-click checkout) when creating a payment, with customer consent — hosted checkout collects this for you. The method appears on the customer record and can be used for:

• One-click checkout — returning customers see their saved methods.
• Merchant-initiated transactions — subscriptions and usage-based charges.

Card details are stored in SpicePay's PCI-DSS Level 1 vault; your systems only ever see tokens.

In the Control Center

Customers lists every record with lifetime value and payment count. The detail page shows the full payment history, active subscriptions, saved methods (last4 and expiry only), and a timeline of disputes and refunds — useful for support teams answering "what happened with this customer's order".