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
6 changes: 3 additions & 3 deletions .ai/specs/SPEC-001-2026-02-10-core-module-architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Core shared models are defined in `package/src/types/Payment.ts`:
- `PaymentRequest`: input contract for native payment start
- `PaymentItem`: line items used for totals and display
- `PaymentResult`: success/error envelope and token details
- `PayServiceStatus`: platform availability flags
- `PayServiceStatus`: availability flags (`isSupported`, `hasActiveCard`)

Cross-layer contract rule:

Expand All @@ -69,10 +69,10 @@ Cross-layer contract rule:

Primary low-level contract:

- `payServiceStatus(): PayServiceStatus`
- `payServiceStatus(options?: PayServiceStatusOptions): Promise<PayServiceStatus>`
- `startPayment(request: PaymentRequest): Promise<PaymentResult>`
- `canMakePayments(usingNetworks: string[]): boolean`
- `isPaymentInProgress(): boolean` — whether a payment started with `startPayment` has not settled yet. Backed by the native single-payment slot (`PendingPayment` on iOS and Android), which `startPayment` claims synchronously on the calling thread and frees when the payment settles.
- `openPaymentSetup(): void` (iOS only)

Primary high-level API:

Expand Down
2 changes: 1 addition & 1 deletion .ai/specs/SPEC-002-2026-02-10-use-payment-checkout-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ The hook provides state for UI rendering but does not own UI components.
Recommended consumer pattern:

- Use `isCheckingStatus` for initial availability loading.
- Use `canMakePayments` for gating payment controls.
- Use `isSupported` for gating payment controls, and `hasActiveCard` to choose between a pay and a "Set up" button on iOS.
- Use `isProcessing` for disabled/loading button state.
- Use `error` for actionable feedback.

Expand Down
26 changes: 26 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,21 @@ All notable changes to this project are documented in this file.
`startPayment` now marks the payment in progress as soon as it is called, as on Android, instead
of when it starts presenting the sheet, so `isPaymentInProgress()` sees a payment started in the
same JS tick.
- **Availability checks are asynchronous and report `isSupported` and `hasActiveCard`.**
`HybridPaymentHandler.payServiceStatus()` now returns a Promise, and `PayServiceStatus` is
`{ isSupported, hasActiveCard }` instead of `{ canMakePayments, canSetupCards }`, which meant
different things on each platform. `usePaymentCheckout` returns `isSupported`, `hasActiveCard`
and a new `refreshStatus()` instead of `canMakePayments` and `canSetupCards`. The check takes the
networks, merchant capabilities and Google Pay environment to check against; the hook passes
those of its payment request. To migrate, `await` the call and read `isSupported` where you read
`canMakePayments` (the same check on iOS, and the one Google recommends for showing the button on
Android). See
[Check availability](https://gmi-software.github.io/react-native-pay/docs/guides/availability).
- **`HybridPaymentHandler.canMakePayments(networks)` is removed.** It answered the same question as
`hasActiveCard`: call `payServiceStatus({ supportedNetworks: networks })` and read
`hasActiveCard`. On Android it never asked the device, so `['visa']` was always `true`.
- **iOS: `HybridPaymentHandler.openPaymentSetup()`** opens Wallet so the user can add a card, for a
"Set up Apple Pay" button (`ApplePayButton` with `buttonType="setUp"`). It does nothing on Android.

### Fixed

Expand All @@ -59,6 +74,17 @@ All notable changes to this project are documented in this file.
- **iOS: an unknown `shippingType` fails the payment** with `Unknown shipping type "<value>". Use
"shipping", "delivery", "storePickup" or "servicePickup"` instead of silently becoming
`"shipping"`. Android ignores `shippingType`.
- **Android: availability checks no longer block the JS thread.** `payServiceStatus()` made two
`isReadyToPay` calls one after the other and waited up to 5 seconds for each on the JS thread, so
every checkout screen froze touches, animations and timers until Google Play services answered.
Both calls now run at once and resolve the Promise when they finish; one that takes longer than
5 seconds counts as `false`. On iOS, the PassKit checks run off the JS thread too.
- **Android: availability is checked in the environment you pay in.** The check always used `TEST`
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: 32 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,8 @@ import { callback } from 'react-native-nitro-modules'
function CheckoutScreen() {
const {
// Payment availability
canMakePayments,
isSupported,
isCheckingStatus,

// Cart management
items,
Expand Down Expand Up @@ -246,7 +247,11 @@ function CheckoutScreen() {
}
}

if (!canMakePayments) {
if (isCheckingStatus) {
return <View><ActivityIndicator /></View>
}

if (!isSupported) {
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
return (
<View>
<Text>Apple Pay or Google Pay is not available on this device</Text>
Expand Down Expand Up @@ -393,9 +398,10 @@ interface UsePaymentCheckoutConfig {
```typescript no-check
interface UsePaymentCheckoutReturn {
// Payment availability
canMakePayments: boolean; // Can user make payments?
canSetupCards: boolean; // Can user add cards?
isCheckingStatus: boolean; // Loading state for availability check
isSupported: boolean; // Device supports Apple Pay / Google Pay
hasActiveCard: boolean; // A card on supportedNetworks is ready
isCheckingStatus: boolean; // true until the availability check settles
refreshStatus: () => void; // Check again, e.g. after the user added a card

// Cart management
items: PaymentItem[]; // Current cart items
Expand Down Expand Up @@ -455,27 +461,32 @@ Low-level payment handler for direct control.

#### Methods

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

Check payment service availability.
Check payment service availability without blocking the JS thread. Pass the networks, capabilities and Google Pay environment your payment request uses.

```typescript
import { HybridPaymentHandler } from "@gmisoftware/react-native-pay";

const status = HybridPaymentHandler.payServiceStatus();
console.log("Can make payments:", status.canMakePayments);
console.log("Can setup cards:", status.canSetupCards);
const status = await HybridPaymentHandler.payServiceStatus({
supportedNetworks: ["visa", "mastercard"],
googlePayEnvironment: "PRODUCTION",
});
console.log("Wallet supported:", status.isSupported);
console.log("Card ready:", status.hasActiveCard);
```

**Returns:**

```typescript
interface PayServiceStatus {
canMakePayments: boolean;
canSetupCards: boolean;
isSupported: boolean; // iOS: canMakePayments(); Android: isReadyToPay
hasActiveCard: boolean; // iOS: canMakePayments(usingNetworks:capabilities:); Android: isReadyToPay with existingPaymentMethodRequired
}
```

Android asks the `TEST` environment unless you pass `googlePayEnvironment`, and in `TEST` `hasActiveCard` is `true` whether or not the user has a card. See [Check availability](https://gmi-software.github.io/react-native-pay/docs/guides/availability) for which button to show.

##### `startPayment(request: PaymentRequest, options?: StartPaymentOptions): Promise<PaymentResult>`

Start a payment request.
Expand Down Expand Up @@ -533,16 +544,6 @@ interface PaymentToken {
}
```

##### `canMakePayments(usingNetworks: string[]): boolean`

Check if specific card networks are supported.

```typescript
import { HybridPaymentHandler } from "@gmisoftware/react-native-pay";

const canPay = HybridPaymentHandler.canMakePayments(["visa", "mastercard"]);
```

##### `isPaymentInProgress(): boolean`

Check whether a payment started with `startPayment` (directly or by `usePaymentCheckout`) has not settled yet. While it returns `true`, `startPayment` resolves with `{ success: false, error: "A payment is already in progress" }`.
Expand All @@ -553,6 +554,10 @@ import { HybridPaymentHandler } from "@gmisoftware/react-native-pay";
const isBusy = HybridPaymentHandler.isPaymentInProgress();
```

##### `openPaymentSetup(): void`

iOS only: opens Wallet so the user can add a card. Call it from an `ApplePayButton` with `buttonType="setUp"`. It does nothing on Android, where the Google Pay sheet lets the user add a card.

---

### Button Components
Expand Down Expand Up @@ -912,8 +917,10 @@ import {
import { Platform } from 'react-native'
import { callback } from 'react-native-nitro-modules'

// 1. Check availability
const { canMakePayments } = HybridPaymentHandler.payServiceStatus()
// 1. Check availability, against the environment you pay in
const { isSupported } = await HybridPaymentHandler.payServiceStatus({
googlePayEnvironment: 'PRODUCTION',
})

// 2. Create payment request
const paymentRequest = createPaymentRequest({
Expand Down Expand Up @@ -951,7 +958,7 @@ const handlePayment = async () => {

// 4. Render the button. onPress must be wrapped with callback().
function PaymentButton() {
if (!canMakePayments) return null
if (!isSupported) return null

return Platform.OS === 'ios' ? (
<ApplePayButton
Expand Down
23 changes: 14 additions & 9 deletions docs/docs/api/hybrid-payment-handler.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,24 @@ import { HybridPaymentHandler, createPaymentRequest } from '@gmisoftware/react-n

## Methods

### payServiceStatus()
### payServiceStatus(options?)

Synchronously returns whether the payment service is available on the device.
Resolves with whether the device supports the wallet and whether a card is ready. The check runs off the JS thread.

```ts
import { HybridPaymentHandler } from '@gmisoftware/react-native-pay'

const status = HybridPaymentHandler.payServiceStatus()
// status: { canMakePayments: boolean, canSetupCards: boolean }
const status = await HybridPaymentHandler.payServiceStatus({
supportedNetworks: ['visa', 'mastercard'],
googlePayEnvironment: 'PRODUCTION',
})
// status: { isSupported: boolean, hasActiveCard: boolean }
```

- **canMakePayments** — User can complete a payment (has a valid card, etc.).
- **canSetupCards** — User can add or manage cards (e.g. Wallet settings).
- **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).

---

Expand Down Expand Up @@ -101,14 +106,14 @@ const isBusy = HybridPaymentHandler.isPaymentInProgress()

---

### canMakePayments(usingNetworks)
### openPaymentSetup()

Returns whether the user can make payments with the given card networks.
iOS only. Opens Wallet (Settings on iPad) so the user can add a card. Call it from a **Set up Apple Pay** button (`ApplePayButton` with `buttonType="setUp"`) when `isSupported` is `true` and `hasActiveCard` is `false`. It does nothing on devices without Apple Pay, and nothing on Android, where the Google Pay sheet lets the user add a card.

```ts
import { HybridPaymentHandler } from '@gmisoftware/react-native-pay'

const canPay = HybridPaymentHandler.canMakePayments(['visa', 'mastercard'])
HybridPaymentHandler.openPaymentSetup()
```

## When to use
Expand Down
25 changes: 22 additions & 3 deletions docs/docs/api/types.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,12 +179,31 @@ type PaymentNetwork =

## PayServiceStatus

Returned by `HybridPaymentHandler.payServiceStatus()`.
Resolved by `HybridPaymentHandler.payServiceStatus()`.

```ts
interface PayServiceStatus {
canMakePayments: boolean
canSetupCards: boolean
isSupported: boolean // the device can pay with Apple Pay / Google Pay
hasActiveCard: boolean // a card on the checked networks is ready
}
```

| | iOS | Android |
|---|---|---|
| `isSupported` | `PKPaymentAuthorizationViewController.canMakePayments()` | `isReadyToPay` |
| `hasActiveCard` | `canMakePayments(usingNetworks:capabilities:)` | `isReadyToPay` with `existingPaymentMethodRequired: true` |

In the Google Pay `TEST` environment, `hasActiveCard` is `true` whether or not the user has a card. See [Check availability](/docs/guides/availability).

## PayServiceStatusOptions

What `payServiceStatus` checks. Pass the values your payment request uses.

```ts
interface PayServiceStatusOptions {
supportedNetworks?: string[] // default: ['visa', 'mastercard', 'amex', 'discover']
merchantCapabilities?: string[] // iOS only. Default: ['3DS']
googlePayEnvironment?: 'TEST' | 'PRODUCTION' // Android only. Default: 'TEST'
}
```

Expand Down
17 changes: 11 additions & 6 deletions docs/docs/api/use-payment-checkout.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ interface UsePaymentCheckoutConfig {

- **merchantName** — The business name shown to the payer. On iOS, Apple Pay labels the total with it, so the sheet reads "Pay *merchantName*". On Android, it is the merchant name on the Google Pay sheet. Without it, iOS uses your app's display name (`CFBundleDisplayName`) and Android uses the app's label. Set it on both platforms.
- **merchantCapabilities** — Apple Pay only. iOS adds `'3DS'` when neither `'3DS'` nor `'EMV'` is given, and fails the payment for an unknown value. See [MerchantCapability](/docs/api/types#merchantcapability).
- **supportedNetworks**, **merchantCapabilities**, **googlePayEnvironment** — Also used for the availability check. Set `googlePayEnvironment: 'PRODUCTION'` in a live app: in `TEST`, Google Pay reports a card whether or not there is one.
- **billingContactRequired**, **shippingContactRequired**, **emailRequired**, **phoneNumberRequired** — Ask the payer for a billing address, a shipping address, an email address or a phone number. They come back as `result.billingContact`, `result.shippingContact`, `result.emailAddress` and `result.phoneNumber`. See [Shipping and contact details](/docs/guides/contact-details).
- **onAuthorize** — Called with the token and the requested contact details after the user authorizes the payment. Charge it on your server and resolve with `{ status: 'success' }` or `{ status: 'failure', error }`. See [Charge before the sheet closes](/docs/guides/server-processing#charge-before-the-sheet-closes). An inline function is fine: `startPayment()` uses the one from the latest render, and a payment keeps that function until it settles, even if the config changes meanwhile.

Expand All @@ -50,9 +51,10 @@ interface UsePaymentCheckoutConfig {
```ts no-check
interface UsePaymentCheckoutReturn {
// Availability
canMakePayments: boolean
canSetupCards: boolean
isSupported: boolean
hasActiveCard: boolean
isCheckingStatus: boolean
refreshStatus: () => void

// Cart
items: PaymentItem[]
Expand All @@ -75,9 +77,12 @@ interface UsePaymentCheckoutReturn {
}
```

- **canMakePayments** — Whether the user can pay with Apple Pay / Google Pay on this device.
- **canSetupCards** — Whether the user can add or manage cards (e.g. in Wallet).
- **isCheckingStatus** — `true` while availability is being checked on mount.
- **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`. See [PayServiceStatus](/docs/api/types#payservicestatus) for what each platform checks.
- **isCheckingStatus** — `true` until the availability check settles. The hook checks on mount and again when `supportedNetworks`, `merchantCapabilities` or `googlePayEnvironment` change. The check never blocks the JS thread.
- **refreshStatus()** — Checks availability again, for example when the app returns from Wallet after `openPaymentSetup()`. `isCheckingStatus` is `true` until it settles, and the flags keep their last values meanwhile.

Which button to show for each combination is in [Check availability](/docs/guides/availability).
- **items** / **total** — Current cart and its exact decimal total, as a number (`NaN` if an amount is invalid). Amounts are `number | string` ([`PaymentAmount`](/docs/api/types#paymentamount)); use `formatAmount(item.amount, currencyCode)` to display them.
- **startPayment()** — Opens the native sheet. Returns `Promise<PaymentResult | null>`.
- Returns `null` and sets `error` when the cart is empty.
Expand All @@ -95,7 +100,7 @@ interface UsePaymentCheckoutReturn {
import { usePaymentCheckout } from '@gmisoftware/react-native-pay'

const {
canMakePayments,
isSupported,
items,
total,
addItem,
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ import {
import { callback } from 'react-native-nitro-modules'

const {
canMakePayments,
isSupported,
isCheckingStatus,
items,
total,
Expand Down
Loading
Loading