> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payvessel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payvessel Checkout

> Hosted checkout for cards and bank transfer: integrate with the payvessel-checkout npm package or Merchant Checkout API

**Accept payments with minimal integration** using Payvessel's hosted checkout. Customers can pay with **card** or **bank transfer** in a single modal. Ideal for e-commerce, donations, and subscriptions.

## Overview

Payvessel Checkout provides a secure, conversion-optimized payment interface. You can integrate it in two ways:

1. **npm package (Recommended):** A lightweight frontend SDK that handles the modal UI and payment channels.
2. **Merchant Checkout API:** A server-side integration for custom redirects or backend-driven flows.

<Info>
  Use your **public API key** (`api_key`) in frontend code. Keep secret keys server-side only.
</Info>

### Recommended Integration Pattern

For production systems, use this flow:

1. Create order/session state on your backend first.
2. Launch checkout from your frontend using `payvessel-checkout`.
3. On completion callbacks, verify transaction status on your backend.
4. Fulfill value (goods/services/wallet credit) **only after successful server-side verification**.

***

## Integrating with `payvessel-checkout`

The `payvessel-checkout` package is the fastest way to add payment capabilities to your web application.

### Installation

Install the package via npm or Yarn:

```bash theme={null}
npm install payvessel-checkout
# or
yarn add payvessel-checkout
```

### Usage Examples

<Tabs>
  <Tab title="Vanilla JavaScript">
    Include the SDK via CDN or bundle it with your app.

    ```html theme={null}
    <!-- Via CDN -->
    <script src="https://unpkg.com/payvessel-checkout@latest/dist/index.umd.js"></script>

    <script>
      const openCheckout = async () => {
        const init = PayvesselCheckout.Checkout({
          api_key: "YOUR_PUBLIC_API_KEY",
        });

        await init.initializeCheckout({
          customer_email: "customer@example.com",
          customer_name: "John Doe",
          customer_phone_number: "08012345678",
          amount: "5000",
          currency: "NGN",
          channels: ["BANK_TRANSFER", "CARD"],
          onSuccess: (response) => {
            console.log("Initialization Successful", response);
          },
          onSuccessfulOrder: (orderDetails) => {
            console.log("Payment Successful", orderDetails);
            // Verify payment on your server
          },
          onError: (error) => {
            console.error("Checkout Error", error);
          },
          onClose: () => {
            console.log("Checkout Closed");
          }
        });
      };
    </script>

    <button onclick="openCheckout()">Pay Now</button>
    ```
  </Tab>

  <Tab title="React">
    ```jsx theme={null}
    import { Checkout } from 'payvessel-checkout';

    function PaymentButton() {
      const handlePayment = async () => {
        const init = Checkout({
          api_key: 'YOUR_PUBLIC_API_KEY',
        });

        await init.initializeCheckout({
          customer_email: 'user@example.com',
          customer_phone_number: '08012345678',
          customer_name: 'Jane Smith',
          amount: '1000',
          currency: 'NGN',
          metadata: { order_id: 'ORD-1001' },
          channels: ['BANK_TRANSFER', 'CARD'],
          onSuccessfulOrder: (data) => {
            alert('Payment received!');
            console.log(data);
          },
          onClose: () => console.log('User closed the modal'),
        });
      };

      return (
        <button onClick={handlePayment}>
          Checkout with Payvessel
        </button>
      );
    }
    ```
  </Tab>

  <Tab title="Next.js (App Router)">
    Ensure you use the `"use client"` directive for the payment component.

    ```tsx theme={null}
    "use client";

    import { Checkout } from 'payvessel-checkout';

    export default function CheckoutComponent() {
      const startPayment = async () => {
        const init = Checkout({
          api_key: process.env.NEXT_PUBLIC_PAYVESSEL_KEY!,
        });

        await init.initializeCheckout({
          customer_email: 'customer@email.com',
          customer_phone_number: '08012345678',
          customer_name: 'Customer Name',
          amount: '2500',
          currency: 'NGN',
          metadata: { order_id: 'ORD-2500' },
          channels: ['BANK_TRANSFER', 'CARD'],
          onSuccessfulOrder: (response) => {
            // Handle success
          },
        });
      };

      return (
        <button onClick={startPayment}>
          Pay Now
        </button>
      );
    }
    ```
  </Tab>
</Tabs>

### Essential Parameters

| Parameter               | Type   | Required | Description                                               |
| ----------------------- | ------ | -------- | --------------------------------------------------------- |
| `api_key`               | string | Yes      | Your Public API Key from the dashboard.                   |
| `customer_email`        | string | Yes      | The customer's email address.                             |
| `customer_phone_number` | string | Yes      | The customer's phone number.                              |
| `customer_name`         | string | Yes      | The customer's full name.                                 |
| `amount`                | string | Yes      | Amount to charge in naira (e.g., "100" for ₦100.00).      |
| `currency`              | string | Yes      | Currency code, default is `NGN`.                          |
| `metadata`              | object | Yes      | Attach order context (for example, order id and cart id). |
| `channels`              | array  | No       | Payment methods: `["BANK_TRANSFER", "CARD"]`.             |
| `reference`             | string | No       | Your unique transaction reference.                        |

### Callback Behavior

| Callback            | When It Fires                                                            | Recommended Action                                  |
| ------------------- | ------------------------------------------------------------------------ | --------------------------------------------------- |
| `onSuccess`         | Initialization succeeds (checkout session created)                       | Log and track for observability.                    |
| `onSuccessfulOrder` | Customer completes payment and transaction is confirmed in checkout flow | Call your backend to verify and then fulfill value. |
| `onError`           | Checkout initialization/payment flow encounters an error                 | Show user-friendly error and allow retry.           |
| `onClose`           | User closes the modal                                                    | Preserve cart/session and allow resume.             |

***

## Server-Side Verification

After a successful payment, always verify the transaction on your server before providing value to the customer.

1. Listen for webhooks from Payvessel.
2. Or use the **Verify Transaction** API to check the status manually.

For technical details, see:

* [Verify Payment](/api-reference/transactions/verify-payment)
* [Webhook Basics](/api-basics/webhooks)

<Warning>
  Never mark an order as paid based only on frontend callbacks.
</Warning>

***

## Mobile and Platform SDKs

If you are not integrating with a web frontend, use the SDK that matches your platform.

### React Native SDK (`react-native-payvessel`)

Use this SDK for React Native apps with in-app modal checkout.

```bash theme={null}
npm install react-native-payvessel react-native-webview
# iOS only
cd ios && pod install
```

```tsx theme={null}
import React, { useState } from "react";
import { View, Button } from "react-native";
import PayvesselCheckout from "react-native-payvessel";

export default function App() {
  const [visible, setVisible] = useState(false);

  return (
    <View style={{ flex: 1 }}>
      <Button title="Pay with Payvessel" onPress={() => setVisible(true)} />
      <PayvesselCheckout
        visible={visible}
        apiKey="YOUR_API_KEY"
        customerEmail="customer@example.com"
        customerPhoneNumber="08012345678"
        customerName="John Doe"
        amount={1000}
        currency="NGN"
        channels={["BANK_TRANSFER", "CARD"]}
        onSuccess={() => setVisible(false)}
        onError={(error) => console.error(error)}
        onClose={() => setVisible(false)}
      />
    </View>
  );
}
```

Reference: [react-native-payvessel on npm](https://www.npmjs.com/package/react-native-payvessel)

### iOS SDK (`Payvessel`)

Install with CocoaPods:

```ruby theme={null}
pod 'Payvessel', '~> 1.0'
```

Or Swift Package Manager:

```swift theme={null}
dependencies: [
  .package(url: "https://github.com/Nex-Panther-Technologies-Ltd/payvessel-ios-sdk.git", from: "1.0.0")
]
```

```swift theme={null}
import Payvessel

Payvessel.shared.configure(with: PayvesselConfig(
  apiKey: "your_api_key",
  secretKey: "your_secret_key",
  environment: .sandbox
))
```

Reference: [Payvessel on CocoaPods](https://cocoapods.org/pods/Payvessel)

### Android SDK (`payvessel-android-sdk`)

Add JitPack and dependency:

```kotlin theme={null}
dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()
    maven("https://jitpack.io")
  }
}
```

```kotlin theme={null}
dependencies {
  implementation("com.github.Nex-Panther-Technologies-Ltd:payvessel-android-sdk:1.0.0")
}
```

```kotlin theme={null}
Payvessel.configure(
  PayvesselConfig(
    apiKey = "your_api_key",
    secretKey = "your_secret_key",
    environment = PayvesselEnvironment.SANDBOX
  )
)
```

Reference: [Android SDK on JitPack](https://jitpack.io/#Nex-Panther-Technologies-Ltd/payvessel-android-sdk/1.0.0)

### WooCommerce Plugin

For WordPress stores, install the official WooCommerce plugin and add your Payvessel keys in WooCommerce payment settings.

Reference: [Payvessel Payment Gateway for WooCommerce](https://wordpress.org/plugins/payvessel-payment-gateway-for-woocommerce/)

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Initialize API Reference" icon="code" href="/api-reference/transactions/initialize-payment">
    Request/response schemas for server-side integration.
  </Card>

  <Card title="Verify API Reference" icon="shield-check" href="/api-reference/transactions/verify-payment">
    How to confirm payments accurately.
  </Card>
</CardGroup>