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

npm install @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,
    PaymentRequest,
    createApplePayMethodData,
    createGooglePayMethodData,
} from '@rnw-community/react-native-payments';

const methodData = [
    createApplePayMethodData({ merchantIdentifier: 'merchant.com.your-app', countryCode: 'US', currencyCode: 'USD' }),
    createGooglePayMethodData({
        countryCode: 'US',
        currencyCode: 'USD',
        gatewayConfig: { gateway: 'example', gatewayMerchantId: 'id' },
    }),
];
const paymentRequest = new PaymentRequest(methodData, {
    total: { label: 'Total', amount: { currency: 'USD', value: '10.00' } },
});

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);
}

createApplePayMethodData and createGooglePayMethodData fill in the defaults: Visa and Mastercard on both platforms, plus the Google Pay TEST environment — pass environment: EnvironmentEnum.PRODUCTION for live payments. Each one returns the plain methodData entry, so you can still write that object by hand — see api/ios-payment-method-data.md and api/android-payment-method-data.md for the raw shape.

sendToYourBackend is where your payment service provider comes in — the gateway recipes give the exact method data, token and server call for Stripe, Adyen, Braintree and Checkout.com. 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. createPaymentRequestFactory builds a fresh request per attempt from shared configuration. For 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 · Setup doctor · Troubleshooting
• Gateway recipes — Pick your gateway: Stripe · Adyen · Braintree · Checkout.com · Direct tokenization
• 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 delivers only the shipping 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.