payvessel-checkout/README.md

A simple checkout integration for Payvessel.

# Payvessel Checkout

A lightweight JavaScript SDK for seamless integration of Payvessel's secure checkout flow into your web applications.

## ✨ Features

- Simple, promise-based API for easy async integration
- Easy integration with your existing frontend
- Compatible with React, Next.js, and vanilla JavaScript projects

---


## 📦 Installation

Using npm:

```bash
npm install payvessel-checkout
```

Using Yarn:

```bash
yarn add payvessel-checkout
```

Or via CDN:

```html
<script src="https://unpkg.com/payvessel-checkout@latest/dist/index.umd.js"></script>
```

---


## 🚀 Usage

### Import the package

```bash
import { Checkout } from "payvessel-checkout";
```

### Initialize and launch checkout

```typescript
const openCheckout = async () => {
    const init = Checkout({
        api_key: "YOUR_API_KEY",
    });

    await init.initializeCheckout({
        customer_email: "customer@example.com",
        customer_phone_number: "08012345678",
        amount: "100",
        currency: "NGN",
        channels: [
            "BANK_TRANSFER",
            "CARD",
        ],
        metadata: {
            name: "John Doe",
            email: "doe@john.com"
        },
        customer_name: "Customer Name",
        onError: (error) => console.error(error),
        onSuccess: (response) => console.log(response),
        onSuccessfulOrder: (e) => console.log(e),
        onClose: (e) => console.log(e),
    });
};
```

### Trigger from a button, a form submit event, etc

#### React

```jsx
<button
    className="inline-block bg-orange-500 text-white px-4 py-2.5 font-medium rounded"
    onClick={openCheckout}
>
    Launch Checkout
</button>
```

#### Vanila JavaScript

```html
<button
    className="inline-block bg-orange-500 text-white px-4 py-2.5 font-medium rounded"
    onclick="openCheckout()"
>
    Launch Checkout
</button>
```

### 🧪 Parameters

#### Checkout(config)

| Key        | Type   | Required | Description         |
|------------|--------|----------|---------------------|
| api_key    | string | ✅       | Your public API key |

#### initializeCheckout(options)

| Key        | Type   | Required | Description         |
|------------|--------|----------|---------------------|
| customer_email    | string | ✅       | Customer's email |
| customer_phone_number    | string | ✅       | Customer's phone number |
| amount  | string | ✅       | Amount to charge (e.g., "100") |
| currency  | string | ✅       | Currency code (e.g., "NGN") |
| metadata  | object | ✅       | Any custom metadata object |
| customer_name  | string | ✅       | Full name of the customer |
| channels  | ["BANK_TRANSFER", "CARD"] | ❌       | Optional list of payment channels. Defaults to `BANK_TRANSFER` if not specified.|
| onError  | (orderDetails: ErrorResponse) => void | ❌       | Called when checkout fails. Receives an error object. |
| onSuccess  | (orderDetails: TransactionResponse) => void | ❌       | Called on successful order initialization. Receives order response data. |
| onSuccessfulOrder  | (orderDetails: OrderConfirmedResponse) => void | ❌       | Called after transaction verification succeeds. Receives verified order details. |
| onClose  | (orderReference: string) => void | ❌       | Called when the payment modal is closed. |
| redirect_url  | string | ❌       | URL to redirect to after payment confirmation. |
| reference  | string | ❌       | Unique reference for the transaction. |