Payer ID

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.

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, Secure Fields, or Direct API.

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:

1
{
2
  "sessionId": "0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
3
  "paymentLink": "https://crisscross.money/checkout/0d3f1d6c-1c49-4b89-9db6-1fdc06f24c8a",
4
  "payerId": "2a1c4f1a-0d44-4f16-8c8e-9a3b4c5d6e7f",
5
  "signature": "hmac-signature"
6
}

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 to list and manage them.
• Fraud screening. The Payer ID is one of the identifiers CrissCross evaluates and can block on. See 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:

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:

1
{
2
  "merchantId": "1b2a3d4c-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
3
  "merchantReference": "ORDER-2026-0187",
4
  "amount": 15000,
5
  "currency": "NGN",
6
  "integrationType": "hosted",
7
  "payerDetails": {
8
    "emailAddress": "[email protected]",
9
    "location": "NGA",
10
    "fullName": "Chinwe Okafor",
11
    "payerId": "2a1c4f1a-0d44-4f16-8c8e-9a3b4c5d6e7f"
12
  }
13
}

3. Look up a payer’s stored payment methods

Use the Payer ID with the Payers API 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 — where the Payer ID is returned in the session response
• Direct API Integration — server-to-server flow that also returns a Payer ID
• Payers API reference — manage payers and their stored payment methods
• Fraud Prevention — how the Payer ID is used in fraud screening