Skip to main content

USD Integration with Clive SDK

This guide walks you through integrating the Clive Payments SDK into your web application to support USD transactions. The integration is framework-agnostic and works with React, Vue, Angular, or Vanilla JavaScript.

Prerequisites​

  • Access to the @clive-alliance/partner-sdk package
  • An accessCode to fetch the required payment information. This is generated when you initiate a payment with USD as currency.

Step 1: Install the SDK​

npm install @clive-alliance/partner-sdk

Step 2: Fetch Payment Information​

Before initializing the widget, retrieve the transaction details by calling the GetPaymentInfo endpoint using your accessCode. The response provides clientId, partnerId, and brandingUrl — all required to initialize the Clive widget.

Endpoint​

GET Payments/GetPaymentInfo/{accessCode}

Headers​

Authorization: Bearer

To authorize this API request, you need to include your apiKey as a bearer token. This is done by setting the Authorization header in your request. The header should have the format:

Authorization: "Bearer your_api_key"

Note: Get your API key from Settings > API Keys in your dashboard.

Sample Response:

{
  "responseCode": "00",
  "responseMessage": "Payment information fetched successfully",
  "data": {
    "email": "emino@yopmail.com",
    "amount": 10,
    "transactionId": "PP8CD04EDD3A284",
    "reference": "pTOom3W1Zj1bL",
    "businessName": "Emino Sin Amor",
    "isActive": true,
    "cardPayment": true,
    "token": "<jwt_token>",
    "currency": "USD",
    "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
    "clientId": "EchezonaInHouse",
    "partnerId": "ECHEZONA001",
    "brandingUrl": "https://api.pay.cliveai.com/api/v1",
    "isLive": true,
    "convinienceFee": 0.15,
    "totalAmount": 10.15,
    "isChargeTransferedToCustomer": true,
    "customization": {
      "bodyColor": null,
      "buttonColor": null,
      "footerText": null,
      "footerLink": null,
      "footerLogo": null
    }
  }
}

Step 3: Create the Mount Point​

Add a div element with a unique ID to your template or component file. The Clive widget will render inside this container.

<!-- The Clive widget will be mounted inside this container -->
<div id="clive-pay-widget"></div>

<!-- Optional: container to display initialization errors -->
<div id="clive-error-container" style="display: none; color: red;"></div>

Ensure this DOM element is fully mounted and available in the browser before calling the initialization script. In component-based frameworks (React, Vue, Svelte), initialize the widget inside a lifecycle hook such as useEffect, mounted, or onMount.

Step 4: Initialize the Clive Widget​

Import createClivePaymentsWidget from the SDK. You can initialize the widget either by providing an accessCode to fetch the payment details first, or by passing an already-fetched paymentInfo object directly.

import { createClivePaymentsWidget } from "@clive-alliance/partner-sdk";

async function setupCliveCheckout(accessCode) {
  // Fetch payment information using the payments endpoint
  const paymentInfoResponse = await fetch(
    `https://api.echezona.com/api/Payments/GetPaymentInfo/${accessCode}`
  );
  const paymentInfoData = await paymentInfoResponse.json();

  if (paymentInfoData.responseCode !== "00" || !paymentInfoData.data) {
    throw new Error("Failed to fetch payment information");
  }

  const paymentInfo = paymentInfoData.data;

  try {
    // Initialize the widget
    createClivePaymentsWidget({
      mount: "#clive-pay-widget",

      amount: paymentInfo.amount,
      currency: paymentInfo.currency || "USD",
      email: paymentInfo.email,
      echezonaReference: paymentInfo.transactionId || "",
      partnerId: paymentInfo.partnerId || "",
      clientId: paymentInfo.clientId || "",
      brandingBaseUrl: paymentInfo.brandingUrl || "",

      // Called by the SDK to initialize the checkout intent on your backend
      initializeTransaction: async (payload) => {
        const response = await fetch("https://api.echezona.com/api/Payments/checkout-intent-v2", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            echezonaReference: paymentInfo.transactionId || "",
            clientId: paymentInfo.clientId || "",
            amount: paymentInfo.amount,
            currency: paymentInfo.currency || "USD",
            email: paymentInfo.email,
            paymentType: payload.payment_type,
            issuerCountry: payload.issuer_country,
          }),
        });

        const jsonResponse = await response.json();
        return jsonResponse.data || {};
      },

      onSuccess: () => {
        console.log("Payment successful");
        // handle success response
      },

      onError: (error) => {
        const errorContainer = document.getElementById("clive-error-container");
        if (errorContainer) {
          errorContainer.innerText = error.message || "Payment failed";
          errorContainer.style.display = "block";
        }
      },
    });
  } catch (err) {
    console.error("Failed to initialize widget:", err);
  }
}

// Call setup once the DOM is ready
setupCliveCheckout("YOUR_ACCESS_CODE");

Configuration Options​

ParameterTypeDescription
mountstringCSS selector for the DOM element where the widget renders
amountnumberTransaction amount
currencystringCurrency code (e.g. "USD")
emailstringCustomer email address
echezonaReferencestringUnique transaction reference from Echezona
partnerIdstringPartner ID from the GetPaymentInfo response
clientIdstringClient ID from the GetPaymentInfo response
brandingBaseUrlstringBase URL for Clive branding assets from the GetPaymentInfo response
initializeTransactionfunctionAsync callback that creates the checkout intent on your backend and returns the transaction data
onSuccessfunctionTriggered when payment completes successfully
onErrorfunctionTriggered when payment fails or is cancelled

Step 5: Post-Payment Verification​

The onSuccess callback fires once Clive processes the transaction. You should still verify the final status server-side before showing a confirmation to the user.

  1. Display a loading or verification screen immediately after onSuccess fires.
  2. Ping your backend to confirm the payment status via webhooks or a direct status check.
  3. Show the final receipt once your backend confirms the transaction.

Do not rely solely on the onSuccess callback to confirm payment. The status may not reflect immediately, so you may need to poll the checkout status on your server.

Additionally, if you have webhooks configured, we will send a webhook notification to your server. Always verify the final transaction status. See the Fetch Transaction Status endpoint and the Webhooks Guide for details.