Server Integration

Render the button and capture the token

Initialise the SDK in manual mode, which suppresses submission and hands you the token — and, for Apple Pay, makes the merchant validation yours to route:

<CrissCrossWallets sessionId={sessionId} mode="manual">
  <ApplePayButton
    // Apple Pay only. Return the merchantSession from step 2, unaltered.
    onValidateMerchant={({ validationUrl }) =>
      fetch('/api/wallet-merchant-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ validationUrl }),
      }).then((response) => response.json())
    }
    onToken={({ provider, token, deviceFingerprint }) =>
      postToYourServer({ provider, token, deviceFingerprint })
    }
  />
  <GooglePayButton
    // No onValidateMerchant — Google Pay has no merchant validation step.
    onToken={({ provider, token, deviceFingerprint }) =>
      postToYourServer({ provider, token, deviceFingerprint })
    }
  />
</CrissCrossWallets>

onValidateMerchant must resolve with the merchantSession object exactly as CrissCross returned it — the wallet sheet will not release a token until it does. Step 2 covers the endpoint behind /api/wallet-merchant-session.

token is already base64-encoded and safe to transport as a string. deviceFingerprint is required for fraud screening — pass it through unaltered.

Validate the merchant session (Apple Pay only)

Apple requires a server-side merchant validation before the wallet sheet will release a token. In manual mode this is yours to make.

onValidateMerchant gives you a validationUrl. Forward it to CrissCross from your server — never from the browser, since this call uses your OAuth credentials:

curl -X POST https://api.crisscross.money/v1/payment/wallet/merchant-session \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
  "sessionId": "01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70",
  "provider": "apple-pay",
  "validationUrl": "https://apple-pay-gateway.apple.com/paymentservices/paymentSession"
}'

Response:

{
  "merchantSession": { }
}

Return merchantSession to the browser unaltered, as JSON. Do not re-serialise its fields, reorder them, or log it — Apple validates it as an opaque whole and it is short-lived.

Note what you do not send: no merchant identifier, no domain, no certificate. CrissCross resolves all of it from sessionId. Google Pay has no equivalent step.

Pass validationUrl through exactly as the wallet issued it. CrissCross accepts it only if it is an HTTPS URL on an Apple Pay validation host and rejects anything else with 422, so a rewritten or constructed URL will fail rather than be requested.

Submit the payment

curl -X POST https://api.crisscross.money/v1/payment \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
  "paymentMethodId": "digitalwallet",
  "sessionId": "01951c8a-7c3d-7e1f-9d4a-2b3c4d5e6f70",
  "paymentDetails": {
    "type": "digitalwallet",
    "provider": "apple-pay",
    "encryptedWalletToken": "eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoi...",
    "deviceFingerprint": "eyJmcCI6IjhkM2YxZTJhOWM0YjdkNmU...",
    "payerEmail": "[email protected]"
  }
}'

Handle the response

{
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
  "status": "SUCCESSFUL",
  "message": "Payment authorised"
}

A payment needing 3-D Secure returns PENDING with an authState:

{
  "transactionId": "9f3e4b2c-1a6d-4e88-9d3a-ff1234567890",
  "status": "PENDING",
  "message": "Authorization required",
  "authState": {
    "type": "redirect",
    "redirectUrl": "https://secure.crisscross.money/3ds/9f3e4b2c"
  }
}

Send the customer to redirectUrl. They return to the session’s redirectUrl when the challenge resolves. Most wallet payments are exempt from 3-D Secure, because the device authentication already satisfies strong customer authentication — so treat this as a path you must support, not the common case.

Confirm on the webhook

The webhook is the authoritative outcome. Match it on sessionId or merchantReference, verify its signature, and only then fulfil. See Webhook Events.