zinari-pay

v1.0.37

Published

12 days ago

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

Downloads

1,569

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 two required properties in the ZinariPayConfig object. The appId and 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 | | 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',
  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 */
    }
  });
});

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 fully 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',
  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 */
      },
      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 fully confirmed. 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 payment | | 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>

Usage

Step 1: 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',
        publicKey: 'your-public-key',
    });
</script>
</body>
</html>

Step 2: 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) => {
    console.log('Transaction Confirmed:', response);
  },
});

Supported Fiat Currencies

This is a list of all the fiat currencies we currently support.

| Currency Name | Symbol | |-----------------------------|--------| | Nigerian Naira | ₦ | | South African Rand | R | | United States Dollar | $ | | Euro | € | | British Pound | £ | | Japanese Yen | ¥ | | Swiss Franc | CHF | | Canadian Dollar | $ | | Australian Dollar | $ | | New Zealand Dollar | $ | | Chinese Yuan | ¥ | | Swedish Krona | kr | | Norwegian Krone | kr | | Danish Krone | kr | | Indian Rupee | ₹ | | Russian Ruble | ₽ | | Brazilian Real | R$ | | Mexican Peso | $ | | Singapore Dollar | $ | | Hong Kong Dollar | $ | | South Korean Won | ₩ | | Turkish Lira | ₺ | | Indonesian Rupiah | Rp | | Malaysian Ringgit | RM | | Thai Baht | ฿ | | United Arab Emirates Dirham | د.إ | | Polish Zloty | zł | | Hungarian Forint | Ft | | Israeli New Shekel | ₪ | | Czech Koruna | Kč | | Philippine Peso | ₱ | | Chilean Peso | $ | | Argentine Peso | $ | | Colombian Peso | $ | | Peruvian Sol | S/. | | Romanian Leu | lei | | Angolan Kwanza | Kz | | Ugandan Shilling | USh | | Zambian Kwacha | ZK | | Eritrean Nakfa | Nfk | | São Tomé and Príncipe Dobra | Db |

Notes

Replace 'your-app-id' and 'your-public-key' with your actual application ID and 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 environment to the whitelisted URLs.

By following these steps, you easily integrate the Zinari Pay CDN Bundle 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

Usage

Step 1: Create a New Instance

Step 2: Access the Instance from a JavaScript File

Supported Fiat Currencies

Notes

Known Issues

CORS Error

Happy Coding