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.
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.
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.
- currency (String)
The currency in which the transaction will be processed. In this case, NGN is used for Nigerian Naira.
- country (String)
The country code where the transaction is being processed. Here, NG refers to Nigeria.
- payment_options (Array of Strings)
A list of available payment methods. The current supported options include USSD and Transfer.
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.
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.
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.
- charge_delivery (Boolean)
Set to true if delivery charges should be applied to the transaction.
-item_weight (Number)
The total weight of the item(s) for delivery, in kilograms.
- delivery_items (Array)
A list of items being delivered. This array can be left empty if there are no specific items to track.
- 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.
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.
Event Handlers
The event handler give you the real-time notification
- onCancel(data):
Callback for when the payment is cancelled by the user.
onCancel: (data) => {
console.log("onCancel", JSON.stringify(data));
}
- onSuccess(transaction):
Callback for a successful payment transaction.
onSuccess: (transaction) => {
console.log("Success", transaction);
}
- onFailed(transaction):
Callback for a failed payment attempt.
onFailed: (transaction) => {
console.log("Failed", transaction);
}
- onError(error):
Callback for handling errors during the transaction process.
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>
