Payvessel Checkout

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:

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

Use your public API key (api_key) in frontend code. Keep secret keys server-side only.

Recommended Integration Pattern

For production systems, use this flow:

Create order/session state on your backend first.
Launch checkout from your frontend using payvessel-checkout.
On completion callbacks, verify transaction status on your backend.
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:

npm install payvessel-checkout
# or
yarn add payvessel-checkout

Usage Examples

Vanilla JavaScript
React
Next.js (App Router)

Include the SDK via CDN or bundle it with your app.

<!-- 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>

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>
  );
}

Ensure you use the "use client" directive for the payment component.

"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>
  );
}

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.

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

For technical details, see:

Never mark an order as paid based only on frontend callbacks.

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.

npm install react-native-payvessel react-native-webview
# iOS only
cd ios && pod install

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

iOS SDK (`Payvessel`)

Install with CocoaPods:

pod 'Payvessel', '~> 1.0'

Or Swift Package Manager:

dependencies: [
  .package(url: "https://github.com/Nex-Panther-Technologies-Ltd/payvessel-ios-sdk.git", from: "1.0.0")
]

import Payvessel

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

Reference: Payvessel on CocoaPods

Android SDK (`payvessel-android-sdk`)

Add JitPack and dependency:

dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()
    maven("https://jitpack.io")
  }
}

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

Payvessel.configure(
  PayvesselConfig(
    apiKey = "your_api_key",
    secretKey = "your_secret_key",
    environment = PayvesselEnvironment.SANDBOX
  )
)

Reference: Android SDK on JitPack

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

Getting started

Use cases

API Basics

Accept Payment

Transfers

Wallets

Virtual Accounts

Issuing

Identity Verification

Value Added Services

Webhook

Payvessel Checkout

Overview

Recommended Integration Pattern

Integrating with `payvessel-checkout`

Installation

Usage Examples

Essential Parameters

Callback Behavior

Server-Side Verification

Mobile and Platform SDKs

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

iOS SDK (`Payvessel`)

Android SDK (`payvessel-android-sdk`)

WooCommerce Plugin

Next Steps

Initialize API Reference

Verify API Reference

​Overview

​Recommended Integration Pattern

​Integrating with payvessel-checkout

​Installation

​Usage Examples

​Essential Parameters

​Callback Behavior

​Server-Side Verification

​Mobile and Platform SDKs

​React Native SDK (react-native-payvessel)

​iOS SDK (Payvessel)

​Android SDK (payvessel-android-sdk)

​WooCommerce Plugin

​Next Steps

Initialize API Reference

Verify API Reference

Overview

Recommended Integration Pattern

Integrating with `payvessel-checkout`

Installation

Usage Examples

Essential Parameters

Callback Behavior

Server-Side Verification

Mobile and Platform SDKs

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

iOS SDK (`Payvessel`)

Android SDK (`payvessel-android-sdk`)

WooCommerce Plugin

Next Steps