> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/guides/checkout/implementation-overview/mobile-app-payments/react-native-sdk/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# React Native SDK

## Overview

`@coinflowlabs/react-native` is a React Native SDK that embeds Coinflow's card tokenization form directly into iOS and Android apps from a single TypeScript codebase. The user enters their card inside your app, the SDK returns a payment token, and your backend charges the card via the standard Coinflow checkout API.

* **Package:** [`@coinflowlabs/react-native`](https://www.npmjs.com/package/@coinflowlabs/react-native)
* **Distribution:** npm
* **Current version:** `4.13.0`

## Requirements

* React Native 0.71+ / Expo SDK 50+
* iOS 15+ / Android `minSdk` 24+
* Peer dependency: [`react-native-webview`](https://www.npmjs.com/package/react-native-webview) `>=11.16.0`

## Installation

```bash
npm install @coinflowlabs/react-native react-native-webview
```

For Expo projects, also run:

```bash
npx expo install react-native-webview
```

iOS additionally requires running `pod install` from the `ios/` directory after install (skip if you use Expo's prebuild flow).

## Integration

#### Add the card form component

Render `CoinflowCardForm` and hold a ref you'll use to trigger tokenization.

```tsx
import React, {useRef} from 'react';
import {Button, View} from 'react-native';
import {
  CoinflowCardForm,
  CardFormNativeRef,
} from '@coinflowlabs/react-native';

export function PaymentScreen() {
  const formRef = useRef<CardFormNativeRef>(null);

  const onPay = async () => {
    try {
      const response = await formRef.current?.tokenize();
      console.log('Token:', response?.token);
    } catch (e) {
      // surface error to user
    }
  };

  return (
    <View>
      <CoinflowCardForm
        ref={formRef}
        merchantId="your-merchant-id"
        env="sandbox"
        style={{height: 52}}
      />
      <Button title="Pay" onPress={onPay} />
    </View>
  );
}
```

> **Info**
>
> `your-merchant-id` is an **example placeholder**. Use your actual merchant ID from the merchant dashboard, or contact the Coinflow integrations team. Typically read from your app's config layer, not hard-coded.

#### Configure the environment

```ts
const env = __DEV__ ? 'sandbox' : 'prod';
```

* `'sandbox'` — test cards, no real money
* `'prod'` — live cards, real money

#### Charge the token server-side

`tokenize()` returns a `CardFormTokenResponse`:

* `token: string` — payment token to send to your backend
* `expMonth?: string`, `expYear?: string` — populated only for variants that collect expiry

Send the token to your server and call Coinflow's checkout API to charge it. See the [Card Checkout endpoint](/api-reference/api-reference/checkout/card-checkout) for the full request shape.

## Variants

```tsx
import {
  CoinflowCardForm,        // full card entry (number, expiry, CVV)
  CoinflowCardNumberForm,  // number + expiry only
  CoinflowCvvForm,         // CVV only — requires `token` prop for saved card
} from '@coinflowlabs/react-native';
```

| Component                | Captures            | Use case                                   |
| ------------------------ | ------------------- | ------------------------------------------ |
| `CoinflowCardForm`       | Number, expiry, CVV | Standard one-shot capture                  |
| `CoinflowCardNumberForm` | Number + expiry     | First step of a two-step flow              |
| `CoinflowCvvForm`        | CVV only            | Re-collecting CVV for a card-on-file token |

## Theming

`MerchantTheme` styles the rendered form. All fields optional.

```tsx
import {MerchantTheme} from '@coinflowlabs/react-native';

const theme: MerchantTheme = {
  primary: '#165DFB',
  background: '#ffffff',
  textColor: '#05092E',
  ctaColor: '#165DFB',
  font: 'Red Hat Display',
  style: 'rounded',
};

<CoinflowCardForm theme={theme} /* ... */ />
```

#### All theme fields

| Field                                                              | Purpose                                             |
| ------------------------------------------------------------------ | --------------------------------------------------- |
| `primary`, `ctaColor`                                              | Accent / action colors (hex strings)                |
| `background`, `backgroundAccent`, `backgroundAccent2`              | Form background tones                               |
| `textColor`, `textColorAccent`, `textColorAction`                  | Input and label text colors                         |
| `font`, `fontSize`, `fontWeight`                                   | Typography. `font` must be available on the device. |
| `style`                                                            | Input shape: `'rounded'`, `'sharp'`, `'pill'`       |
| `cardNumberPlaceholder`, `cvvPlaceholder`, `expirationPlaceholder` | Override input placeholder text                     |
| `showCardIcon`                                                     | Toggle the card brand icon (Visa/Mastercard/Amex)   |

## Resources

* **Source:** [github.com/coinflow-labs-us/coinflow-react-native](https://github.com/coinflow-labs-us/coinflow-react-native)
* **npm:** [@coinflowlabs/react-native](https://www.npmjs.com/package/@coinflowlabs/react-native)
* **License:** Apache 2.0
* **Checkout API:** [Card Checkout endpoint](/api-reference/api-reference/checkout/card-checkout)