zinari-pay

v2.0.1

Published

a month ago

zinari-pay is a comprehensive package for integrating Zinari Corps cryptocurrency payment gateway into web applications.

Downloads

260

Zinari Pay

Zinari Pay

zinari-pay is a comprehensive package for integrating Zinari Corps cryptocurrency payment gateway into web applications. This package simplifies the process of adding cryptocurrency payment functionalities, supporting various currencies like USDT & USDC. The package includes encrypted transaction handling and support for various fiat currencies. It is designed to be easy to integrate, providing a seamless experience for developers and end-users.

Features

Supports multiple cryptocurrencies: USDT & USDC
Encrypted transaction handling for secure payments
Support for various fiat currencies
Automatic creation and management of payment components in the DOM
Comprehensive logging for development and debugging
Includes a loader screen and handles transaction status updates

Installation

Using npm

To install the package using npm, run the following command:

npm install zinari-pay

Using yarn

To install the package using Yarn, run the following command:

yarn add zinari-pay

Usage

Vanilla JavaScript Example

ZinariPayConfig

There are only three required properties in the ZinariPayConfig object. The appId, apiKey & publicKey are gotten from your ZinariPay dashboard. The log property is optional and defaults to false. It logs important details about the transaction processes in the browser console.

| Property | Type | Required | Notes | |-----------|---------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | appId | string | Yes | Get from your ZinariPay dashboard | | apiKey | string | Yes | Get from your ZinariPay dashboard | | publicKey | string | Yes | Get from your ZinariPay dashboard | | log | boolean | No | Logs important details about the transaction processes in the browser console. Defaults to false.NB: This may include sensitive data. Only use for development. |

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', /** Recommendation: Only use for development
   to avoid exposing sensitive data to end users
   */
});

const payWithCryptoButton = document.getElementById("your-payment-button");

payWithCryptoButton.addEventListener("click", () => {
  zinariPay.initiateTransaction({
    amount: 10000,
    notificationEmailAddress: '[email protected]',
    details: {
      /** Add all the extra details you need here,
       * we  call your webhook url with all this data included */
    },
    onConfirmed: (transactionDetails) => {
      /** Do something when the transaction is confirmed, failed, cancelled, incomplete or excess */
    },
    onSuccess: (transactionDetails) => {
      /** Do something when the transaction is confirmed, incomplete or excess */
    },
    onFailure: (transactionDetails) => {
      /** Do something when the transaction is failed or cancelled */
    }
  });
});

zinariPay.initiateTransaction Method

This method is used to initiate a transaction. It takes a single argument, an object with the following properties:

| Property | Type | Required | Notes | |--------------------------------------|----------------------------------------------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | amount | number | Yes | The amount in fiat. Whatever fiat currency you have set on your dashboard will be used. For example, if your app currency is set to USD, then passing 1000 here will mean $1000, and will be converted to the users crypto currency of choice during payment | | details | object | No | All the details you need to identify a payer. e.g userId, email, productId etc. Whe a transaction is confirmed, we will call your webhook endpoint with this data so the you can easily identify which of your customers made a payment | | closeOnCompleted | boolean | No | Defaults to false. Closes the payment screen automatically when the transaction is confirmed | | notificationEmailAddress | string | No | If you do not provide a notificationEmailAddress, the user will be presented with a screen to enter their email in order to receive payment notifications | | onConfirmed | (values: TransactionStatusResponse) => void | No | We will call this function once a payment is confirmed, failed, cancelled, incomplete or excess with the following values so that you can perform some action on the frontend like redirecting the user to a success page. The function will be called with the following values | | onSuccess | (values: TransactionStatusResponse) => void | No | We will call this function once a payment is confirmed, incomplete or excess with the following values so that you can perform some action on the frontend like redirecting the user to a success page. The function will be called with the following values | | onFailure | (values: TransactionStatusResponse) => void | No | We will call this function once a payment is failed or cancelled confirmed with the following values so that you can perform some action on the frontend like redirecting the user to a success page. The function will be called with the following values |

React Example

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 handleClick = useCallback(({price, email}) => {
    zinariPay.initiateTransaction({
      amount: price,
      notificationEmailAddress: email,
      onConfirmed: (transactionDetails) => {
        /** Do something when the transaction is confirmed, failed, cancelled, incomplete or excess */
      },
      onSuccess: (transactionDetails) => {
        /** Do something when the transaction is confirmed, incomplete or excess */
      },
      onFailure: (transactionDetails) => {
        /** Do something when the transaction is failed or cancelled */
      },
      details: {
        /** Add all the extra details you need here,
         * we  call your webhook url with all this data included */
      },
    });
  }, []);

  return <button onClick={handleClick}>
    Pay with Cryptocurrency
  </button>
}

onConfirmed Callback

This function is called once a payment is confirmed, failed, cancelled, incomplete or excess. You can use this callback to perform actions on the frontend, such as redirecting the user to a success page, or providing value. The function will be called with the following parameters:

| Property | Type | Example | |-------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | status | AppTransactionStatus | confirmed - User paid complete amount and the blockchain transaction has been confirmedexcess - User over paid, you'll have to provide a refundincomplete - User underpaid and will have to complete the paymentfailed - Payment failed to complete on the blockchain | | cryptocurrencyAmount | number | 1 (The amount of crypto that the user should send) | | blockchainConfirmations | number | 12 | | blockchainTransactionId | string | 100458ac66fc5f5e3dab837bd47f5c1034ea1d170c5dcc04b41bd76e2bed8eb | | cryptocurrency | CryptoCurrency | BTC | | fiatCurrency | FiatCurrency | USD | | fiatAmount | number | 56000 (Calculated with the exchange rate at the time of the transaction) | | webhookUrlCalled | boolean | true (If you have provided a webhook URL in your app settings, then we will call that URL with transaction updates) | | amountReceived | number | 1 (The actual amount of crypto the user sent) | | details | any | { userId: '44f4-de3a-er4e-ea34', productId: '43d4-de3a-er2e-ea34' } |

Zinari Pay CDN Integration

The Zinari Pay CDN Bundle provides an easy way to integrate cryptocurrency payment functionalities into your web applications. This guide walk you through the steps to integrate Zinari Pay using the CDN version.

Installation

To use the CDN version, simply include the following script tag in your HTML file:


<script src="https://cdn.jsdelivr.net/npm/zinari-pay/dist/zinari-pay-cdn-bundle.umd.js"></script>

You can also use UNPKG as an alternative:


<script src="https://unpkg.com/zinari-pay/dist/zinari-pay-cdn-bundle.umd.js"></script>

CDN Usage

Create a New Instance

After including the script tag, you create a new instance of ZinariPay using the window object. This makes the instance accessible globally within your application.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Zinari Pay Integration</title>
</head>
<body>
<!-- Your content -->

<!-- Include the Zinari Pay CDN Bundle -->
<script src="https://cdn.jsdelivr.net/npm/zinari-pay/dist/zinari-pay-cdn-bundle.umd.js"></script>
<script>
    // Create a new instance of ZinariPay
    window.zinariPay = new ZinariPay({
        appId: 'your-app-id',
        apiKey: 'your-api-key',
        publicKey: 'your-public-key',
    });
</script>
</body>
</html>

Access the Instance from a JavaScript File

You can access the ZinariPay instance from within any JavaScript file using the window object. This allows you to interact with the instance and call its methods.

// Access the ZinariPay instance
const zinariPayInstance = window.zinariPay;

// Example: Initiate a transaction
zinariPayInstance.initiateTransaction({
  amount: 100,
  details: {orderId: '#1234', description: 'Purchase Order #1234'},
  onConfirmed: (response) => {
    /** Do something when the transaction is confirmed, failed, cancelled, incomplete or excess */
  },
  onSuccess: (transactionDetails) => {
    /** Do something when the transaction is confirmed, incomplete or excess */
  },
  onFailure: (transactionDetails) => {
    /** Do something when the transaction is failed or cancelled */
  },
});

Supported Fiat Currencies

These are the base fiat currencies you can set for your app. When a payment is made, we automatically convert the fiat amount to the corresponding crypto value e.g. USDT, for the transaction.

| Currency Name | Symbol | |-----------------------------|--------| | Nigerian Naira | ₦ | | South African Rand | R | | United States Dollar | $ | | Canadian Dollar | $ | | Euro | € | | British Pound | £ | | Indian Rupee | ₹ | | United Arab Emirates Dirham | د.إ |

Notes

Replace your-app-id, your-api-key and your-public-key with your actual appId, apikey & public key.
Ensure that the script tag URL points to the latest version or a specific version of the CDN bundle.
The ZinariPay instance is available globally via the window object.

Known Issues

CORS Error

If you encounter a CORS error during integration, you can resolve it by visiting your console. Navigate to the API section under the App settings and add your development/live environment to the whitelisted URLs.

By following these steps, you easily integrate the ZinariPay into your web application and start accepting cryptocurrency payments.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Table of Contents

Zinari Pay

Links

Features

Installation

Using npm

Using yarn

Usage

Vanilla JavaScript Example

ZinariPayConfig

zinariPay.initiateTransaction Method

React Example

onConfirmed Callback

Zinari Pay CDN Integration

Installation

CDN Usage

Create a New Instance

Access the Instance from a JavaScript File

Supported Fiat Currencies

Notes

Known Issues

CORS Error

Happy Coding