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.

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:

<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

{
  "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)

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

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.

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
[email protected]

License

MIT