# Bivo Payment SDK

**Package:** `@bivoglobal/bivo-payment`

The **Bivo Payment SDK** is a lightweight and secure JavaScript library
that enables partners to collect card details without directly
handling sensitive cardholder data.

By using **session-based tokenization and secure hosted components**,
the SDK ensures that **Primary Account Numbers (PAN), CVV, and other
card data never pass through your infrastructure**, significantly
reducing your **PCI DSS compliance scope**.

This approach allows partners to integrate card payments quickly while
maintaining strong security guarantees.

---

# Key Benefits

## 🔐 PCI Scope Reduction

Sensitive cardholder data is captured and transmitted **directly to
Bivo's PCI-compliant infrastructure**, ensuring your backend and
frontend never store or process raw card data.

## ⚡ Developer‑First Integration

The SDK is designed for rapid integration with minimal configuration and
clean APIs.

## 📦 Framework Flexibility

Works seamlessly with:

- Vanilla JavaScript
- React
- React Native
- Any framework capable of mounting a DOM container

## 🧩 Embedded & Customizable UI

Secure payment components are mounted within your application using
hosted frames that can visually blend into your interface.

---

# Architecture Overview

The Bivo SDK follows a **No‑Touch Card Data Architecture**.

1.  **Your Backend**
    - Requests a `sessionId` from Bivo.
2.  **Your Frontend**
    - Initializes the Bivo SDK using the `sessionId`.
3.  **Bivo SDK**
    - Renders a secure card collection component inside your
      application.
4.  **Bivo Payment Gateway**
    - Processes the card data and returns a success or failure event.

Because the card details are submitted **directly from the user's
browser to Bivo**, your infrastructure **never handles PCI‑sensitive
data**.

---

# Installation

Install the SDK using your preferred package manager.

```bash
npm install @bivoglobal/bivo-payment

# or

yarn add @bivoglobal/bivo-payment
```

## CDN / Script Tag

For HTML pages without a bundler, load the UMD build and stylesheet directly:

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@bivoglobal/bivo-payment@latest/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@bivoglobal/bivo-payment@latest/dist/index.umd.js"></script>
```

The global `BivoPayments` object is then available on `window`.

---

# Quick Start

## 1. Create a Payment Session (Server‑Side)

Before initializing the SDK, your backend must create a **payment
session** with Bivo.

This session prevents client‑side manipulation and authenticates the
transaction.

### Endpoint

    POST /api-gateway/v1/admin/cards/link-card

### Example Response

```json
{
  "sessionId": "sess_abc123",
  "endpoint": "{{host}}/pgw/v1/card"
}
```

Your backend should then pass this `sessionId` to the frontend.

---

# Frontend Implementation (Web)

## Vanilla JavaScript (Inline + Modal)

```javascript
import * as BivoPayments from "@bivoglobal/bivo-payment";
import "@bivoglobal/bivo-payment/style.css";

const onCallback = (result) => {
  if (result.success) console.log("Success:", result.data);
  else console.error("Error:", result.error);
};

// Inline mode
const bivoInline = BivoPayments.init({
  token: "your-session-token",
  endpoint: "your-endpoint",
  beneficiaryCard: false,
  onCallback,
});
bivoInline.mount({ id: "payment-container" });

// Modal mode
const bivoModal = BivoPayments.init({
  token: "your-session-token",
  endpoint: "your-endpoint",
  beneficiaryCard: false,
  isModal: true,
  onCallback,
});
document.getElementById("open-modal")?.addEventListener("click", () => bivoModal.open());

// bivoInline.destroy() / bivoModal.destroy()
```

`mount()` accepts `{ id }`, `{ className }` (CSS selector string), or `{ element }`.

## React

```jsx
import { useState } from "react";
import { AddCard } from "@bivoglobal/bivo-payment/react";
import "@bivoglobal/bivo-payment/style.css";

export default function PaymentPage() {
  const [isOpen, setIsOpen] = useState(false);

  const onCallback = (result) => {
    if (result.success) { console.log("Success:", result.data); setIsOpen(false); }
    else console.error("Error:", result.error);
  };

  return (
    <>
      {/* Inline */}
      <AddCard token="..." endpoint="..." onCallback={onCallback} />

      {/* Beneficiary flow */}
      <AddCard token="..." endpoint="..." beneficiaryCard onCallback={onCallback} />

      {/* Modal */}
      <button onClick={() => setIsOpen(true)}>Add Card</button>
      <AddCard isModal isOpen={isOpen} token="..." endpoint="..." onCallback={onCallback} onClose={() => setIsOpen(false)} />
    </>
  );
}
```

## React Native

Import `AddCard` from `@bivoglobal/bivo-payment/native`. Renders a native card form — no WebView required.

```jsx
import { AddCard } from "@bivoglobal/bivo-payment/native";

<AddCard
  token="your-session-token"
  endpoint="your-endpoint"
  beneficiaryCard={false}   // set true for recipient card flow
  onCallback={(result) => {
    if (result.success) console.log("Card linked:", result.data);
    else console.error("Error:", result.error);
  }}
/>
```

---

# API Reference

## `init(options)` — Vanilla JS

Options:

- `token` (string, required)
- `endpoint` (string, required)
- `beneficiaryCard` (boolean, default `false`)
- `isModal` (boolean, default `false`)
- `onCallback` (function)
- `onModalClose` (function)

Returns: `mount(selector)`, `open()`, `destroy()`

## `AddCard` Props — React / React Native

| Prop | Type | React | Native | Notes |
|---|---|---|---|---|
| `token` | string | required | required | |
| `endpoint` | string | required | required | |
| `beneficiaryCard` | boolean | optional | optional | default `false` |
| `isModal` | boolean | optional | — | |
| `isOpen` | boolean | optional | — | modal open state |
| `onCallback` | function | optional | optional | `{ success, data?, error? }` |
| `onClose` | function | optional | — | called on modal close |
| `lang`            | `"en"` \| `"es"` | optional | optional | UI language, default `"en"`  |

---

# Error Reference

  -------------------------------------------------------------------------
  Error Code           Description          Recommended Action
  -------------------- -------------------- -------------------------------
  `invalid_session`    Provided sessionId   Verify backend session creation
                       is malformed or      
                       invalid              

  `expired_session`    Session has expired  Request a new sessionId

  `payment_declined`   Card issuer rejected Prompt user for another card
                       the transaction      

---

# Security & PCI Compliance

The Bivo SDK is designed to keep partner infrastructure **outside of PCI
scope whenever possible**.

### Key Security Principles

**Zero Card Data Exposure** - Your frontend and backend never see PAN or
CVV.

**Direct Secure Submission** - Card data is transmitted directly from
the user's browser to Bivo.

**PCI Level 1 Infrastructure** - Bivo stores and processes card data
inside a certified PCI environment.

**Tokenized Transactions** - All follow‑up operations use **session
tokens**, not card data.

This architecture significantly reduces compliance overhead for partners
while maintaining enterprise‑grade security.

---

# Support

For integration assistance, sandbox credentials, or enterprise
onboarding, contact:

**Bivo Developer Support**\
developers@bivocash.com

---

# License

MIT