Digital Wallets

Digital Wallets

Digital wallets let customers pay with a card they have already stored on their device, authorised with Face ID, Touch ID, a device passcode, or a screen lock. CrissCross supports Apple Pay and Google Pay on the hosted checkout, through the CrissCross React SDK, and through a direct server-to-server integration.

Introduction

A digital wallet payment is a card payment. The customer’s device releases a one-time, encrypted token that stands in for their card, and CrissCross processes it on the same acquiring rails as any other card transaction. The customer never types a card number, and you never handle one.

Because the wallet already holds the card and the billing details, wallets remove almost all of the checkout form. That makes them consistently the fastest way to pay on mobile, and the reason they convert well on phone-heavy traffic.

This guide explains how to enable Apple Pay and Google Pay, what CrissCross takes care of on your behalf, and what to expect in your reporting and webhooks.

Pre-requisites

Before accepting digital wallet payments through CrissCross, ensure you meet the following requirements:

• A CrissCross integration:
  You have integrated with CrissCross using the hosted checkout, the React SDK, or the server-to-server API.

• Payment method enabled:
  You have enabled Apple Pay and Google Pay in your CrissCross configuration through the CrissCross dashboard.

• Card payments enabled:
  Wallet payments settle on your card acquiring configuration, so Card must be enabled on your account.

• Registered payment domains:
  Required only if you render the wallet button on your own site — that is, the React SDK or a server-to-server integration. Apple requires every domain that presents an Apple Pay button to be verified. See Wallet Configuration. The hosted checkout needs none of this.

Ways to integrate Digital Wallets with CrissCross

1. CrissCross hosted checkout
   The simplest path, and the only one that needs no wallet-specific work at all:

   • CrissCross renders the Apple Pay or Google Pay button on the checkout page whenever the customer’s device and browser support it.
   • CrissCross performs the wallet merchant validation, decrypts the wallet token, and handles any 3-D Secure step.
   • Your integration is unchanged from any other hosted checkout payment: create a session, redirect to paymentLink, fulfil on the webhook.
   • No payment domains to register, because the button is presented on CrissCross’s own checkout domain.

2. CrissCross React SDK
   Render the wallet button inside your own checkout, on your own domain, while CrissCross keeps the wallet plumbing:

   • The SDK is initialised with a sessionId — the same identifier Secure Fields uses. CrissCross resolves every wallet identifier from it, so there is no publishable key to manage and no credential in your front-end bundle.
   • <ApplePayButton> and <GooglePayButton> render only where the device and browser can present them.
   • You register the domains that will host the button. See Wallet Configuration.
   • See React Integration.

3. Server-to-server integration
   For full control of the checkout, capture the wallet token yourself and submit it to the CrissCross API. You still use the SDK to render the button and obtain the token, because only the wallet can produce one. See Server Integration.

Retrieving available payment methods

Calling the GET /v1/payment/available-methods endpoint with a sessionId reports which payment methods are eligible for that session, and returns the configuration the React SDK needs.

Eligibility is not the same as what a shopper sees. The wallet buttons that actually render also depend on the customer’s device, browser and provisioned cards, which the server cannot know — so treat this response as the set of methods permitted for the session, not a rendering instruction. The SDK and the hosted checkout both narrow it further on the client.

Request:

curl -G https://api.crisscross.money/v1/payment/available-methods \
     -d sessionId={sessionId}

Response:

{
  "success": true,
  "availableMethods": [
    {
      "type": "apple-pay",
      "name": "Apple Pay",
      "requiredInput": [],
      "captureCredentialsExternally": true,
      "configuration": {
        "merchantName": "Example Store",
        "supportedNetworks": ["visa", "masterCard"],
        "countryCode": "ZA"
      }
    },
    {
      "type": "google-pay",
      "name": "Google Pay",
      "requiredInput": [],
      "captureCredentialsExternally": true,
      "configuration": {
        "merchantName": "Example Store",
        "supportedNetworks": ["VISA", "MASTERCARD"],
        "countryCode": "ZA"
      }
    },
    ...other methods...
  ]
}

In this response:

• Each wallet is listed under its own type — apple-pay or google-pay.
• requiredInput is empty. There are no fields to collect: the wallet supplies the card and the billing details.
• captureCredentialsExternally is true, meaning the payment credentials are captured by the wallet on the customer’s device rather than by a CrissCross form.

configuration carries what the wallet sheet needs to display and which networks to accept. The React SDK reads it for you — you do not need to pass any of it yourself.

A wallet only appears in this response when it is enabled on your account and the session’s currency and payer location are supported for it.

Creating a checkout session

Creating a session for a wallet payment is identical to any other hosted checkout session. You do not name the payment method — the hosted checkout decides what to present from your configuration and the session details.

curl -X POST https://api.crisscross.money/v1/checkout/session \
     -H "Content-Type: application/json" \
     -d '{
  "merchantId": "YOUR_MERCHANT_ID",
  "merchantReference": "ORDER67890",
  "amount": 20000,
  "currency": "ZAR",
  "integrationType": "hosted",
  "redirectUrl": "https://merchant.com/redirect",
  "payerDetails": {
    "emailAddress": "[email protected]",
    "location": "ZAF",
    "fullName": "Siyanda Mthembu",
    "phoneNumber": "0723456789"
  }
}'

Response:

{
  "sessionId": "01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70",
  "paymentLink": "https://checkout.payos.money/session/01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70?signature=kRe8vQZ2mXpL7nT4wYbHs1JdA0uCgFiO6ExNq3ZrPyM"
}

Handling the payment

On the hosted checkout, redirect the customer to paymentLink exactly as returned. From there:

1. The customer taps Apple Pay or Google Pay on the CrissCross checkout page.
2. The wallet sheet opens on their device. They pick a card and authorise with Face ID, Touch ID, a passcode, or a screen lock.
3. The device releases an encrypted, single-use payment token. CrissCross decrypts it and submits the payment to the acquirer.
4. If 3-D Secure is required, CrissCross handles the challenge on the checkout page. Most wallet payments are exempt, because the device authentication already satisfies the strong customer authentication requirement.
5. The customer returns to your redirectUrl with ?status=completed, ?status=failed or ?status=cancelled appended.
6. The webhook carries the authoritative outcome. Fulfil on the webhook, not on the redirect. See Webhook Events.

A customer who opens the wallet sheet and dismisses it without authorising stays on the checkout page and can choose another payment method. No transaction is created.

If you render the button yourself, steps 1 to 3 happen in your own page and the SDK hands you the outcome — see React Integration. The wallet interaction and the resulting transaction are otherwise identical.

Device and browser availability

Wallet buttons are conditional. CrissCross shows a wallet only when the customer’s device and browser can present it and the customer has at least one card provisioned:

Customers on an unsupported device see the rest of your enabled payment methods as normal. Design your checkout copy so that it does not promise a wallet that may not appear — for example, avoid “Pay with Apple Pay” as the only call to action on the page preceding checkout.

Reconciliation and reporting

A wallet payment reports as a card payment, because that is what settles:

• paymentMethodId is card on the transaction and in the webhook payload.
• The wallet used is identified separately on the transaction’s paymentInstrument, alongside the card brand and masked number of the underlying card.
• Settlement, fees and payout timing follow your card configuration. See Settlement Reporting.

If you group transactions by paymentMethodId for reporting, wallet payments will fall into your card totals. Read paymentInstrument if you need to separate them.

Refunds

Wallet payments refund exactly like card payments, through the same endpoint, with no wallet-specific fields:

• Full and partial refunds are both supported, up to the remaining refundable balance.
• Funds return to the underlying card in the customer’s wallet, not to the device or the wallet itself.
• The customer does not need the device that made the payment, and does not need to authorise the refund.

See Full and Partial Refunds for the request shape, refund states and notifications.

Supported regions / countries

Wallet availability is determined by three things together, not by country alone:

• Your account configuration — which wallets are enabled for you, and on which acquiring connection.
• The session’s collection currency — the currency the payer is actually charged in.
• The payer’s location — payerDetails.location on the session.

Digital wallet payments settle on CrissCross’s card acquiring, so a wallet can only be available where card acquiring is already live for you. Beyond that, do not infer availability from the country: the same country can be eligible on one account and not on another.

Always resolve availability at runtime by reading GET /v1/payment/available-methods for the session, as described above. That response is the authoritative answer for that session, and it is what the SDK and the hosted checkout use. Contact your CrissCross representative for the wallets, currencies and markets enabled on your account.

Supported workflows and services

The following table outlines the workflows and services supported when using digital wallet payments with CrissCross:

Wallet tokens are single-use and bound to the customer’s device, so they cannot be stored for later use or reused for merchant-initiated transactions. If you need to charge a customer again without them present, collect the card through Card instead.

Ensuring a seamless and secure payment experience

To optimise your integration and ensure customer satisfaction, consider the following best practices:

• Let the wallet lead on mobile:
  Where a wallet is available, it is almost always the fastest way for that customer to pay. CrissCross orders the checkout page to reflect this, so avoid overriding the presentation to bury it.

• Do not collect what the wallet already has:
  The wallet supplies the cardholder name and billing address. Asking for them again before checkout adds friction for no gain.

• Fulfil on the webhook:
  As with every hosted checkout payment, the redirect tells you the buyer came back; the webhook tells you the money moved.

• Monitor performance and reliability:
  Keep an eye on transaction success rates and processing times. CrissCross’s dashboard provides insights into each payment method’s performance, and wallet payments are broken out separately from keyed card payments.

Additional resources and next steps

• Wallet Configuration
  Registering payment domains and the identifiers CrissCross resolves on your behalf.

• React Integration
  Rendering the wallet button in your own checkout with @crisscross/wallets.

• Server Integration
  Submitting a wallet token to the CrissCross API yourself.

• Hosted Checkout
  The full integration guide for creating sessions, redirecting buyers, and handling returns and webhooks.

• Card
  Card payments, including the tokenisation and merchant-initiated flows that wallets do not support.

• Full and Partial Refunds
  How to refund a wallet payment.

• CrissCross API documentation
  The endpoint reference for sessions, transactions and refunds.