​
Cube SDK Payload Data Structure

The Cube SDK provides flexibility in managing both payments and delivery services. Below is a detailed breakdown of the payload data structure required when integrating the Cube SDK into your application.

​
Payload Structure Overview

The payload is a JavaScript object passed to the CubeSDK.config() method, containing essential details about the transaction, customer, and delivery.
Feel free to conduct direct testing on this website. We strongly encourage and recommend utilising this feature as an efficient means to promptly test functionalities and configurations on your end.
Sample
CubeSDK.config({
  public_key: "", // Replace with your Public API Key
  amount: 9000.458,  // Amount to be charged
  currency: "NGN",   // Transaction currency
  country: "NG",     // Country code
  payment_options: ["USSD", "Transfer"], // Available payment options.
  customer: {...}, // Customer details
  merchant_details: {...}, // Merchant details
  handle_delivery: true, // Enable delivery handling
  charge_delivery: true, // Apply delivery charges
  item_weight: 0.5,  // Weight of the item(s) for delivery
  delivery_items: [...], // List of delivery items
  pickup_location: {...}, // Pickup location details
  redirect_url: "", // URL to redirect after payment
  onCancel: (data) => {...}, // Handle payment cancellation
  onSuccess: (transaction) => {...}, // Handle successful payment
  onFailed: (transaction) => {...}, // Handle failed payment
  onError: (error) => {...}, // Handle errors during the transaction
});

​
Detailed Breakdown

​
- public_key (String)

This is your Public API Key provided by Mervii. You should replace this with your live or test API key when configuring the SDK.
Example:
public_key: "CU_PK_LIVE-******" //You can passed both Production and Test Public API key

​
- amount (Number)

The total amount to be charged for the transaction. This should include all costs, such as delivery fees, if applicable.
Example:
amount: 9000.46

​
- currency (String)

The currency in which the transaction will be processed. In this case, NGN is used for Nigerian Naira.
Example:
currency: "NGN"

​
- country (String)

The country code where the transaction is being processed. Here, NG refers to Nigeria.
Example:
country: "NG"

​
- payment_options (Array of Strings)

A list of available payment methods. The current supported options include USSD and Transfer.
Example:
payment_options: ["USSD", "Transfer"]

​
- customer (Object)

Contains customer details required for the transaction. name: Full name of the customer. phone_number: Primary contact phone number. email: Customer’s email address.
Example:
customer: {
  name: "John deo",
  phone_number: "07045417072",
  email: "hello@mervii.com"
}

​
- merchant_details (Object)

Details about the merchant processing the payment. title: The name of the merchant or business. description: A short description of the transaction or product. logo: A URL pointing to the merchant’s logo.
Example:
merchant_details: {
  title: "Merchant",
  description: "Sell With Mervii",
  logo: "https://mervii.com/android-chrome-512x512.png"
}

​
- handle_delivery (Boolean)

Set to true if the SDK should handle delivery processing for the transaction.
Example:
handle_delivery: true

​
- charge_delivery (Boolean)

Set to true if delivery charges should be applied to the transaction.
Example:
charge_delivery: true

​
-item_weight (Number)

The total weight of the item(s) for delivery, in kilograms.
Example
item_weight: 0.5

​
- delivery_items (Array)

A list of items being delivered. This array can be left empty if there are no specific items to track.
Example
delivery_items: []

​
- pickup_location (Object)

Details about the pickup location for the delivery. region: Coordinates (latitude and longitude) of the pickup location. city: The city where the pickup is taking place. state_code: The code of the state where the pickup is located. country_code: The code of the country where the pickup is located. contacts: Information about the contact person at the pickup location.
Example
pickup_location: {
  region: {
    latitude: 7.427026700000001,
    longitude: 3.8900142,
  },
  city: "Ibadan",
  state_code: "YO",
  country_code: "NG",
  contacts: {
    name: "John doe",
    phone_number: "07046417072",
    email: "hello@mervii.com",
  },
  pickup_date: "09-07-2024",
  pickup_time: "03:40PM",
  pickup_note: "Ask for John",
  formattedAddress: "95 Poly Road Sango, Ibadan 200132, Oyo, Nigeria"
}

​
- redirect_url (String)

A URL to which the user will be redirected after the transaction is complete. This can be left empty if no redirection is required.
Example
redirect_url: ""

​
Event Handlers

The event handler give you the real-time notification

​
- onCancel(data):

Callback for when the payment is cancelled by the user.
Example
onCancel: (data) => {
  console.log("onCancel", JSON.stringify(data));
}

​
- onSuccess(transaction):

Callback for a successful payment transaction.
Example
onSuccess: (transaction) => {
  console.log("Success", transaction);
}

​
- onFailed(transaction):

Callback for a failed payment attempt.
Example
onFailed: (transaction) => {
  console.log("Failed", transaction);
}

​
- onError(error):

Callback for handling errors during the transaction process.
Example
onError: (error) => {
  console.log("Error: ", JSON.stringify({ error }));
}

​
Example Payload

Here’s a full example of the payload structure 
<script src="https://cube.mervii.com/beta/cube.js"></script>
<button id="pay-button">Pay Now</button>
<script>
  document.getElementById("pay-button").onclick = function () {
    CubeSDK.config({
      public_key: "CU_PK_LIVE-e**************************", // Replace with your API key
      amount: 9000.458,
      currency: "NGN",
      country: "NG",
      payment_options: ["USSD", "Transfer"],
      customer: {
        name: "John doe",
        phone_number: "07045417072",
        email: "hello@mervii.com",
      },
      merchant_details: {
        title: "Merchant",
        description: "Sell With Mervii",
        logo: "https://mervii.com/android-chrome-512x512.png",
      },
      handle_delivery: true,
      charge_delivery: true,
      item_weight: 0.5,
      pickup_location: {
        region: {
          latitude: 7.427026700000001,
          longitude: 3.8900142,
        },
        city: "Ibadan",
        state_code: "YO",
        country_code: "NG",
        contacts: {
          name: "Developers",
          phone_number: "09020500177",
          email: "developer@mervii.com",
        },
        pickup_date: "09-07-2024",
        pickup_time: "03:40PM",
        pickup_note: "Ask for Adekunle",
        formattedAddress: "95 Poly Road Sango, Ibadan 200132, Oyo, Nigeria",
      },
      onCancel: (data) => {
        console.log("onCancel", JSON.stringify(data));
      },
      onSuccess: (transaction) => {
        console.log("Success", transaction);
      },
      onFailed: (transaction) => {
        console.log("Failed", transaction);
      },
      onError: (error) => {
        console.log("Error: ", JSON.stringify({ error }));
      },
    });
  };
</script>