# 54pay-payment-sdk

A JavaScript/TypeScript SDK for accepting payments via [54Pay](https://github.com/MYPAYGATE/web-sdk). This release covers the **Nigeria (NGN)** checkout: Bank Transfer, OPay, PalmPay and Kuda.

## Installation

```bash
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:

```bash
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.)

```ts
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),
  },
});
```

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

### Script tag (CDN / global)

```html
<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 })`

| Field      | Type                      | Description                                          |
| ---------- | ------------------------- | ---------------------------------------------------- |
| `targetId` | `string`                  | `id` of the DOM element to render the checkout into. |
| `props`    | `PaygateCheckoutSdkProps` | Checkout configuration (see below).                  |

### `props`

| Field       | Type                               | Required | Description                                                                    |
| ----------- | ---------------------------------- | -------- | ------------------------------------------------------------------------------ |
| `userData`  | `MerchantDataProps`                | yes      | Transaction + customer details (see below).                                    |
| `config`    | `{ environment?, theme?, … }`      | no       | `environment: "test" \| "live"` (default `test`), `theme: "light" \| "dark"`.  |
| `onSuccess` | `(transactionId?: string) => void` | no       | Called once when the payment completes.                                        |
| `onError`   | `(error?: unknown) => void`        | no       | Called once when the payment fails.                                            |

### `userData` (`MerchantDataProps`)

**Required**

| Field                                           | Type     | Notes                                                                                                                                                          |
| ----------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`                                        | `number` | Must be a positive number.                                                                                                                                     |
| `transactionRef`                                | `string` | Your unique reference. Used as the recovery key.                                                                                                               |
| `merchantPublicKey`                             | `string` | Your 54Pay public key, used for API auth.                                                                                                                      |
| country / currency                              | `string` | Provide at least one of `countryCode` (e.g. `"NGA"`), `currencyCode` (e.g. `"NGN"`) or `transactionCurrency` so the SDK can resolve the country profile. |
| `firstName`, `lastName`, `email`, `phoneNumber` | `string` | Customer details.                                                                                                                                              |

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

This release supports **Nigeria (NGN)** only. The region is resolved from `userData.countryCode` (`"NGA"`) and/or `userData.currencyCode` / `transactionCurrency` (`"NGN"`).

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

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

## Supported payment methods (Nigeria)

- Bank Transfer (dynamic virtual account)
- OPay
- PalmPay
- Kuda

## License

MIT