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:

GuideWhy
Web SDKIsolation model and package map
SDK SetupClient id (partner id), environments, installation, CSP
Top-Up TransferEstimate, execute and the restricted top-up token
EnvironmentsThe 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
InputWhat it isSource
quoteEstimation id, amounts and expiry the checkout renders and binds the sheet toPOST /api/v1/cards/topup/estimate with payment_method: apple_pay or google_pay
walletConfigThe provider's wallet block, passed verbatimtopup.providers[<estimate.provider>] from GET /api/v1/config
providerThe estimate's provider nameprovider from the estimate response. Required for the desktop Google Pay QR
auth.checkoutTokenRestricted top-up token — token mode onlyaccess_token from POST /api/v1/cards/topup/token

Trap: pass walletConfig exactly 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 absent apple_pay
or google_pay key means that wallet is not offered by the provider; it is not an error.


Choose a Mode

Token modeLegacy mode
Who executesThe checkout frame calls POST /api/v1/cards/topup/execute itselfYour application calls execute with the sheet's token
Configauth: { checkoutToken }No auth
Result callbackonExecuted / onExecuteFailedonToken
Wallet payment tokenNever leaves the frameDelivered to your page in onToken
Google Pay on desktopQR handoff to an Android phoneNot available
Android Custom Tabs launchSupportedNot 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? }
OptionTypeDescription
configobjectProvider block. When present, its Google Pay values (auth methods, networks) drive the readiness check verbatim
forcebooleanBypass the per-session cache and probe again
cacheStorage-like | nullPersistent 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.

FieldTypeDescription
applePaybooleanApple Pay can pay here. false — hide the Apple Pay entry
googlePaybooleanGoogle Pay can tokenize here
googlePayHandoffbooleanGoogle Pay cannot tokenize here, but the desktop QR can finish it. Token mode only
googlePayStateenumSummary of Google Pay for this context — see below
googlePayStateMeaningSuggested UI
readyGoogle Pay can pay here (googlePay: true)Show the entry; open the checkout
handoffDesktop: no native Google Pay, the phone QR can finish itToken mode only — see Google Pay on Desktop
needs_cardAndroid, Google Pay works, but no card in Google Wallet on this phone qualifiesOptionally show the entry and send the user to Google Wallet; re-check with force: true when they return
unavailableGoogle Pay cannot be used hereHide the entry

googlePay: false outside 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_card is never reported when the provider block passed in config has no google_pay key.

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 fieldRequiredSourceDescription
estimationIdYesestimation_idBinds the sheet to the priced estimation
sourceAmountYessource_amount, source_currencyThe fiat amount the sheet charges
destinationAmountNodestination_amount, destination_token_symbolThe "Top up" row
feeNofee_amount, fee_currencyThe fee row
rateNoYour own formatting of rateDisplay-only rate line
expiresAtMsNoexpires_at × 1000Drives 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_at is Unix seconds; expiresAtMs is 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

FieldTypeRequiredDescription
quoteobjectYesSee Step 2
walletConfigobjectYesProvider block, verbatim
auth.checkoutTokenstringConditionalRestricted top-up token. Present — token mode; absent — legacy mode
providerstringConditionalThe estimate's provider name. Required for the desktop Google Pay QR
googlePayHandoffqr | noneNoToken mode only. qr (default) shows the phone QR where Google Pay cannot tokenize; none hides Google Pay there
applePayHandoffinline | popupNoWhere the Apple Pay session runs — see Apple Pay and Your Domain. Default inline
layoutfull | compactNofull (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
appearanceobjectNoShared appearance tokens — see Branding and Appearance
buttonsobjectNoApple and Google button presets
brandingobjectNoLogo slot, processing disclosure, privacy link
stringsobjectNoTranslated labels
onToken(token) => voidConditionalLegacy mode. Required when auth is absent
onExecuted(result) => voidNoToken mode. The frame executed the top-up
onExecuteFailed(error) => voidNoToken mode. The execute call failed
onReady() => voidNoReview screen rendered, buttons live
onStateChange(state) => voidNoCheckout state — see Events
onCancel() => voidNoThe user dismissed the sheet. Nothing happened; the button stays usable
onAttemptFailed(reason) => voidNoThe sheet opened but produced no token
onEstimationExpired() => voidNoThe quote expired in view

Events

CallbackWhenWhat to do
onReadyReview screen renderedHide your spinner
onStateChange(state)loading → ready → sheet-open; token mode adds executing and handoff-pendingDrive your own chrome
onCancelSheet dismissedShow 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
onEstimationExpiredQuote expired while on screenRe-estimate, mint a new token in token mode, call update()
onExecuted(result)Token mode: execute returnedTreat result.status like your card top-up flow's
onExecuteFailed(error)Token mode: execute failedSee the reason table below. The frame stays disabled until update() re-arms it
onToken(token)Legacy mode: sheet authorizedExecute on your side — see Legacy Mode

onExecuted result:

FieldDescription
idTop-up transaction id
statusThe execute response's status (Completed, Pending, Failed, …). Reconcile through your status feed
methodapple_pay or google_pay
cardNetwork, panLast4, displayNameDisplay metadata for your confirmation UI

onExecuteFailed reasons:

reasonHTTP statusCauseResolution
execute_rejected4xxValidation failure or rejected requestShow an error; re-estimate before retrying
already_executed409A second execute on the same estimationReconcile by status — the first execute may have succeeded
estimation_expired422The estimation expired before executeRe-estimate, mint a new token, update()
execute_unauthorized401 / 403The checkout token expired or has the wrong scopeMint a new token, update()
execute_failed5xxBackend failureReconcile by status before offering a retry
network_error—No responseReconcile 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:

ModeHowTrade-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 automaticallyOne extra click
Popup checkout — openWalletCheckoutPopup()The whole checkout opens top-level in a popup on the frame domainNo iframe on your page

Pass applePayHandoff: 'popup'. The default inline works 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),
  );
});
MethodDescription
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.

  1. The user scans the code with an Android phone.
  2. The same checkout opens top-level on the phone, runs the native Google Pay sheet and executes.
  3. 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. onExecuted does 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 fieldExecute fieldDescription
walletPaymentTokenwallet_payment_tokenEncrypted, gateway-bound payload. Relay verbatim; max 16384 characters
cardholderNamecardholder_namePresent only when the provider block requests billing fields
billingDetailsbilling_addressPresent only when the provider block requests billing fields (required_billing_contact_fields / billing_address_required)
walletTransactionIdwallet_transaction_idApple'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.
  • cardholderName and billingDetails are 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' } },
});
OptionValuesDescription
branding.logowirex (default), hidden, customThe logo above the total
branding.logoImagedata:image/… URICustom logo for logo: 'custom'. Remote URLs never load — the frame's CSP allows only data: images
branding.processingDisclosure.partnerNamestringRenders "Wirex processes this payment on behalf of {partnerName}". Omit to hide the line
branding.privacyUrlhttps:// URLThe link behind the privacy line under the button. Anything else falls back to the Wirex privacy policy
buttons.applePay.styleblack, white, white-outlineApple's presets
buttons.applePay.typeplain, top-up, buyApple's presets
buttons.googlePay.colorblack, whiteGoogle's presets
buttons.googlePay.typeplain, pay, buyGoogle'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

PlatformHow
Your Android appGoogle 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 appWKWebView 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
    returnUrl with estimation_id and outcome (completed, pending, failed, already_executed)
    appended. Reconcile by estimation status on your backend — the link is a UX signal, not the result.
  • returnUrl is an https App 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: and http: are refused: buildWalletLaunchUrl throws
    a TypeError.
  • 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

ExportDescription
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.


Did this page help you?