> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.crisscross.money/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server. # Payer ID > What a Payer ID is, when CrissCross returns it, what it represents, and how to store and reuse it to recognise returning customers. ## Overview A **Payer ID** is a stable identifier that CrissCross assigns to the person paying you — the *payer*. It is returned in your checkout responses and represents the customer behind a payment. Unlike a `sessionId` or `transactionId`, which each describe a **single** payment attempt and are discarded afterwards, a Payer ID is **durable**: the same payer keeps the same Payer ID across every session and transaction they make with you. That makes it the one identifier you can use to recognise a returning customer, link their payments together, and — over time — offer them a faster checkout. > **Payer ID format** > > A Payer ID is a UUID, for example `2a1c4f1a-0d44-4f16-8c8e-9a3b4c5d6e7f`. Treat it as an opaque string — don't parse it or assume anything about its structure. --- ## When it is returned A Payer ID is returned whenever you create or fetch a checkout session, regardless of which integration method you use — [Hosted Checkout](/hosted-checkout) or [Direct API](/direct-api-integration). | Where | Field | Notes | | --------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------- | | **Create checkout session** — `POST /v1/checkout/session` | `payerId` | Returned in the response body alongside `sessionId`. | | **Get checkout session** — `GET /v1/checkout/session` | `payerId` and `payerDetails.payerId` | Returned at the top level and echoed inside `payerDetails`. | CrissCross resolves the payer from the `payerDetails` you supply when you create the session (email address, name, phone number, location). The resulting Payer ID comes back in the response: ```json { "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a", "paymentLink": "https://checkout.crisscross.money/session/0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a?signature=kRe8vQZ2mXpL7nT4wYbHs1JdA0uCgFiO6ExNq3ZrPyM", "payerId": "2a1c4f1a-0d44-4f16-8c8e-9a3b4c5d6e7f", "signature": "kRe8vQZ2mXpL7nT4wYbHs1JdA0uCgFiO6ExNq3ZrPyM" } ``` --- ## What it represents The Payer ID identifies the **customer**, not the payment. One payer can have many sessions and many transactions; they all share the same Payer ID. Because of that, the Payer ID is what CrissCross uses to tie a person's activity together across your account: * **Stored payment methods.** Cards and other instruments a payer has saved are held against their Payer ID. See the [Payers API](/api-reference) to list and manage them. * **Fraud screening.** The Payer ID is one of the identifiers CrissCross evaluates and can block on. See [Fraud Prevention](/fraud-prevention). * **Returning-customer flows.** Because it's stable, you can use it to recognise a customer you've seen before and skip re-collecting their details. ### How it differs from other identifiers CrissCross returns several identifiers during a payment. They are easy to confuse, so it's worth being precise: | Identifier | Scope | Lifetime | Use it to… | | ------------------- | -------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- | | `payerId` | The customer (payer) | **Persistent** — reused across sessions and transactions | Recognise a returning customer; link their payments; retrieve stored methods | | `sessionId` | One checkout session | Single payment intent | Initiate and track one payment attempt | | `transactionId` | One transaction | Single payment attempt | Poll status; match webhooks; reconcile | | `merchantReference` | Your own order | Set by you | Reconcile against your order system | | `merchantId` | Your account | Permanent | Identify your account on every request | --- ## How to store and use it ### 1. Store it against your customer record When a session or transaction completes, persist the returned `payerId` against your own customer or user record. It is the handle you'll use for everything below, so keep it somewhere you can look it up by customer. The Payer ID is not a secret in the way an API key or `signature` is, but it is tied to an identifiable person — store and transmit it with the same care you apply to other customer data, and don't expose it to end users in URLs or client-side code unnecessarily. ### 2. Reuse it to link returning customers When the same customer comes back, pass their stored Payer ID into `payerDetails.payerId` on your next **create checkout session** call. This associates the new session with the existing payer instead of creating a fresh identity: ```json { "merchantId": "1b2a3d4c-5e6f-7a8b-9c0d-1e2f3a4b5c6d", "merchantReference": "ORDER-2026-0187", "amount": 15000, "currency": "NGN", "integrationType": "hosted", "payerDetails": { "emailAddress": "chinwe.okafor@example.com", "location": "NGA", "fullName": "Chinwe Okafor", "payerId": "2a1c4f1a-0d44-4f16-8c8e-9a3b4c5d6e7f" } } ``` > **Store, don't re-derive** > > Always reuse the Payer ID **you stored**. Don't rely on re-sending the same email or phone number to get the same Payer ID back — the returned `payerId` is the authoritative link to a payer, so persist it and pass it back explicitly. ### 3. Look up a payer's stored payment methods Use the Payer ID with the [Payers API](/api-reference) to retrieve the payment methods a customer has saved, so you can offer a returning customer their existing card or wallet instead of asking for details again. --- ## Related * [Hosted Checkout](/hosted-checkout) — where the Payer ID is returned in the session response * [Direct API Integration](/direct-api-integration) — server-to-server flow that also returns a Payer ID * [Payers API reference](/api-reference) — manage payers and their stored payment methods * [Fraud Prevention](/fraud-prevention) — how the Payer ID is used in fraud screening