54pay-payments-sdk

54pay-payment-sdk

A JavaScript/TypeScript SDK for accepting payments via 54Pay. This release covers the Nigeria (NGN) checkout: Bank Transfer, OPay, PalmPay and Kuda.

Installation

npm install 54pay-payment-sdk
# or
yarn add 54pay-payment-sdk

react, react-dom and styled-components are peer dependencies — install them in your app if you haven't already:

npm install react react-dom styled-components

Usage

The SDK mounts the checkout into a DOM element you provide via its id.

ES module / bundler (React, Vite, Next.js, etc.)

import { FiftyFourPayPaymentSdk } from "54pay-payment-sdk";

FiftyFourPayPaymentSdk.setup({
  targetId: "checkout-container", // id of an element already in the DOM
  props: {
    userData: {
      amount: 1000,
      transactionRef: "ORDER_12345",
      merchantPublicKey: "PK-…",
      countryCode: "NGA",
      currencyCode: "NGN",
      transactionCurrency: "NGN",
      firstName: "Ada",
      lastName: "Obi",
      email: "ada@example.com",
      phoneNumber: "8160009000",
    },
    config: { environment: "live", theme: "light" },
    onSuccess: (transactionId) => console.log("paid", transactionId),
    onError: (error) => console.error("payment failed", error),
  },
});

<div id="checkout-container"></div>

Script tag (CDN / global)

<script src="https://cdn.jsdelivr.net/npm/54pay-payment-sdk/dist/index.iife.js"></script>
<div id="checkout-container"></div>
<script>
  window["54PaySdk"].setup({
    targetId: "checkout-container",
    props: {
      userData: {
        amount: 1000,
        transactionRef: "ORDER_12345",
        merchantPublicKey: "PK-…",
        countryCode: "NGA",
        currencyCode: "NGN",
        firstName: "Ada",
        lastName: "Obi",
        email: "ada@example.com",
        phoneNumber: "8160009000",
      },
      config: { environment: "live" },
      onSuccess: (transactionId) => console.log("paid", transactionId),
    },
  });
</script>

API

FiftyFourPayPaymentSdk.setup({ targetId, props })

props

userData (MerchantDataProps)

Required

Common optional fields: merchantName, merchantReference, transactionDescription, redirectUrl, successUrl, errorUrl, cancelUrl, webhookUrl, customerAddress, customerCity, customerState, metadataOrderId, metadataProductInfo. See the exported MerchantDataProps type for the full list.

Environments

config.environment selects the backend:

• "test" → 54Pay test environment
• "live" → 54Pay production environment

If omitted, the SDK defaults to the test environment.

Supported regions

The region is resolved from userData.countryCode and/or userData.currencyCode / transactionCurrency.

Because XAF is shared across the six-country CFA zone, Cameroon is resolved from countryCode — send "CMR" (or "CM") to get the Cameroon profile.

If you pass an unsupported country/currency, the checkout will not mount — instead onError is called with:

{ code: "UNSUPPORTED_REGION", message: "…" }

License

MIT