Before diving into the Getting Started integration guide, it's important to understand the core concepts and data model behind Express Checkout (XCO).
XCO User
An XCO User is a cross-merchant customer identity managed by Purse. It represents a single customer who can interact with multiple merchants through Express Checkout.
An XCO User profile contains:
| Field | Description |
|---|
email | Customer email address (required, minimum identifier) |
phone_number | Customer phone number |
first_name / last_name | Customer identity |
gender | male, female, or other |
birthdate | Date of birth (ISO 8601 YYYY-MM-DD) |
addresses | Array of billing and/or delivery addresses |
An XCO User exists independently of any single merchant. The same customer can be linked to multiple merchants, each through its own consent. This enables a seamless checkout experience across the Purse ecosystem.
New vs. Existing User
When a customer arrives at your signup flow, two scenarios apply:
- New user (
exists: false) — No XCO account exists yet. You create one alongside the customer account in your system.
- Existing user (
exists: true) — The customer already has an XCO account (possibly created through another merchant). You link it via passwordless authentication.
Merchant Consent
A consent is the link between a merchant and an XCO User. It represents the customer's explicit agreement to share their XCO data (profile and payment tokens) with a specific merchant.
How Consent Is Created
Consent creation depends on whether the XCO user already exists:
| Scenario | How consent is created |
|---|
| New user | Consent is created automatically when you call POST /v1/merchants/{merchantId}/users with the customer data. |
| Existing user | Consent is created explicitly via POST /v1/merchants/{merchantId}/users/{customerReference}/consents after successful passwordless verification. |
Without an active consent, a merchant cannot access the customer's XCO data or payment tokens. Consent must be obtained before any Express Checkout payment flow can take place.
What Consent Enables
Once a consent is established, the merchant can:
- Retrieve the customer's XCO profile via
GET /v1/merchants/{merchantId}/users/{customer_reference}
- Access the customer's saved payment tokens for Express Checkout payments
- Pre-fill checkout forms with the customer's stored address and identity data
Customer Reference
The customer reference (customer_reference) is your own identifier for the customer in your system. It serves as the bridge between your internal customer record and the XCO User.
The customer_reference must be unique per merchant. It is used as a path parameter in all subsequent API calls (e.g., retrieving user data, creating consents).
Where It's Used
| API Endpoint | Role of customer_reference |
|---|
POST /v1/merchants/{merchantId}/users | Sent in the request body to link the new XCO account |
POST /v1/merchants/{merchantId}/users/{customerReference}/consents | Path parameter to identify which customer to link |
GET /v1/merchants/{merchantId}/users/{customer_reference} | Path parameter to retrieve the customer's XCO profile |
Passwordless Authentication (OTP)
When a customer already has an XCO account, their identity must be verified before a consent can be created. Express Checkout uses a passwordless OTP (One-Time Password) flow for this purpose.
Flow Overview
Three Sub-Steps
| Step | Endpoint | Purpose |
|---|
| Start | POST /v1/merchants/{merchantId}/users/passwordless/start | Sends an OTP to the customer's email or phone |
| Verify | POST /v1/merchants/{merchantId}/users/passwordless/verify | Validates the OTP and returns a consent_challenge_id along with the customer's XCO profile |
| Consent | POST /v1/merchants/{merchantId}/users/{customerReference}/consents | Finalizes the link using the consent_challenge_id |
The consent_challenge_id is a short-lived token returned after successful OTP verification. It must be used promptly to create the consent — it cannot be reused or stored for later.
Rate Limiting & caller_id
All passwordless endpoints accept an optional caller_id parameter (e.g., the customer's browser IP address). Without it, rate limiting is applied solely based on your clientId, which may block legitimate requests in production.
→ See Rate Limiting for details.
Payment Tokens
Payment tokens are saved payment instruments (e.g., credit cards) linked to an XCO User. They enable returning customers to pay without re-entering card details.
Token Count
When checking if an XCO user exists (GET /v1/users/exists), the response includes a token_count field:
token_count | Meaning |
|---|
0 | The user has no saved payment methods |
≥ 1 | The user has one or more saved payment instruments available for Express Checkout |
Payment tokens belong to the XCO User, not to a specific merchant. Once a customer grants consent, the merchant can access the customer's saved tokens for a streamlined checkout experience.
Token Lifecycle
- Creation — A token is created when a customer saves a payment method during a checkout flow with any consenting merchant.
- Reuse — The token can be reused across all merchants that hold an active consent with the customer.
- Deletion — The customer can remove tokens through wallet management interfaces.
Summary
| Concept | Description |
|---|
| XCO User | A cross-merchant customer identity managed by Purse |
| Consent | A merchant-specific link granting access to an XCO User's data and tokens |
| Customer Reference | Your internal customer ID, used to bridge your system with the XCO User |
| Passwordless OTP | Identity verification flow for linking existing XCO accounts |
| Payment Tokens | Saved payment instruments reusable across consenting merchants |
Next Steps