Apple Pay and Google Pay Top-Up
Embed the Wirex-hosted Apple Pay and Google Pay checkout for a top-up your backend priced, in token or legacy mode.
Before You Start
Read the following guides before proceeding:
| Guide | Why |
|---|---|
| Web SDK | Isolation model and package map |
| SDK Setup | Client id (partner id), environments, installation, CSP |
| Top-Up Transfer | Estimate, execute and the restricted top-up token |
| Environments | The topup block of the configuration endpoint |
Overview
@wirexapp/card-wallet-topup-web renders a Wirex-served checkout for a top-up your backend has already
priced: a review screen with the quote and the Apple Pay or Google Pay button. The checkout runs under
Wirex's merchant identity. You register nothing with Apple or Google — no merchant account, no
certificates, no domain-association files, no payment-sheet code.
A wallet top-up requires the WalletTopup capability — separate from CardTopup. Check it with
GET /api/v2/user before offering a wallet button.
There is no 3DS step on this path: three_ds_state is never present on a wallet top-up.
npm install @wirexapp/card-wallet-topup-web| Input | What it is | Source |
|---|---|---|
quote | Estimation id, amounts and expiry the checkout renders and binds the sheet to | POST /api/v1/cards/topup/estimate with payment_method: apple_pay or google_pay |
walletConfig | The provider's wallet block, passed verbatim | topup.providers[<estimate.provider>] from GET /api/v1/config |
provider | The estimate's provider name | provider from the estimate response. Required for the desktop Google Pay QR |
auth.checkoutToken | Restricted top-up token — token mode only | access_token from POST /api/v1/cards/topup/token |
Trap: pass
walletConfigexactly as received — do not re-case keys, remap fields or add defaults.
The frame copies these values into the Apple and Google payment requests unchanged. An absentapple_pay
orgoogle_paykey means that wallet is not offered by the provider; it is not an error.
Choose a Mode
| Token mode | Legacy mode | |
|---|---|---|
| Who executes | The checkout frame calls POST /api/v1/cards/topup/execute itself | Your application calls execute with the sheet's token |
| Config | auth: { checkoutToken } | No auth |
| Result callback | onExecuted / onExecuteFailed | onToken |
| Wallet payment token | Never leaves the frame | Delivered to your page in onToken |
| Google Pay on desktop | QR handoff to an Android phone | Not available |
| Android Custom Tabs launch | Supported | Not supported |
Use token mode. It keeps the encrypted wallet payload out of your application entirely and is the only
mode that works where no page exists to hand a token back to (the desktop QR, a Custom Tabs launch).
In both modes a successful sheet means tokenized, never money moved. The execute response and your
status feed own the top-up outcome.
Step 1: Check Availability
Call checkWalletAvailability() once per page session, before showing any wallet button or row. Pass the
default provider block — no quote exists yet.
import { checkWalletAvailability } from '@wirexapp/card-wallet-topup-web';
const sdk = { environment: 'uat', clientId: 'a4f6c1e2-9b03-4d77-8a51-2f0c6b8e4d19' };
const availability = await checkWalletAvailability(sdk, {
config: topupConfig.providers[topupConfig.default_provider],
});
// { applePay, googlePay, googlePayHandoff?, googlePayState? }| Option | Type | Description |
|---|---|---|
config | object | Provider block. When present, its Google Pay values (auth methods, networks) drive the readiness check verbatim |
force | boolean | Bypass the per-session cache and probe again |
cache | Storage-like | null | Persistent cache of the last real answer. Default window.localStorage; any { getItem, setItem } adapter works (sessionStorage as-is); null disables persistence |
The result is cached per page session. With the default persistent cache, a fresh page load resolves
instantly from the last real answer while a live probe refreshes it; a failed probe never overwrites it.
| Field | Type | Description |
|---|---|---|
applePay | boolean | Apple Pay can pay here. false — hide the Apple Pay entry |
googlePay | boolean | Google Pay can tokenize here |
googlePayHandoff | boolean | Google Pay cannot tokenize here, but the desktop QR can finish it. Token mode only |
googlePayState | enum | Summary of Google Pay for this context — see below |
googlePayState | Meaning | Suggested UI |
|---|---|---|
ready | Google Pay can pay here (googlePay: true) | Show the entry; open the checkout |
handoff | Desktop: no native Google Pay, the phone QR can finish it | Token mode only — see Google Pay on Desktop |
needs_card | Android, Google Pay works, but no card in Google Wallet on this phone qualifies | Optionally show the entry and send the user to Google Wallet; re-check with force: true when they return |
unavailable | Google Pay cannot be used here | Hide the entry |
googlePay: falseoutside Android Chrome or an Android WebView is expected. The checkout requests
cryptogram cards only (CRYPTOGRAM_3DS), and desktop browsers have none. On Android, a card must be in
Google Wallet on that phone — a card saved only to the Google account does not qualify.
needs_cardis never reported when the provider block passed inconfighas nogoogle_paykey.
Show a Google Pay entry when availability.googlePay || availability.googlePayHandoff in token mode, and
when availability.googlePay in legacy mode.
Step 2: Price the Top-Up
Your backend calls the estimate endpoint with a wallet payment_method and no card id. Full request and
response documentation is in Top-Up Transfer.
const estimate = await fetch(`${baseUrl}/api/v1/cards/topup/estimate`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'X-User-Wallet': userEoaAddress,
'X-Chain-Id': chainId,
'Content-Type': 'application/json'
},
body: JSON.stringify({
payment_method: 'apple_pay',
destination_amount: '100000000',
destination_token_address: destinationTokenAddress
})
}).then(response => response.json());Build the quote from the estimate response:
const quote = {
estimationId: estimate.estimation_id,
sourceAmount: { amount: estimate.source_amount, currency: estimate.source_currency },
destinationAmount: { amount: estimate.destination_amount, currency: estimate.destination_token_symbol },
fee: { amount: estimate.fee_amount, currency: estimate.fee_currency },
expiresAtMs: estimate.expires_at * 1000,
};
const walletConfig = topupConfig.providers[estimate.provider];| Quote field | Required | Source | Description |
|---|---|---|---|
estimationId | Yes | estimation_id | Binds the sheet to the priced estimation |
sourceAmount | Yes | source_amount, source_currency | The fiat amount the sheet charges |
destinationAmount | No | destination_amount, destination_token_symbol | The "Top up" row |
fee | No | fee_amount, fee_currency | The fee row |
rate | No | Your own formatting of rate | Display-only rate line |
expiresAtMs | No | expires_at × 1000 | Drives the countdown and disables the button at expiry |
Amounts are display values (10.30 EUR), not base units. The backend re-validates the estimation on
execute; the sheet display is presentation, the estimation is the priced truth.
Trap:
expires_atis Unix seconds;expiresAtMsis milliseconds. Passing seconds expires the
quote immediately.
Step 3: Mint a Checkout Token (Token Mode)
Your backend exchanges the user token for a restricted top-up token, accepted only by the top-up estimate
and execute endpoints. See Restricted Top-Up Token.
const { access_token: checkoutToken } = await fetch(`${baseUrl}/api/v1/cards/topup/token`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'X-User-Wallet': userEoaAddress,
'X-Chain-Id': chainId
}
}).then(response => response.json());- Mint one token per checkout, right before mounting or arming, and a fresh one with every re-estimate.
- The field in the response is
access_token. - Never pass the user's full session token as
checkoutToken. Pass only the restricted token.
Skip this step in legacy mode.
Step 4: Mount the Checkout
import { createWalletTopUpForm } from '@wirexapp/card-wallet-topup-web';
const checkout = createWalletTopUpForm(sdk, {
quote,
walletConfig,
provider: estimate.provider,
auth: { checkoutToken },
applePayHandoff: 'popup',
onExecuted: ({ id, status }) => showResult(id, status),
onExecuteFailed: ({ reason, status, message }) => showError(reason),
onCancel: () => {},
onAttemptFailed: reason => showError(reason),
onEstimationExpired: async () => {
const fresh = await yourBackend.reEstimate();
const token = await yourBackend.mintTopUpToken();
await checkout.update(fresh.quote, fresh.walletConfig, { checkoutToken: token });
},
});
await checkout.mount(document.querySelector('#wallet-checkout'));
// When the view closes:
checkout.destroy();mount() resolves when the frame has rendered the quote. The container needs no fixed height — the frame
reports its own.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
quote | object | Yes | See Step 2 |
walletConfig | object | Yes | Provider block, verbatim |
auth.checkoutToken | string | Conditional | Restricted top-up token. Present — token mode; absent — legacy mode |
provider | string | Conditional | The estimate's provider name. Required for the desktop Google Pay QR |
googlePayHandoff | qr | none | No | Token mode only. qr (default) shows the phone QR where Google Pay cannot tokenize; none hides Google Pay there |
applePayHandoff | inline | popup | No | Where the Apple Pay session runs — see Apple Pay and Your Domain. Default inline |
layout | full | compact | No | full (default) renders the review card; compact keeps only the total headline, the wallet button and the countdown, for hosts that render their own review UI |
appearance | object | No | Shared appearance tokens — see Branding and Appearance |
buttons | object | No | Apple and Google button presets |
branding | object | No | Logo slot, processing disclosure, privacy link |
strings | object | No | Translated labels |
onToken | (token) => void | Conditional | Legacy mode. Required when auth is absent |
onExecuted | (result) => void | No | Token mode. The frame executed the top-up |
onExecuteFailed | (error) => void | No | Token mode. The execute call failed |
onReady | () => void | No | Review screen rendered, buttons live |
onStateChange | (state) => void | No | Checkout state — see Events |
onCancel | () => void | No | The user dismissed the sheet. Nothing happened; the button stays usable |
onAttemptFailed | (reason) => void | No | The sheet opened but produced no token |
onEstimationExpired | () => void | No | The quote expired in view |
Events
| Callback | When | What to do |
|---|---|---|
onReady | Review screen rendered | Hide your spinner |
onStateChange(state) | loading → ready → sheet-open; token mode adds executing and handoff-pending | Drive your own chrome |
onCancel | Sheet dismissed | Show nothing |
onAttemptFailed(reason) | Sheet opened, no token (for example, a merchant-validation failure) | Show a retry message. reason is a stable slug for messaging and analytics |
onEstimationExpired | Quote expired while on screen | Re-estimate, mint a new token in token mode, call update() |
onExecuted(result) | Token mode: execute returned | Treat result.status like your card top-up flow's |
onExecuteFailed(error) | Token mode: execute failed | See the reason table below. The frame stays disabled until update() re-arms it |
onToken(token) | Legacy mode: sheet authorized | Execute on your side — see Legacy Mode |
onExecuted result:
| Field | Description |
|---|---|
id | Top-up transaction id |
status | The execute response's status (Completed, Pending, Failed, …). Reconcile through your status feed |
method | apple_pay or google_pay |
cardNetwork, panLast4, displayName | Display metadata for your confirmation UI |
onExecuteFailed reasons:
reason | HTTP status | Cause | Resolution |
|---|---|---|---|
execute_rejected | 4xx | Validation failure or rejected request | Show an error; re-estimate before retrying |
already_executed | 409 | A second execute on the same estimation | Reconcile by status — the first execute may have succeeded |
estimation_expired | 422 | The estimation expired before execute | Re-estimate, mint a new token, update() |
execute_unauthorized | 401 / 403 | The checkout token expired or has the wrong scope | Mint a new token, update() |
execute_failed | 5xx | Backend failure | Reconcile by status before offering a retry |
network_error | — | No response | Reconcile by status before offering a retry |
error.message is a sanitized backend message, safe for diagnostics and toasts.
Re-Arm After Expiry
update(quote, walletConfig?, auth?, provider?) re-renders the mounted checkout in place — no remount, the
user keeps the screen. In token mode pass a fresh auth with every new quote: the old token was minted for
the expired estimation.
Apple Pay and Your Domain
Apple binds its merchant session to the top-level page's domain, and only Wirex's frame domains are
registered with Apple. Two ways to run, neither requiring Apple work on your side:
| Mode | How | Trade-off |
|---|---|---|
Embedded iframe with applePayHandoff: 'popup' | Your page embeds the checkout. Its Apple Pay button opens a small popup on the Wirex frame domain, where the session runs; the result relays back automatically | One extra click |
Popup checkout — openWalletCheckoutPopup() | The whole checkout opens top-level in a popup on the frame domain | No iframe on your page |
Pass
applePayHandoff: 'popup'. The defaultinlineworks only when your embedding domain itself is
registered under Wirex's Apple merchant id, which requires a per-domain onboarding with Wirex. Without it
the Apple Pay sheet fails on the device.
Google Pay has no domain binding and runs inline in the iframe.
Popup Checkout
import { openWalletCheckoutPopup } from '@wirexapp/card-wallet-topup-web';
payButton.addEventListener('click', () => {
// window.open must run synchronously inside the click handler, or the
// browser's popup blocker refuses it. Open first, arm when the estimate resolves.
const popup = openWalletCheckoutPopup(sdk, {
onExecuted: ({ status }) => showResult(status),
onExecuteFailed: ({ reason }) => showError(reason),
onClose: () => {},
onMountError: error => showError(error.message),
});
Promise.all([yourBackend.estimate(), yourBackend.mintTopUpToken()]).then(
([{ quote, walletConfig, provider }, checkoutToken]) =>
popup.arm(quote, walletConfig, { checkoutToken }, provider),
);
});| Method | Description |
|---|---|
arm(quote, walletConfig, auth?, provider?) | First call initializes the checkout; later calls behave like update(). No-op after the popup closed |
update(quote, walletConfig?, auth?, provider?) | Re-arms with a fresh quote; the popup stays open |
close() | Closes the popup. Fires onClose when nothing was tokenized or executed |
The popup takes the same config as the embedded checkout minus quote and walletConfig, plus onClose
and onMountError. In token mode it closes itself after onExecuted.
Google Pay on Desktop
Desktop browsers cannot tokenize Google Pay. In token mode, where availability.googlePayHandoff is
true, the checkout shows a QR code in place of the Google Pay button. The code carries the checkout — the
top-up token, the quote and the provider name — so provider is required.
- The user scans the code with an Android phone.
- The same checkout opens top-level on the phone, runs the native Google Pay sheet and executes.
- The desktop checkout reports
onStateChange('handoff-pending')and never learns the outcome.
Reconcile on your own. After
handoff-pending, poll the estimation status or your balance and
activity feed, then close the checkout yourself.onExecuteddoes not fire for a payment completed on the
phone. Nothing is stored on the Wirex side between the two devices.
Pass googlePayHandoff: 'none' to hide Google Pay on desktop instead.
Legacy Mode: Execute Yourself
Without auth, the checkout tokenizes and returns. onToken delivers the sheet's payload and your
application calls execute.
const checkout = createWalletTopUpForm(sdk, {
quote,
walletConfig,
applePayHandoff: 'popup',
onToken: token => yourBackend.executeTopUp({
estimation_id: quote.estimationId,
wallet_payment_token: token.walletPaymentToken,
cardholder_name: token.cardholderName,
billing_address: token.billingDetails && {
country_code: token.billingDetails.countryCode,
state: token.billingDetails.state,
city: token.billingDetails.city,
postal_code: token.billingDetails.postalCode,
address_line1: token.billingDetails.addressLine1,
address_line2: token.billingDetails.addressLine2,
},
wallet_transaction_id: token.walletTransactionId,
}),
});| Token field | Execute field | Description |
|---|---|---|
walletPaymentToken | wallet_payment_token | Encrypted, gateway-bound payload. Relay verbatim; max 16384 characters |
cardholderName | cardholder_name | Present only when the provider block requests billing fields |
billingDetails | billing_address | Present only when the provider block requests billing fields (required_billing_contact_fields / billing_address_required) |
walletTransactionId | wallet_transaction_id | Apple's transaction identifier. Absent on Google Pay |
method | — | apple_pay or google_pay |
cardNetwork, panLast4, displayName | — | Display metadata |
- Never parse, reshape, log or persist
walletPaymentToken. cardholderNameandbillingDetailsare personal data. Pass them to execute; never log or persist them.- The token field names are camelCase; the execute body is snake_case. Map them as above.
Branding and Appearance
createWalletTopUpForm(sdk, {
// …
branding: {
logo: 'custom',
logoImage: 'data:image/png;base64,iVBORw0KGgo…',
processingDisclosure: { partnerName: 'Acme' },
privacyUrl: 'https://acme.example/privacy',
},
buttons: {
applePay: { style: 'black', type: 'top-up' },
googlePay: { color: 'black', type: 'pay' },
},
appearance: { variables: { surfaceColor: '#0E0E10', colorText: '#FFFFFF' } },
});| Option | Values | Description |
|---|---|---|
branding.logo | wirex (default), hidden, custom | The logo above the total |
branding.logoImage | data:image/… URI | Custom logo for logo: 'custom'. Remote URLs never load — the frame's CSP allows only data: images |
branding.processingDisclosure.partnerName | string | Renders "Wirex processes this payment on behalf of {partnerName}". Omit to hide the line |
branding.privacyUrl | https:// URL | The link behind the privacy line under the button. Anything else falls back to the Wirex privacy policy |
buttons.applePay.style | black, white, white-outline | Apple's presets |
buttons.applePay.type | plain, top-up, buy | Apple's presets |
buttons.googlePay.color | black, white | Google's presets |
buttons.googlePay.type | plain, pay, buy | Google's presets |
Custom button text is not possible: both wallets brand-control their buttons.
The checkout accepts the shared appearance tokens —
surfaceColor (page ground), colorBackground and colorBorder (summary card), borderRadius,
colorText, colorLabel, the font tokens and more. The loading skeleton is drawn from the same tokens. In
popup mode the appearance applies before the first arm(), so the pre-quote skeleton matches too.
Native Apps
| Platform | How |
|---|---|
| Your Android app | Google does not allow Google Pay in a WebView of a third-party package. Open the hosted checkout top-level in Chrome Custom Tabs. Token mode only |
| Your iOS app | WKWebView with Apple Pay enabled |
Prefer the native SDKs — React Native,
Flutter, iOS,
Android — which wrap these launches.
To build the Custom Tabs URL from JavaScript, use buildWalletLaunchUrl from @wirexapp/card-sdk-core:
import { buildWalletLaunchUrl } from '@wirexapp/card-sdk-core';
const url = buildWalletLaunchUrl(
'https://frames.wirexapp.com',
{
checkoutToken,
quote,
provider: estimate.provider,
returnUrl: 'https://app.example.com/wallet/return',
},
'a4f6c1e2-9b03-4d77-8a51-2f0c6b8e4d19',
);- The page runs the sheet, executes and shows its own result screen with a Return to the app button: your
returnUrlwithestimation_idandoutcome(completed,pending,failed,already_executed)
appended. Reconcile by estimation status on your backend — the link is a UX signal, not the result. returnUrlis anhttpsApp Link or Universal Link (verified by the OS for your package — preferred) or
your app's own scheme (com.partner.app:/wallet/return, which any installed app can claim).
javascript:,data:,blob:,file:,about:andhttp:are refused:buildWalletLaunchUrlthrows
aTypeError.- The opened URL stays in the browser history. The checkout token in it is short-lived and bound to the
top-up it was minted for — another reason to mint one per checkout.
Exports
| Export | Description |
|---|---|
checkWalletAvailability(sdk, options?) | Promise<{ applePay, googlePay, googlePayHandoff?, googlePayState? }> |
createWalletTopUpForm(sdk, config) | { mount(container), update(quote, walletConfig?, auth?, provider?), destroy() } |
openWalletCheckoutPopup(sdk, config) | { arm(quote, walletConfig, auth?, provider?), update(…), close() } |
React bindings — useWalletAvailability and WalletTopUpForm — ship in @wirexapp/card-react. See
React Bindings.
Updated 7 days ago

