Skip to content
Skills Library
Programming · Building & coding

react-native-pay

/react-native-pay

Expert guide to @gmisoftware/react-native-pay — Apple Pay and Google Pay for React Native through Nitro Modules, with a unified usePaymentCheckout hook and native ApplePayButton / GooglePayButton views. Use when adding Apple Pay or Google Pay, configuring merchant IDs, entitlements, or the Expo config plugin, when the pay button does not appear or Google Pay reports unavailable, when handling a payment token on a backend, when testing payments, and when reasoning about what this library does and does not do with money.

Licence
MIT
Last repository change
14.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
10
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Expert guide to @gmisoftware/react-native-pay — Apple Pay and Google Pay for React Native through Nitro Modules, with a unified usePaymentCheckout hook and native ApplePayButton / GooglePayButton views. Use when adding Apple Pay or Google Pay, configuring merchant IDs, entitlements, or the Expo config plugin, when the pay button does not appear or Google Pay reports unavailable, when handling a payment token on a backend, when testing payments, and when reasoning about what this library does and does not do with money.

Original author description

Expert guide to @gmisoftware/react-native-pay — Apple Pay and Google Pay for React Native through Nitro Modules, with a unified usePaymentCheckout hook and native ApplePayButton / GooglePayButton views. Use when adding Apple Pay or Google Pay, configuring merchant IDs, entitlements, or the Expo config plugin, when the pay button does not appear or Google Pay reports unavailable, when handling a payment token on a backend, when testing payments, and when reasoning about what this library does and does not do with money.

How it works

  1. Version verification
  2. When to use
  3. When NOT to use
  4. Core architecture
  5. Security boundary (read first)
  6. Critical behaviours
  7. Problem → reference routing
  8. Common mistakes
  9. Troubleshooting
  10. Known limitations
Original SKILL.md headings · 154 lines, 884 words
SKILL.md preview
---
name: react-native-pay
description: >-
  Expert guide to @gmisoftware/react-native-pay — Apple Pay and Google Pay for React
  Native through Nitro Modules, with a unified usePaymentCheckout hook and native
  ApplePayButton / GooglePayButton views. Use when adding Apple Pay or Google Pay,
  configuring merchant IDs, entitlements, or the Expo config plugin, when the pay
  button does not appear or Google Pay reports unavailable, when handling a payment
  token on a backend, when testing payments, and when reasoning about what this
  library does and does not do with money.
license: MIT
metadata:
  package: "@gmisoftware/react-native-pay"
  version: "0.0.16"
  commit: 2078fdda8bdef87b51d20039d7684a255f0baadc
  verified: "2026-08-21"
  repository: https://github.com/gmi-software/react-native-pay
  audience: library users and library contributors
  tags: react-native, payments, apple-pay, google-pay, passkit, wallet, nitro, expo, ios, android, checkout
---

# react-native-pay

Skill for **`@gmisoftware/react-native-pay`**. Presents the platform payment sheet (Apple Pay /
Google Pay) and returns a payment token to JavaScript.

**This library does not charge anyone.** It tokenizes. Everything after that is your backend.

Paths like `package/src/...` are relative to a **library checkout**, not this skills repo.

## Version verification

```text
Package:            @gmisoftware/react-native-pay
Version:            0.0.16
Commit:             2078fdda8bdef87b51d20039d7684a255f0baadc
Verification date:  2026-08-21
```

`0.0.x` — treat the API as unstable; re-verify against the installed copy.

```bash
npm view @gmisoftware/react-native-pay version
node -p "require('@gmisoftware/react-native-pay/package.json').version"
```

## When to use

- Adding Apple Pay or Google Pay to React Native / Expo
- Merchant IDs, entitlements, Expo config plugin
- Button missing / Google Pay unavailable
- Backend token handling and gateway choice
- Testing payments; judging whether an integration is safe to ship
- Changing Nitro specs / Swift / Kotlin / config plugin

## When NOT to use

| Situation | Instead |
| --- | --- |
| Card fields, PayPal, subscriptions billing | Your gateway's React Native SDK |
| Charging, refunds, webhooks, reconciliation | Gateway **server** SDK |
| Apple Pay on the web | Apple's web Payment Request docs |
| Wallet passes / loyalty cards | PassKit pass APIs |
| Showing backend decline inside the Apple Pay sheet | Not possible today — see limitations |

## Core architecture

```text
JS builds PaymentRequest
  → HybridPaymentHandler.startPayment(request)
  → OS sheet (PassKit / Google Pay)
  → encrypted token → PaymentResult
  → YOUR CODE → YOUR BACKEND → gateway charge
```

| Export | Role |
| --- | --- |
| `HybridPaymentHandler` | Availability + `startPayment` |
| `usePaymentCheckout` | Cart state, availability, status |
| `ApplePayButton` / `GooglePayButton` | Platform-exclusive native buttons |

`usePaymentCheckout` and the exported `HybridPaymentHandler` each call `createHybridObject` at
module scope — two native instances. Pick one; do not mix
([architecture.md](references/architecture.md)).

Full surface: [api.md](references/api.md). No subpath exports.

## Security boundary (read first)

| Question | Answer |
| --- | --- |
| Network requests in the library? | **No** |
| Stores credentials/tokens? | **No** |
| Contacts a payment gateway? | **No** (gateway name is OS config only) |
| Charges the card? | **No** |
| Raw token exposed to JS? | **Yes** — `PaymentResult.token.paymentData` |

```text
LIBRARY:  present sheet, return token
YOU:      send token to backend over TLS
BACKEND:  authorise/capture with SECRET keys
```

1. **Never put gateway secrets in the client** (source, `.env`, `app.config.js`, binary).
2. **Never trust client-reported amounts** — backend recomputes from its order record.
3. **Treat the token as short-lived** — do not log, persist, or send off-backend.
4. **Crash/analytics must not capture `paymentData`.**
5. **UI contract is `pending` → `succeeded` | `failed`** from the backend — not the sheet.
6. **Authorise the caller against the referenced order** before charging.

Details: [security.md](references/security.md).

## Critical behaviours

1. **Apple Pay sheet always reports success** — hardcoded `.success` after 1s; sheet success ≠
   payment succeeded ([apple-pay.md](references/apple-pay.md)).
2. **Google Pay defaults to TEST** — omitting `googlePayEnvironment` → test tokens that cannot
   charge; set `'PRODUCTION'` explicitly ([google-pay.md](references/google-pay.md)).
3. **`canMakePayments` differs** — iOS queries the device; Android is a string list check. Prefer
   `payServiceStatus().canMakePayments` on Android.
4. **Failures resolve, they do not reject** — check `result.success`, do not rely on `try/catch`.

## Problem → reference routing

| Problem | Start here |
| --- | --- |
| Safe to ship? Backend responsibilities | [security.md](references/security.md) |
| Token → gateway (Stripe / Braintree / Adyen) | security + [api.md](references/api.md) |
| TEST vs PRODUCTION Google Pay | [google-pay.md](references/google-pay.md) |
| **Setup / Expo / native wiring** | [setup.md](references/setup.md) |
| Apple Pay from scratch | setup → [apple-pay.md](references/apple-pay.md) |
| Google Pay from scratch | setup → [google-pay.md](references/google-pay.md) |
| Button missing / unavailable | [debugging.md](references/debugging.md) |
| Exact API / field names | [api.md](references/api.md) |
| Testing on simulator/device; release gate | [testing.md](references/testing.md) |
| Native architecture | [architecture.md](references/architecture.md) |
| Contributing to the library | [contributing.md](references/contributing.md) |

## Common mistakes

- Shipping Stripe/Braintree **secret** keys in the app
- Treating sheet success as a successful charge
- Omitting `googlePayEnvironment: 'PRODUCTION'`
- Gating Android UI on `canMakePayments` alone
- `try/catch` around `startPayment` for cancellation
- Using Expo Go (Nitro requires a development build)
- Logging or sending `PaymentResult` to crash/analytics
- Inventing APIs (`processPayment`, `stripeSecretKey`, `onPaymentCaptured` — none exist)
- Mixing `usePaymentCheckout` with the exported `HybridPaymentHandler.startPayment`

## Troubleshooting

1. Module missing / Expo Go → [setup.md](references/setup.md)
2. Availability / button → platform refs + [debugging.md](references/debugging.md)
3. Wrong money / token shape → [security.md](references/security.md)
4. Confusing sheet result → critical behaviours above

## Known limitations

| Limitation | Consequence |
| --- | --- |
| iOS sheet always succeeds | Backend decline cannot appear in Apple Pay UI |
| Android ignores custom `supportedNetworks` | Hardcoded Visa/MC/Amex/Discover |
| One payment at a time | Second `startPayment` overwrites the first |
| Buttons are platform-exclusive | Branch on `Platform.OS` |
| `transactionId` is a client UUID | Not a gateway idempotency key |
| No Expo Go | Development build required |
| Simulator/emulator tokens unusable | Sheet may open; live charge needs a signed device |

## Accuracy

Never invent configuration keys or claim "PCI compliant". Describe what crosses the boundary.
Jest mocks Nitro — green tests do not prove a payment works.
Files in this package (10)
  • SKILL.md 7 KB
  • references/api.md 12 KB
  • references/apple-pay.md 9 KB
  • references/architecture.md 8 KB
  • references/contributing.md 8 KB
  • references/debugging.md 11 KB
  • references/google-pay.md 10 KB
  • references/security.md 13 KB
  • references/setup.md 7 KB
  • references/testing.md 10 KB

Versions

The database has no other skills named react-native-pay.

Database snapshot: 13.11.2026 · package version bc7d24c5b7a2 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100react-native-better-maps
    Expert guide to react-native-better-maps — native maps for React Native built on Nitro Modules, with Apple MapKit and Google Maps provider adapters, descriptor-based overlays, and native marker clustering. Use when installing or configuring the map, rendering markers or…
  • 100react-native-testing
    Test React Native components with Jest and React Native Testing Library. Use when writing Jest or React Native Testing Library tests for React Native components.
  • 100create-react-native-library
    Scaffolds React Native libraries with create-react-native-library for standalone libraries or local native modules and views. Use when creating or working on React Native libraries or adding native functionality in an existing app.
  • 95auth0-react-native
    Use when adding authentication to React Native or Expo mobile apps (iOS/Android) with biometric support - integrates react-native-auth0 SDK with native deep linking
  • 100react-native-skills
    React Native and Expo rules for lists, animations, navigation, images and native modules. Use when building or optimizing React Native apps.
  • 100react-native-web-testing
    Use when testing React Native Web applications. Provides patterns for Jest, React Native Testing Library, component testing, and web-specific testing strategies.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.