docs
IntegrateCheckout Session

Customer lifecycle

Decide who the customer is, what the form collects, and how XPay's customer record evolves across one-time payers and returning customers.

A CustomerAPI is XPay's record of someone who paid you. It carries their name, email, phone, address, and the lifetime spend tied to those identifiers. This page is about how that record gets created, prefilled, and re-used across the two integration scenarios you're likely to build: signed-in customers and guest checkouts.

The single rule that drives every decision below: name your signed-in users with your own user ID, as externalCustomerId, and leave guests to XPay. You never need to store XPay's cus_* IDs, and XPay recognizes returning guests on its own.

The two customer types

XPay tracks two kinds of Customer records.

TypeWhen it's createdUse
RegisteredYou named the customer with externalCustomerId or customerId, created them through the Customers API, or set customerCreation: "always" and the customer paid. The dashboard counts them as known customers.Your signed-in user paid. Name them by your own user ID on every session.
GuestAuto-created during a checkout when the session names no Customer and customerCreation is if_required (the default). XPay groups guests by email, phone, and card fingerprint so the same person is recognized across visits.A one-time payer or someone who hasn't signed in. Don't store the cus_*: XPay links the same guest across visits for you.

Both types appear in the dashboard. The guest's grouping fields (every email and phone they've used, every card they've paid with) build up automatically. The dashboard also surfaces "Related customers" so you can see when a guest record overlaps with a registered one.

Two patterns by merchant scenario

The shape of externalCustomerId, customerDetails, and customerCreation you send depends on what you know about the person paying.

Signed-in user

Send your own user ID as externalCustomerId, and what you know about them as customerDetails. The first time a customer submits checkout for that ID, XPay creates a registered Customer with it as its externalId. This happens before payment, so the Customer stays even if they don't finish paying. Every later session finds the same Customer, prefills the form from it, and updates it with the details you send. There's nothing to store on your side.

curl -X POST https://api.xpay.app/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "afterCompletion": { "type": "redirect", "redirect": { "url": "https://yourshop.example/order/{CHECKOUT_SESSION_ID}" } },
    "externalCustomerId": "u_42",
    "customerDetails": {
      "name": "Aya Hassan",
      "email": "aya@example.com",
      "phone": "+201234567890"
    },
    "lineItems": [ { "price": "price_test_xyz", "quantity": 1 } ]
  }'

To read the Customer later, call GET /customers/external/u_42. If you already store cus_* IDs, you can keep passing them as customerId instead; give those Customers an externalId with PATCH /customers/:id to switch over.

When checkout creates a registered Customer, from externalCustomerId or customerCreation: "always", you get customer.created. When a session changes one, through the details you send or customerUpdate, you get customer.updated. Guests send no customer webhooks; checkout.session.completed carries the guest.

Guest checkout

No signed-in user. Omit externalCustomerId and customerId, and leave customerCreation as the default (if_required). XPay creates or matches a guest record by email, phone, and card fingerprint. You don't need to track the cus_* on your side. The dashboard groups guests automatically.

curl -X POST https://api.xpay.app/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "afterCompletion": { "type": "redirect", "redirect": { "url": "https://yourshop.example/order/{CHECKOUT_SESSION_ID}" } },
    "lineItems": [ { "price": "price_test_xyz", "quantity": 1 } ]
  }'

The webhook that fires on success (checkout.session.completed) carries the Customer in data.object.customer.

externalCustomerId, customerId and customerDetails

These are the ways to identify the customer on a session.

FieldWhat it doesRequired type
externalCustomerIdYour own ID for the customer. Uses the Customer with this externalId, or creates one with it when the customer first submits checkout. The form prefills from that Customer.Registered
customerIdReferences an existing Customer (cus_*). The form prefills name, email, phone, billing address, and shipping from that record.Registered
customerDetailsInline contact and address data (name, email, phone, billingDetails.address, shipping). Prefills the form. With externalCustomerId, it also updates the Customer it finds.n/a

Send at most one of externalCustomerId and customerId. customerDetails works with externalCustomerId, but not with customerId. Sending none is fine: the form is blank and the customer fills it in.

customerId must point at a registered Customer. Passing a guest's cus_* is refused. Guests can't be named on a later session, and they can't have an externalId.

externalId is unique in your account: POST /customers or PATCH /customers/:id with an ID another Customer already has fails with resource_already_exists. Test and live mode keep separate Customers, so the same ID can exist in both.

Prefill rules

When the page renders, the form is pre-filled in priority order:

  1. customerDetails.{name, email, phone} if provided.
  2. The existing Customer's name, email, phone, address, shipping if customerId or externalCustomerId named one.
  3. Empty otherwise. The customer fills it in.

The email and phone fields are locked (read-only) when the session names an existing Customer and the record carries them. The customer can't change someone else's email or phone mid-checkout.

customerCreation

Controls when XPay creates a Customer record at payment time. Two values; default is if_required.

ValueWhat it does
if_requiredDefault. When the session names no Customer: if the customer fills in an email or phone, a guest Customer is created or matched; if they fill in neither, no Customer record is created.
alwaysA registered Customer is created from customerDetails at payment time, even if they only typed a name. Use this when you want a known account on file (returning visits, post-purchase emails).

customerCreation: "always" can't be combined with customerId or externalCustomerId. A session that names its Customer already says which one to use.

customerUpdate

When the session names a Customer (customerId or externalCustomerId), what the customer types into the form is not written back to that Customer by default. Set customerUpdate to opt-in per field. Each sub-flag is auto (write) or never (default, don't write).

{
  "customerId": "cus_test_AbC123",
  "customerUpdate": {
    "name": "auto", // overwrite customer.name with the form value
    "address": "auto", // overwrite customer.address with the billing address
    "shipping": "auto", // overwrite customer.shipping with the shipping address
  },
}

customerUpdate is only meaningful when the session names a Customer. Sending it without customerId or externalCustomerId is a validation error.

email and phone aren't in customerUpdate because they're locked at the form level when the existing customer carries them. They can only be backfilled when missing (see How XPay handles guest customers).

What the form collects

Four boolean toggles control which fields the hosted checkout form asks the customer to fill. All default to false.

ToggleWhat it asks forRequired at submit?
nameCollectionCustomer's full name.Yes when on.
phoneNumberCollectionCustomer's phone with country code.Yes when on. Submit fails with parameter_missing on customerDetails.phone if blank.
billingAddressCollectionCardholder name and full billing address (street, city, state).Yes when on. Submit fails on missing customerDetails.billingDetails.address.line1.
shippingAddressCollectionRecipient name and shipping address.Yes when on. Submit fails on missing customerDetails.shipping.address.line1.

Email is always asked for and always required. It's the receipt destination and the primary identifier for guest dedup.

The submit button label is set separately by submitType (pay / subscribe / book / donate).

Custom fields

Need to ask for a Tax ID, an order note, or a delivery preference? customFields is an array of up to 3 entries. Each one renders an input on the form and the customer's answer is returned back on the session response and the webhook payload.

Field typeInput renderedValidation
TEXTSingle-line text input.Optional minCharacters / maxCharacters via hasLimits + limitType.
NUMBERNumber-only input.Same character limits apply.
DROPDOWNSelect with merchant-defined dropdownOptions.At least 2 options required.
CHECKBOXSingle checkbox the customer ticks.No character limits.
{
  "customFields": [
    {
      "label": "Tax ID",
      "type": "TEXT",
      "isOptional": false,
      "hasLimits": true,
      "limitType": "BETWEEN",
      "minCharacters": 9,
      "maxCharacters": 15,
    },
    {
      "label": "Delivery preference",
      "type": "DROPDOWN",
      "dropdownOptions": [{ "label": "Leave at door" }, { "label": "Hand to recipient" }],
    },
  ],
}

Each field gets a stable key server-side (derived from label) so the answer comes back at the same key in the response payload. The collected value lives in the matching text / numeric / dropdown slot on each entry.

How XPay handles guest customers

The default checkout flow (no customerId, customerCreation: "if_required") creates a guest Customer the first time someone checks out. The same guest is matched on subsequent visits when any identifier overlaps. You don't write any code for this.

XPay matches by:

  • Email, case-insensitive and trimmed.
  • Phone, normalized (country code, 00 prefix converted to +).
  • Card fingerprint, captured after a successful charge. If a guest pays with a card that's been seen on another guest record, XPay merges the two records into one, with all their payments and spend.

What this gives you in the dashboard:

  • A guest's profile compounds every email, phone, and card they've used over time.
  • A guest's spend, refunds, and payment count are accurate even when they checked out three times with three slightly different forms.
  • The "Related customers" section on a registered customer's profile surfaces the guest records that share contact info with them, so you can connect the two.

Avoiding duplicate customer records

The biggest failure mode merchants hit: sending the customer's details on every order without saying who they are, so each order looks like a new person. The pattern below avoids that.

Name every signed-in user by your own ID

Set externalCustomerId to your user's ID on every session they pay through. Their first checkout creates their Customer, even if they don't finish paying; every later one reuses it, and the spend rolls up under the same record. You don't store anything.

const session = await fetch("https://api.xpay.app/checkout/sessions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.XPAY_SECRET_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    afterCompletion: { type: "redirect", redirect: { url: returnUrl } },
    externalCustomerId: user.id, // the same ID every time
    customerDetails: { name: user.name, email: user.email },
    lineItems: [...],
  }),
});

Read the Customer by the same ID

GET /customers/external/:externalId returns the Customer for your user. Webhooks carry the same externalId, so your handler knows which user paid without a lookup table.

Leave guests to XPay

If a user paid as a guest first (before signing up) and then created an account, send their user ID as externalCustomerId on every session they pay through while signed in. XPay recognizes returning guests on its own. When the guest and the registered customer share an email, phone or card, the dashboard's "Related customers" section shows the connection.

Use metadata for everything else

Set metadata on a session for anything else your system needs back, such as an order ID. It comes back on the webhook payload, on the session retrieve response, and on the Payment Intent.

The result: one XPay registered Customer per authenticated user, lifetime spend rolls up correctly, and guests are tracked separately without you having to manage them.

Where to next

On this page