zinari-pay/README.md

zinari-pay is a comprehensive package for integrating ZinariPays cryptocurrency payment gateway into web & mobile applications.

<div style="width: 100%;display: flex;align-items: center;justify-content: center;">
<img src="https://pay.zinari.io/logoPurple.webp" alt="Zinari Pay Logo" width="250" height="auto"/>
</div>

# Video Tutorials

[![ZinariPay Tutorials](https://img.youtube.com/vi/Bq4KgiGxoD0/0.jpg)](https://www.youtube.com/watch?v=Bq4KgiGxoD0&list=PLqVphqtb4Bs8McBaiihvZ10Vwb7PJ8WlI)

# Table of Contents

- [Zinari Pay](#zinari-pay)
    - [Links](#links)
    - [Features](#features)
    - [Fee Structure](#fee-structure)
    - [Installation](#installation)
        - [Using npm](#using-npm)
        - [Using yarn](#using-yarn)
    - [Usage](#usage)
        - [Vanilla JavaScript Example](#vanilla-javascript-example)
        - [React Example](#react-example)
    - [Zinari Pay CDN Integration](#zinari-pay-cdn-integration)
    - [Notes](#notes)
    - [Known Issues](#known-issues)
        - [CORS Error](#cors-error)
    - [Happy Coding](#happy-coding)

# Zinari Pay

`zinari-pay` is a secure and easy-to-integrate cryptocurrency payment gateway designed to enable businesses to accept
crypto payments online. It supports stablecoins (USDT & USDC), offers encrypted transaction handling, and provides
seamless integration for developers and business owners.

## Links

- [Official Website](https://pay.zinari.io/)
- [NPM Package](https://www.npmjs.com/package/zinari-pay)
- [Documentation](https://www.npmjs.com/package/zinari-pay)

## Features

- Accept stablecoins payments: USDT & USDC
- Secure encrypted transactions
- Automatic payment components management
- Comprehensive logging for easy debugging
- Real-time transaction status updates
- Easy integration with JavaScript and React
- CDN integration for quick setup

## Fee Structure

ZinariPay charges a straightforward and affordable fee structure:

| Transaction Fee    | Minimum Fee | Maximum Fee |
|--------------------|-------------|-------------|
| 1% per transaction | $1          | $5          |

### Example:

- **Small transactions:** If a customer pays **$50**, the 1% fee would be $0.50. However, due to the $1 minimum, the fee
  charged is **$1**.
- **Large transactions:** If a customer pays **$1,000**, the 1% fee would be $10. However, due to the $5 maximum, the
  fee charged is **$5**.

For detailed pricing information, visit our [Pricing Page](https://pay.zinari.io/pricing).

## Installation

### Using npm

```sh
npm install zinari-pay
```

### Using yarn

```sh
yarn add zinari-pay
```

## Usage

### Vanilla JavaScript Example

```javascript
import ZinariPay from 'zinari-pay';

const zinariPay = new ZinariPay({
  appId: 'your-app-id',
  apiKey: 'your-api-key',
  publicKey: 'your-public-key',
  log: process.env.NODE_ENV === 'development',
});

document.getElementById("your-payment-button").addEventListener("click", () => {
  zinariPay.initiateTransaction({
    amount: 1000,
    notificationEmailAddress: 'user@email.com',
    details: {userId: '123'},
    onSuccess: (transactionDetails) => { /* success action */
    },
    onFailure: (transactionDetails) => { /* failure action */
    },
    onIncomplete: (transactionDetails) => { /* incomplete action */
    },
    onExcess: (transactionDetails) => { /* excess action */
    },
  });
});
```

### React Example

```javascript
import ZinariPay from 'zinari-pay';

const zinariPay = new ZinariPay({
  appId: 'your-app-id',
  apiKey: 'your-api-key',
  publicKey: 'your-public-key',
  log: process.env.NODE_ENV === 'development',
});

const App = () => {
  const handlePayment = () => {
    zinariPay.initiateTransaction({
      amount: 500,
      notificationEmailAddress: 'user@example.com',
      details: {orderId: '567'},
      onSuccess: (transactionDetails) => { /* success action */
      },
      onFailure: (transactionDetails) => { /* failure action */
      },
      onIncomplete: (transactionDetails) => { /* incomplete action */
      },
      onExcess: (transactionDetails) => { /* excess action */
      },
    });
  };

  return <button onClick={handlePayment}>Pay with Crypto</button>;
};
```

## Zinari Pay CDN Integration

```html

<script src="https://cdn.jsdelivr.net/npm/zinari-pay/dist/zinari-pay-cdn-bundle.umd.js"></script>
<script>
    window.zinariPay = new ZinariPay({
        appId: 'your-app-id',
        apiKey: 'your-api-key',
        publicKey: 'your-public-key',
    });
</script>
```

## Notes

- Replace placeholder values (`your-app-id`, `your-api-key`, `your-public-key`) with actual credentials.
- Always ensure script tags use the latest CDN bundle.

## Known Issues

### CORS Error

Resolve by adding your environment URLs to whitelisted URLs in your [ZinariPay console](https://console.zinari.io/).

## Happy Coding

- [CzA](https://christopherakanmu.com/)