Sign inCreate account

@valuepay/react

Overview

Official React SDK for ValuePay. Accept payments in your React or Next.js app with minimal setup using the npm package.

This page documents the npm SDK. If you want inline script integration instead, use the React/Next.js (Script) page.

Installation

npm install @valuepay/react # or yarn add @valuepay/react # or pnpm add @valuepay/react

Requirements

  • React >= 16.8.0 (hooks support required)
  • React DOM >= 16.8.0

Quick Start

You can integrate the SDK in three ways: drop-in button, hook-based flow, or provider with ref.

Drop-in Button

components/Checkout.tsx
import { ValuePayButton } from "@valuepay/react"; export default function Checkout() { return ( <ValuePayButton publicKey="KP_your_public_key" amount={5000} customer={{ email: "jane@example.com", fullName: "Jane Doe" }} onSuccess={(response) => { console.log("Payment successful!", response.ref, response.status); }} onClose={(response) => { console.log("Checkout closed", response); }} onCancelled={(response) => { console.log("Payment cancelled", response); }} /> ); }

The default button text is Pay ₦{amount} Now. You can customize text, children, className, and style.

Hook Integration

components/Checkout.tsx
import { useValuePay } from "@valuepay/react"; export default function Checkout() { const { initialize, isReady, isProcessing } = useValuePay({ publicKey: "KP_your_public_key", amount: 10000, customer: { email: "john@example.com", fullName: "John Doe" }, onSuccess: (response) => console.log("Paid!", response), onCancelled: (response) => console.log("Cancelled", response), onClose: (response) => console.log("Closed", response), }); return ( <button onClick={() => initialize()} disabled={!isReady || isProcessing}> {isProcessing ? "Processing..." : "Pay ₦10,000"} </button> ); }

Provider with Ref

components/Checkout.tsx
import { useRef } from "react"; import { ValuePayProvider, ValuePayProviderRef } from "@valuepay/react"; export default function Checkout() { const payRef = useRef<ValuePayProviderRef>(null); return ( <> <ValuePayProvider ref={payRef} config={{ publicKey: "KP_your_public_key", amount: 7500, customer: { email: "alice@example.com", fullName: "Alice Smith" }, onSuccess: (response) => console.log("Success!", response), onCancelled: (response) => console.log("Cancelled", response), }} /> <button onClick={() => payRef.current?.initialize()}>Checkout</button> </> ); }

Redirect Mode

Use redirectUrl to send users to your verification page after checkout.

<ValuePayButton publicKey="KP_your_public_key" amount={5000} customer={{ email: "jane@example.com", fullName: "Jane Doe" }} redirectUrl="https://yoursite.com/payment/verify" />

After payment, ValuePay redirects with query params such as ref and status.

API Reference

useValuePay(config: ValuePayConfig)
  • initialize(overrides?) => void
  • isReady: boolean
  • isProcessing: boolean
ValuePayButton

Extends ValuePayConfig and supports optional UI props: text, className, style, containerStyle, containerClassName, disabled, and children.

ValuePayConfig
  • publicKey, amount, customer are required
  • currency defaults to NGN
  • channels defaults to card, transfer, qrcode, ussd
  • transactionRef supports custom references (VPS_TX_ is auto-prepended if missing)
  • Supports redirectUrl, metaData, customization, and callbacks
ValuePayResponse

Includes ref, transactionRef, status, amount, currency, customer, paymentMethod, validation, and raw payload.

Dynamic Amounts

const { initialize } = useValuePay({ publicKey: "KP_xxx", amount: 0, customer: { email: "user@example.com", fullName: "User" }, onSuccess: (res) => console.log(res), }); initialize({ amount: selectedProduct.price });

Payment Channels

  • card
  • transfer
  • qrcode
  • ussd
  • mobile_money

Checkout Customization

<ValuePayButton publicKey="KP_xxx" amount={2000} customer={{ email: "user@example.com", fullName: "User" }} customization={{ title: "My Store", description: "Thanks for shopping with us!", logoUrl: "https://mystore.com/logo.png", }} onSuccess={(res) => console.log(res)} />

Server Verification

Always verify payments on your server using the ref from the SDK response before fulfilling an order.

const response = await fetch("https://api.valuepayng.com/v1/transactions/verify", { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${VALUEPAY_SECRET_KEY}`, }, body: JSON.stringify({ tx_ref: transactionRef }), }); const result = await response.json();

TypeScript

The package exports first-class types for configuration, responses, channels, status values, hook return type, and component props.

import type { ValuePayConfig, ValuePayResponse, PaymentChannel, ValuePayStatus, UseValuePayReturn, ValuePayButtonProps, ValuePayProviderProps, ValuePayProviderRef, } from "@valuepay/react";

Browser and SSR Support

The SDK targets modern browsers and supports SSR frameworks like Next.js (Pages and App Router), Remix, and Gatsby.

DOM access is guarded with runtime checks so it can run safely in server-rendered environments.

Security

  • Use only your public key in client-side code.
  • Never expose your ValuePay secret key on the frontend.
  • Always verify transactions server-side.
  • Use HTTPS in production.
  • Allow https://www.valuepayng.com in CSP for script-src and frame-src.

Error Handling

<ValuePayButton publicKey="KP_xxx" amount={5000} customer={{ email: "user@example.com", fullName: "User" }} onError={(error) => { console.error("Payment SDK error:", error.message); }} onSuccess={(res) => console.log(res)} />

Common causes include script loading failures, CSP blocking, and invalid runtime configuration.

Need help? Check out the React/Next.js (Script) page or Authentication docs.

ON THIS PAGE

© Copyright 2026

Terms of ServicePrivacy PolicyAbout Us