Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 43 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,43 @@ All notable changes to this project are documented in this file.
iOS the payer picks one, and the first is selected by default. Google Pay cannot offer a choice
yet, so Android charges the first method. An empty or repeated `identifier`, a negative
`amount`, or `paymentItems` that total less than zero without shipping fail the payment.
- **`googlePayAllowedAuthMethods`** in `PaymentRequest` and the `usePaymentCheckout` config
(`GooglePayAuthMethod[]`: `'PAN_ONLY'`, `'CRYPTOGRAM_3DS'`) limits which Google Pay cards are
accepted, for example device tokens only under SCA. Both by default, as before.
- **More card networks.** `PaymentNetwork` gains `cartesBancaires`, `chinaUnionPay`, `dankort`,
`eftpos`, `girocard`, `mada`, `mir`, `quicPay`, `suica`, `vPay`, `waon`, `nanaco`, `bancontact`,
`postFinance`, `pagoBancomat`, `tmoney`, `meeza`, `napas`, `bankAxept`, `himyan`, `jaywan` and
`myDebit`, which Apple Pay accepts in `supportedNetworks` and reports in results. Android
accepts `jcb` and `interac`, and `electron`, `maestro` and `elo` for Brazilian combo cards.
- **`GooglePayButton` takes `supportedNetworks`, `googlePayAllowedAuthMethods` and
`merchantCapabilities`,** and `PayServiceStatusOptions` takes `googlePayAllowedAuthMethods`, under
the same names as in `PaymentRequest`. Give them the values of your request, so the button and
`hasActiveCard` count the same cards as the payment. `usePaymentCheckout` passes its config to
`payServiceStatus`.
- **Android honours a debit-only `merchantCapabilities`.** `'Debit'` without `'Credit'` now leaves
credit cards out of the Google Pay request (`allowCreditCards: false`), as UK gambling merchants
must. Prepaid cards stay allowed. Google Pay cannot leave debit cards out, so `'Credit'` alone
still accepts every card type on Android; `'3DS'` and `'EMV'` have no effect there. The button
and the readiness check leave credit cards out too.

### Changed

- **`PaymentNetwork` has a new `'unknown'` value,** reported for a card on a network the library
cannot name. Both platforms used to report such cards as `'visa'`. Code that switches over
`token.paymentMethod.network` needs a case for it.
- **An unknown name in `supportedNetworks` fails the payment** on both platforms, with an `error`
that contains `Unknown payment network "<value>". Use a PaymentNetwork value such as "visa" or
"mastercard"`. iOS used to drop it silently. Names now match ignoring case, so `'Visa'` works,
and a network the platform does not offer is left out; the payment fails when none is left.
`payServiceStatus` rejects with the same configuration error for a value the payment would
refuse, instead of answering `hasActiveCard: false`.
- **An unknown value in `merchantCapabilities` fails the payment on Android too,** with the same
`error` as on iOS: `Unknown merchant capability "<value>". Use "3DS", "EMV", "Credit" or
"Debit"`. Android used to ignore the field.
- **Android: `PaymentMethod.displayName` is the wallet's description of the card** (Google Pay's
`paymentMethodData.description`, for example "Visa •••• 1234") instead of `"VISA 1234"`. Google
Pay asks apps not to show `cardNetwork` to the payer. Use `network` for logic.

- **`PaymentRequest.shippingMethods` is `ShippingMethod[]`, not `PaymentItem[]`.** Neither
platform ever read the old field, so only the type changes: give each method an `identifier`
and drop `type`.
Expand Down Expand Up @@ -68,6 +102,15 @@ All notable changes to this project are documented in this file.

### Fixed

- **Android: `supportedNetworks` limits the cards the payer can choose.** Android ignored it and
always offered Visa, Mastercard, Amex and Discover, so a merchant whose gateway refuses Amex
still received Amex tokens, and JCB or Interac could not be enabled. The payment request, the
`GooglePayButton` and the readiness check behind `payServiceStatus` now use the same networks
and auth methods.
- **Android: `PaymentMethod.type` reports the card's funding source.** It was always
`'unknown'`. It now reads Google Pay's `cardFundingSource`, so a result reports `'credit'`,
`'debit'` or `'prepaid'`, and `'unknown'` only when Google Pay does not know. `'store'` stays
iOS only.
- **Requested contact details are no longer lost.** iOS asked for the billing and shipping
address but never returned them, and Android ignored `billingContactRequired` and
`shippingContactRequired`. See Added.
Expand All @@ -83,8 +126,6 @@ All notable changes to this project are documented in this file.
until a payment had started, and in `TEST` Google Pay reports a card whether or not there is one,
so production apps showed the pay button for users without a card. It now uses
`googlePayEnvironment` from the hook config or the options.
- **`hasActiveCard` is `false` when no checked network is one the platform knows.** iOS passed an
empty network list to PassKit, which can answer `true` for it.
- **iOS: Apple Pay requests always include 3DS or EMV.** PassKit needs one of them, but iOS
matched only the exact strings `3DS`, `EMV`, `Credit` and `Debit` and dropped everything else,
so `[]`, `['Credit']` or `['3ds']` built a request with neither. Values are now matched
Expand Down
57 changes: 47 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -372,14 +372,15 @@ interface UsePaymentCheckoutConfig {
merchantName?: string; // "Pay <merchantName>" on Apple Pay; defaults to the app name
countryCode?: string; // Default: 'US'
currencyCode?: string; // Default: 'USD'
supportedNetworks?: string[]; // Default: ['visa', 'mastercard', 'amex', 'discover']
merchantCapabilities?: MerchantCapability[]; // Default: ['3DS']
supportedNetworks?: string[]; // PaymentNetwork names. Default: ['visa', 'mastercard', 'amex', 'discover']
merchantCapabilities?: MerchantCapability[]; // Default: ['3DS']. Android: only Debit without Credit
applePayMerchantIdentifier?: string; // Optional iOS override
// Google Pay specific (Android)
googlePayMerchantId?: string;
googlePayEnvironment?: "TEST" | "PRODUCTION";
googlePayGateway?: string;
googlePayGatewayMerchantId?: string;
googlePayAllowedAuthMethods?: GooglePayAuthMethod[]; // Default: ['PAN_ONLY', 'CRYPTOGRAM_3DS']
// Contact details, returned in the result (see "Shipping and contact details")
billingContactRequired?: boolean;
shippingContactRequired?: boolean;
Expand Down Expand Up @@ -463,7 +464,7 @@ Low-level payment handler for direct control.

##### `payServiceStatus(options?: PayServiceStatusOptions): Promise<PayServiceStatus>`

Check payment service availability without blocking the JS thread. Pass the networks, capabilities and Google Pay environment your payment request uses.
Check payment service availability without blocking the JS thread. Pass the `supportedNetworks`, `merchantCapabilities`, `googlePayAllowedAuthMethods` and `googlePayEnvironment` your payment request uses. The Promise rejects with the payment's configuration error for a value the payment would refuse.

```typescript
import { HybridPaymentHandler } from "@gmisoftware/react-native-pay";
Expand Down Expand Up @@ -634,6 +635,11 @@ interface GooglePayButtonProps {

radius?: number; // Corner radius in dp

// The cards your payment accepts, so the button never shows another card.
supportedNetworks?: string[]; // as PaymentRequest.supportedNetworks
googlePayAllowedAuthMethods?: string[]; // as PaymentRequest.googlePayAllowedAuthMethods
merchantCapabilities?: string[]; // as PaymentRequest.merchantCapabilities

onPress?: () => void; // wrap with callback() from react-native-nitro-modules
style?: ViewStyle;
}
Expand Down Expand Up @@ -759,7 +765,7 @@ interface PaymentRequest {
currencyCode: string;
paymentItems: PaymentItem[];
merchantCapabilities: string[]; // MerchantCapability values
supportedNetworks: string[];
supportedNetworks: string[]; // PaymentNetwork names; unknown names fail
shippingType?: string; // ShippingType value, iOS only
shippingMethods?: ShippingMethod[]; // → PaymentResult.shippingMethod
billingContactRequired?: boolean; // → PaymentResult.billingContact
Expand All @@ -771,6 +777,7 @@ interface PaymentRequest {
googlePayEnvironment?: "TEST" | "PRODUCTION";
googlePayGateway?: string;
googlePayGatewayMerchantId?: string;
googlePayAllowedAuthMethods?: string[]; // GooglePayAuthMethod values
}

// Payment Result
Expand All @@ -790,14 +797,16 @@ interface PaymentToken {

// Payment Method
interface PaymentMethod {
displayName?: string;
network?: PaymentNetwork;
type: PaymentMethodType;
displayName?: string; // for the payer, e.g. "Visa •••• 1234"; don't parse it
network?: PaymentNetwork; // "unknown" when the library cannot name it
type: PaymentMethodType; // funding source; "store" is iOS only
secureElementPass?: PKSecureElementPass;
billingAddress?: CNContact;
}

// Payment Networks
// Payment Networks. Google Pay offers visa, mastercard, amex, discover, jcb
// and interac, plus electron, maestro and elo for Brazilian combo cards.
// Apple Pay offers all of them; each platform leaves out the ones it lacks.
type PaymentNetwork =
| "visa"
| "mastercard"
Expand All @@ -809,7 +818,33 @@ type PaymentNetwork =
| "elo"
| "idcredit"
| "interac"
| "privateLabel";
| "privateLabel"
| "cartesBancaires"
| "chinaUnionPay"
| "dankort"
| "eftpos"
| "girocard"
| "mada"
| "mir"
| "quicPay"
| "suica"
| "vPay"
| "waon"
| "nanaco"
| "bancontact"
| "postFinance"
| "pagoBancomat"
| "tmoney"
| "meeza"
| "napas"
| "bankAxept"
| "himyan"
| "jaywan"
| "myDebit"
| "unknown"; // results only

// Google Pay auth methods (Android)
type GooglePayAuthMethod = "PAN_ONLY" | "CRYPTOGRAM_3DS";

// Payment Method Type
type PaymentMethodType = "unknown" | "debit" | "credit" | "prepaid" | "store";
Expand All @@ -830,7 +865,9 @@ Google Pay accepts at most two decimal places, so three-decimal amounts (`"1.234

### Merchant capabilities

`merchantCapabilities` is used by Apple Pay only. `"3DS"` and `"EMV"` are payment protocols, and PassKit needs at least one of them: EMV only covers China UnionPay, so every other card needs 3DS. `"Credit"` and `"Debit"` limit the accepted card types. iOS matches the values case-insensitively and adds `"3DS"` when neither protocol is given, so `["Credit"]` is sent as 3DS + Credit. Any other value fails the payment with `Unknown merchant capability "<value>". Use "3DS", "EMV", "Credit" or "Debit"`.
`"3DS"` and `"EMV"` are Apple Pay payment protocols, and PassKit needs at least one of them: EMV only covers China UnionPay, so every other card needs 3DS. Android ignores them. `"Credit"` and `"Debit"` limit the accepted card types. iOS adds `"3DS"` when neither protocol is given, so `["Credit"]` is sent as 3DS + Credit. Both platforms match the values case-insensitively, and any other value fails the payment with `Unknown merchant capability "<value>". Use "3DS", "EMV", "Credit" or "Debit"`.

Google Pay can leave credit cards out, but not debit cards. On Android, `"Debit"` without `"Credit"` sends `allowCreditCards: false`, which UK gambling merchants must do; prepaid cards stay allowed. `["3DS", "Credit"]` accepts every card type on Android, so check the card on your server if you must refuse debit cards. Give `GooglePayButton` and `payServiceStatus` the same `merchantCapabilities` as the payment.

### Shipping and contact details

Expand Down
6 changes: 6 additions & 0 deletions docs/docs/api/components.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,14 @@ Renders the Google Pay button. Only available on Android.
| `buttonType` | `GooglePayButtonType` | Yes | Button label type. |
| `theme` | `'dark' \| 'light'` | Yes | Button theme. |
| `radius` | `number` | No | Corner radius in dp. |
| `supportedNetworks` | `string[]` | No | The card networks your payment accepts, as in `PaymentRequest.supportedNetworks`. Default: `visa`, `mastercard`, `amex`, `discover`. |
| `googlePayAllowedAuthMethods` | `string[]` | No | As in `PaymentRequest.googlePayAllowedAuthMethods`. Default: both. |
| `merchantCapabilities` | `string[]` | No | As in `PaymentRequest.merchantCapabilities`. `'Debit'` without `'Credit'` leaves credit cards out. Default: every card type. |
| `onPress` | `() => void`, wrapped with `callback()` | No | Called when the user taps the button. Must be wrapped, see [Nitro and onPress](#nitro-and-onpress). |
| `style` | `ViewStyle` | No | Layout/style (e.g. width, height). |

The button can show the payer's card, so give it the same `supportedNetworks`, `googlePayAllowedAuthMethods` and `merchantCapabilities` as the payment, under the same names. Otherwise it may show a card the payment then refuses. With `usePaymentCheckout`, pass them from `paymentRequest`. With an unknown network, auth method or merchant capability, the button keeps its previous configuration, or does not appear on the first render, and logs an error in debug builds.

**GooglePayButtonType:**
`'buy'` | `'book'` | `'checkout'` | `'donate'` | `'order'` | `'pay'` | `'subscribe'` | `'plain'`

Expand All @@ -76,6 +81,7 @@ const handlePayment = async () => {
buttonType="buy"
theme="dark"
radius={8}
supportedNetworks={['visa', 'mastercard']}
onPress={callback(handlePayment)}
style={{ width: '100%', height: 48 }}
/>
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/api/hybrid-payment-handler.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ const status = await HybridPaymentHandler.payServiceStatus({
- **isSupported** — The device can pay with Apple Pay / Google Pay, whether or not a card is set up.
- **hasActiveCard** — The user has a card ready on one of `supportedNetworks`.

Pass the networks, capabilities and Google Pay environment your payment request uses ([PayServiceStatusOptions](/docs/api/types#payservicestatusoptions)). A failed check resolves both flags as `false`, except that on iOS an unknown `merchantCapabilities` value rejects the Promise, as it fails `startPayment`. Without `googlePayEnvironment`, Android asks the `TEST` environment, where `hasActiveCard` is `true` whether or not the user has a card. What each platform checks, and which button to show, is in [Check availability](/docs/guides/availability).
Pass the `supportedNetworks`, `merchantCapabilities`, `googlePayAllowedAuthMethods` and `googlePayEnvironment` your payment request uses ([PayServiceStatusOptions](/docs/api/types#payservicestatusoptions)); `hasActiveCard` then counts only cards the payment accepts. Without them, both platforms ask about `visa`, `mastercard`, `amex` and `discover`. The Promise rejects with the configuration error that would fail `startPayment` for a value the payment would refuse: an unknown network, capability or auth method, or no network the platform offers. A check that fails for any other reason resolves both flags as `false`. Without `googlePayEnvironment`, Android asks the `TEST` environment, where `hasActiveCard` is `true` whether or not the user has a card. What each platform checks, and which button to show, is in [Check availability](/docs/guides/availability).

---

Expand Down
Loading
Loading