Restricting wallet cards by issuing country (Apple Pay)

Apple Pay's wallet module accepts an optional allowedCountries array on the payment data you pass in. The array filters the wallet sheet to only offer cards issued in those countries listed in Apple's supportedCountries on the ApplePayPaymentRequest.

Rules

• Optional. Omit the array or pass undefined and the payment request is unchanged.
• Non-empty array of ISO 3166-1 alpha-2 codes when supplied. [ ], ['GBR'], '['G'], or non-strings reject.
• Case-insensitive - 'gb' is normalised to 'GB' before reaching the wallet.
• Filters by card issuing country, not billing or shipping address.
• The wallet enforces it: a customer with no eligible card can't complete that wallet flow so ensure you offer a fallback payment method.

Using the array

Add allowedCountries to the object passed to startSession:

applePayClientModule.startSession({
  label: 'A short order description',
  type: 'final',
  amount: '1.00',
  currencyCode: 'GBP',                // falls back to merchant config if omitted
  allowedCountries: ['GB', 'IE']      // remove for no restriction
}, function (comcardeSingleUseToken, ApplePaySession) {
  // The SDK tokenizes the payment and hands you the token plus the raw session.
  // Send the token to your server, then close the sheet — the session stays
  // open until you call completePayment:
  ApplePaySession.completePayment(ApplePaySession.STATUS_SUCCESS); // or STATUS_FAILURE
});

The SDK copies it to supportedCountries on the ApplePayPaymentRequest.

Apple Pay version requirement

supportedCountries only exists on Apple Pay JS API version 3+. The SDK defaults to version 14, so most integrators do nothing. If you pin sdkVersion below 3 in applePay.create(), supplying allowedCountries rejects rather than silently opening an unrestricted sheet:

comcarde.applePay.create({
  client: clientInstance,
  sdkVersion: 3, // minimum if you use allowedCountries
  // ...
});

Errors

All errors are ComcardeError with type: MERCHANT — they indicate that your integration is wrong, not a customer problem. They are promise rejections, so handle them in .catch.

Quick reference

allowedCountries: ['GB', 'IE']  // valid
allowedCountries: ['gb', 'ie']  // valid — normalised to uppercase
allowedCountries: []            // rejects — must be non-empty
allowedCountries: 'GB,IE'       // rejects — must be an array
// property omitted entirely    // valid — no restriction