ReactNative Payments

Accept Payments with Apple Pay and Android Pay using the Payment Request API.

TurboModule-based implementation of the W3C Payment Request API (08 September 2022) for React Native — full TypeScript, a unified iOS/Android API, and an Expo config plugin. A rewrite of naoufal/react-native-payments; see Migrating from upstream if you are porting an existing integration.

For AI agents

Start with llms.txt for a curated, agent-oriented index of this package's docs and AGENTS.md for architecture and contributor conventions.

Install

yarn add @rnw-community/react-native-payments

Autolinking picks up the TurboModule on both architectures — no manual react-native link step. Complete the one-time platform setup before writing any code: iOS · Android · Expo.

Quickstart

import {
    PaymentComplete,
    PaymentMethodNameEnum,
    PaymentRequest,
    SupportedNetworkEnum,
} from '@rnw-community/react-native-payments';

const methodData = [
    {
        supportedMethods: PaymentMethodNameEnum.ApplePay,
        data: {
            merchantIdentifier: 'merchant.com.your-app.namespace',
            supportedNetworks: [SupportedNetworkEnum.Visa, SupportedNetworkEnum.Mastercard],
            countryCode: 'US',
            currencyCode: 'USD',
        },
    },
    // Add a matching AndroidPay entry to the same array to support both platforms.
];
const paymentDetails = { total: { label: 'Total', amount: { currency: 'USD', value: '10.00' } } };

const paymentRequest = new PaymentRequest(methodData, paymentDetails);

if (await paymentRequest.canMakePayment()) {
    const paymentResponse = await paymentRequest.show();
    const isConfirmed = await sendToYourBackend(paymentResponse.details); // your own gateway call

    await paymentResponse.complete(isConfirmed ? PaymentComplete.SUCCESS : PaymentComplete.FAIL);
}

Only call complete(PaymentComplete.SUCCESS) once your backend has actually confirmed the charge. A PaymentRequest is single-use — build a new one per payment attempt rather than reusing a settled request; see docs/architecture.md. For the full two-platform methodData shape, shipping/coupon change events, and payment details modifiers, see the doc map below.

Screenshots

Recording is deferred, not dropped — capture needs the on-device Maestro fleet, tracked in docs/roadmap.md. Once captured, an Apple Pay and a Google Pay sheet GIF replace this placeholder.

Doc map

• Getting started — Install · iOS · Android · Expo
• Platforms — iOS · Android · Web · Expo
• API reference — index (PaymentRequest, PaymentResponse, every exported type/enum)
• Guides — Payment change events · Payment details modifiers · Error handling · Retrying a payment · Unit testing · Troubleshooting
• Architecture — The JS↔native contract, single-use requests, event lifecycle
• Roadmap — Open work and the W3C compliance checklist

Migrating

• From v2 to v3 — the native module interface change and the single-use request behavior change.
• From upstream react-native-payments — the full API mapping and a worked before/after example.

W3C compliance

This package implements the W3C Payment Request API — change events, PaymentDetailsModifier, hasEnrolledInstrument(), retry(), toJSON() and the event-handler attributes are all implemented, with a small set of documented platform deviations (Android has no in-sheet change events, iOS ignores shippingOption.selected, PaymentRequest is single-use). See the full W3C compliance checklist and each platform's known deviations in docs/platforms/.

Architecture & contributing

See AGENTS.md for the source layout, TurboModule/Expo-plugin architecture, and coverage. For end-to-end verification, see react-native-payments-example/e2e/readme.md.

License

This library is licensed under The MIT License.