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.

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-e1VFDBEE75Xa15UYzbzhEhuxuyxBncCpc9wCdkDJ"

- 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: "Adeyemi",
  phone_number: "09020500144",
  email: "hello@domain.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: "Olakunle Olayemi",
    phone_number: "09020500177",
    email: "abdul@gmail.com",
  },
  pickup_date: "09-07-2024",
  pickup_time: "03:40PM",
  pickup_note: "Ask for Adekunle",
  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-e1VFDBEE75Xa15UYzbzhEhuxuyxBncCpc9wCdkDJ", // Replace with your API key
      amount: 9000.458,
      currency: "NGN",
      country: "NG",
      payment_options: ["USSD", "Transfer"],
      customer: {
        name: "Adeyemi",
        phone_number: "09020500144",
        email: "hello@domain.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: "Olakunle Olayemi",
          phone_number: "09020500177",
          email: "abdul@gmail.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>

Cube

​Cube SDK Payload Data Structure

​Payload Structure Overview

​Detailed Breakdown

​- public_key (String)

​- amount (Number)

​- currency (String)

​- country (String)

​- payment_options (Array of Strings)

​- customer (Object)

​- merchant_details (Object)

​- handle_delivery (Boolean)

​- charge_delivery (Boolean)

​-item_weight (Number)

​- delivery_items (Array)

​- pickup_location (Object)

​- redirect_url (String)

​Event Handlers

​- onCancel(data):

​- onSuccess(transaction):

​- onFailed(transaction):

​- onError(error):

​Example Payload