@bivo/payment-react-native

A secure, developer-friendly React Native SDK to collect and tokenize card details using Bivo Secure Store.

🚀 Features

• 🔒 PCI-friendly card data collection (no raw data exposure)
• ⚡ Secure tokenization via your backend
• 🧩 Prebuilt, composable input components
• ✅ Built-in validation & state tracking
• 🎨 Fully customizable styles
• 📱 Optimized for React Native apps

📦 Installation

npm install @bivo/payment-react-native
# or
yarn add @bivo/payment-react-native

🧠 Core Concepts

BivoSecureStore

Central controller that:

• Manages field states
• Runs validations
• Controls submit readiness
• Sends tokenized data to your backend

Input Components

| Component | Purpose | |----------|--------| | BivoCardInput | Card number | | BivoTextInput | Expiry / custom fields | | BivoCVCInput | CVV/CVC |

🛠️ Basic Usage

import React, { useRef, useState } from "react";
import { StyleSheet, View, TouchableOpacity, Text } from "react-native";
import {
  BivoSecureStore,
  BivoTextInput,
  BivoCardInput,
  BivoCVCInput,
} from "@bivo/payment-react-native";

function App() {
  const [, setFormVersion] = useState(0);

  const bivoStoreRef = useRef(
    new BivoSecureStore("yourVaultId", "sandbox")
  );

  const bivoStore = bivoStoreRef.current;

  const token = "your token from backend";
  const endpoint = "your backend endpoint";

  const requiredFields = ["cardNumber", "expiryDate", "cvc"];
  const isDisabled = bivoStore.isSubmitDisabled(requiredFields);

  const handleFieldStateChange = () => {
    setFormVersion((value) => value + 1);
  };

  const handleSubmit = async () => {
    const result = await bivoStore.submit(endpoint, token);
    console.log(result);
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Bivo Payment SDK</Text>

      <BivoCardInput
        bivoStore={bivoStore}
        fieldName="cardNumber"
        placeholder="4111 1111 1111 1111"
        required
        onStateChange={handleFieldStateChange}
      />

      <BivoTextInput
        bivoStore={bivoStore}
        fieldName="expiryDate"
        placeholder="MM/YY"
        required
        onStateChange={handleFieldStateChange}
      />

      <BivoCVCInput
        bivoStore={bivoStore}
        fieldName="cvc"
        placeholder="CVC/CVV"
        required
        onStateChange={handleFieldStateChange}
      />

      <TouchableOpacity
        disabled={isDisabled}
        style={[styles.button, isDisabled && styles.disabledButton]}
        onPress={handleSubmit}
      >
        <Text style={styles.buttonText}>Submit</Text>
      </TouchableOpacity>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16, justifyContent: "center" },
  title: { fontSize: 20, fontWeight: "600", marginBottom: 16 },
  button: {
    backgroundColor: "blue",
    padding: 12,
    borderRadius: 6,
    marginTop: 16,
    alignItems: "center",
  },
  disabledButton: { opacity: 0.5 },
  buttonText: { color: "#fff", fontWeight: "600" },
});

export default App;

🧩 Props

Common Props (All Inputs)

| Prop | Type | Description | |------|------|------------| | bivoStore | BivoSecureStore | Store instance managing state and submission | | fieldName | string | Unique field identifier | | placeholder | string | Input placeholder | | required | boolean | Marks field as required | | onStateChange | () => void | Triggered on input state change | | regex | RegExp | Custom validation pattern | | errorMsg | string | Custom error message | | containerStyle | ViewStyle | Wrapper/container style | | textStyle | TextStyle | Input text style |

🧪 Custom Validation Example

<BivoTextInput
  bivoStore={bivoStore}
  fieldName="zip"
  placeholder="ZIP Code"
  required
  regex={/^\\d{5}$/}
  errorMsg="Invalid ZIP Code"
  onStateChange={handleFieldStateChange}
/>

🔐 Submission Flow

1. User enters card details
2. SDK validates each field
3. Form state updates via onStateChange
4. Submit enabled only when valid
5. Call submit:

await bivoStore.submit(endpoint, token);

6. Tokenized data securely sent to backend

✅ Validation

Always pass required field IDs:

const requiredFields = ["cardNumber", "expiryDate", "cvc"];
const isDisabled = bivoStore.isSubmitDisabled(requiredFields);

🔑 Rules

• Field names must match fieldName
• Missing or invalid field → submit disabled
• Always re-trigger validation using onStateChange

🔁 Lifecycle (How it Works)

User Input
   ↓
Field Validation (regex + required)
   ↓
BivoSecureStore State Update
   ↓
isSubmitDisabled() check
   ↓
Submit Button Enabled
   ↓
submit(endpoint, token)
   ↓
Tokenized Payload → Backend

🎨 Styling

<BivoCardInput
  containerStyle={{ borderWidth: 1, borderColor: "#ccc", borderRadius: 6 }}
  textStyle={{ fontSize: 16, padding: 10 }}
/>

🌐 Environment

new BivoSecureStore("vaultId", "sandbox");

| Environment | Description | |------------|------------| | sandbox | Testing | | live | Production |

⚠️ Common Mistakes

❌ Forgetting onStateChange → Form never updates

❌ Mismatched field names → Validation fails silently

❌ Not passing all required fields → Submit always disabled

❌ Hardcoding tokens → Security risk

❌ Using HTTP instead of HTTPS → Requests may fail

🧠 Best Practices

• Always generate token from backend
• Keep vaultId and token secure
• Use strict regex for custom fields
• Log submission response for debugging
• Keep UI responsive with disabled state

🐛 Troubleshooting

Submit button always disabled

• Check requiredFields
• Ensure onStateChange is wired
• Validate regex rules

Input not updating

• Verify bivoStore instance is stable (useRef)

Submission fails

• Check backend endpoint
• Ensure token is valid

📄 License

MIT

🤝 Support

For support, contact your Bivo team or raise an issue in your repository.