zinari-pay

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

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.

Links

• Official Website
• NPM Package
• Documentation

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: '[e-mail]',
    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 confirmed excess - User over paid, you'll have to provide a refund incomplete - User underpaid and will have to complete the payment failed - 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.

Happy Coding

• CzA