# Introduction
How to connect our API into your application.
### Getting Started
{% hint style="info" %}
**Note:** To use our APIs, you need to have an [XtraKit account](https://xtrakit.com). On the XtraKit dashboard, we will generate any API for you.
{% endhint %}
## Overview
Our APIs are designed to integrate seamlessly with your systems and applications. This document serves as a comprehensive reference for all the features accessible to you through our APIs for adding and fetching data. It's designed around the primary resources you'll need most frequently and is made with RESTful standards in mind.
### HTTP Methods
POST
To add new business data to the system, use this request.
GET
To add and retrieve business data from the system, use this request.
PUT
To update an existing business record in the system, use this request.
DELETE
To remove business records from the system, use this request. Removal is permanent.
## Authentication
Place your API key in the Authorisation header of each request you make to ensure the authenticity of your API calls. From your [API settings](https://app.xtrakit.com/settings/apis) page, you can manage your API key.
However, the API key must remain confidential. You can reset your API key or, if you think it has been compromised for any reason, change it from the [API settings](https://app.xtrakit.com/settings/apis) page.
The following format should be used for authorisation headers:
`Authorization: Bearer API_KEY`
{% hint style="info" %}
**Sample Authorization Header**
Authorization: Bearer 92857043717beff382ae75c8dc7514162f04
{% endhint %}
```php
curl -H "Authorization: Bearer API_KEY" \
https://api.xtrakit.com/api/v1/user/authenticate
```
## Requests and Response
The format of the response and request payloads is JSON. Responses will always have `application/json` as their content type. Each response will typically follow this format:
## Response Formats
| Response | Data type | Description |
| -------- | --------- | ------------------------------------------------------------------------------------------------ |
| status | number | The HTTP status code indicating a status operation. |
| message | string | This gives you detailed explaination on the request sent. The interpretation of the status code. |
| data | object | An object holding any data that the API returned after receiving the request. |
## **Status Codes and Interpretation**
| Status Code | Interpretation |
| ----------- | --------------------------------------------------------- |
| `200` | Standard for successful request. |
| `201` | Used for requests as a result of creation. |
| `204` | Indicates that a request has succeeded or been processed. |
| `400` | For bad requests. |
| `401` | For unathorized. |
| `402` | For payment required. |
| `404` | For not found. |
| `500` | For internal server errors. |
# Sales
XtraKit's Sales API allows you to programmatically handle sales data. Sales management may be easily integrated into your applications by using it to retrieve, add, change, or manage sales.
List Sale GET
Retrieve a list of all sales and you can also filter your results.
# List Sales
A list of all sales may be obtained using this endpoint. For emphasis on specific results, you can add filters based on date, status, customer, and other variables.
## Endpoint
**`GET`** `https://api.xtrakit.com/api/v1/sales`
## Headers
`Authorization: Bearer API_KEY`
## **Query Parameters**
{% endtab %}
{% tab title="NodeJS" %}
```javascript
const axios = require('axios');
const invoice_code = 'YOUR_INVOICE_CODE'; // Replace 'YOUR_INVOICE_CODE' with your actual invoice Code
const config = {
method: 'get',
url: `https://api.xtrakit.com/api/v1/sales/{invoice_code}`,
headers: {
'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key
}
};
axios(config).then(function(response) {
console.log(JSON.stringify(response.data));
}).catch(function(error) {
console.error(error);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
invoice_code = 'YOUR_INVOICE_CODE' # Replace 'YOUR_INVOICE_CODE' with your actual invoice Code
url = f'https://api.xtrakit.com/api/v1/sales/{invoice_code}'
headers = {
"Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
}
try:
response = requests.get(url, headers=headers)
print(response.json())
except requests.exceptions.RequestException as e:
print(e)
```
{% endtab %}
{% endtabs %}
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"message": "Sale found",
"data": {
"sales": {
"id": 32,
"invoice_code": 324232,
"invoice_number": "INV-000001",
"customer_id": "42",
"sub_total_amount": "100.00",
"total_amount": "200.00",
"amount_paid": "200.00",
"discount": "0.00",
"invoice_type": "pos",
"invoice_colour": "#FFFFFF",
"invoice_note": null,
"invoice_terms": "Thanks for doing business",
"payment_internal_note": null,
"payment_date": "2024-08-04",
"payment_type": "2024-08-04",
"payment_status": "paid",
"issued_by": "Jones Nathal",
"due_date": "2024-08-30",
"reminder_date": "2024-08-25",
"reminder_message": null,
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
},
"sales-item": [
{
"id": 45,
"invoice_code": "324232",
"invoice_number": "INV-000001",
"item_name": "Web Design",
"description": "Including hosting",
"unit_price": "100.00",
"quantity": "2",
"tax": "0.00",
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
},
...
],
"sales-payment": [
{
"invoice_code": "324232",
"customer_name": "Peter Amos",
"amount_paid": "200.00",
"payment_method": "Cash",
"internal_payment_note": null,
"issued_by": "Jones Nathal",
"payment_at": "2024-08-04 08:23:45",
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
},
...
]
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Add Sale
Adding new sales may be obtained using this endpoint. For emphasis on specific results, you can add the following parameters when creating new sales.
## Endpoint
**`POST`** `https://api.xtrakit.com/api/v1/sales/add`
## Headers
`Authorization: Bearer API_KEY`
## **Body Parameters**
Parameters
Type
Description
invoice_code
string
Required
An invoice code is a unique 6-digit code to generate.
invoice_number
string
Required
An invoice number is a unique 6-digit code to generate. Prefix depends on the one you set on the system which would be appended automatically. Example: INV-000001
customer_id
int
Required
You can retrieve customer IDs from customers created and pull their primary ID here.
sub_total_amount
decimal (10,2)
Required
Subtotal amount of your sales in this format: 10.00
total_amount
decimal (10,2)
Required
The total amount of your sales after adding everything including tax, discount, etc. In this format: 10.00
amount_paid
decimal (10,2)
Required
The amount received from the customer when creating this sale. If the amount is zero (0) and the payment method is none, it means the invoice status is DRAFT
discount
decimal (10,2)
Optional
Discounts given to the customer on sale can be null. Discount is in value not percentage. Example: 10.00
invoice_type
string
Required
We have 3 types of invoices in our system, with 3 Statuses: main, pos, and order. So, the main is the XtraKit dashboard, pos is the XtraPOS, and order is the Storefront.
invoice_colour
string
Optional
To set your custom invoice colour, you need to put colour by using a colour code like this: #FFFFFF
invoice_note
string
Optional
If you want to add a message to your invoice.
invoice_terms
string
Optional
What terms and conditions do you want to add to the invoice? Maybe half payment should be made before work.
payment_type
string
Required
Payment method or type can be of these options: None, Mobile Money, Cash, Bank Transfer / Deposit, Cheque, Card Payment, Digital Payment and Other Payment
payment_internal_note
string
Optional
You want to add any payment message for internal use only. The customer won't see this message.
issued_by
string
Optional
Name of the person who issued the invoice. Example: Jones Nathal
due_date
string
Required
The latest date for when you must pay your invoice. Date format: 2024-08-30
reminder_date
string
Optional
The date you want us to send a reminder to the client on invoice payment. Date format: 2024-08-30
reminder_message
string
Optional
The reminder message you want us to send to the customer on the reminder date.
An invoice code is a unique code to retrieve a single sale. Should be passed through the URL
## Body Parameters
Parameters
Type
Description
invoice_code
string
Required
An invoice code is a unique 6-digit code to generate.
invoice_number
string
Required
An invoice number is a unique 6-digit code to generate. Prefix depends on the one you set on the system which would be appended automatically. Example: INV-000001
customer_id
int
Required
You can retrieve customer IDs from customers created and pull their primary ID here.
sub_total_amount
decimal (10,2)
Required
Subtotal amount of your sales in this format: 10.00
total_amount
decimal (10,2)
Required
The total amount of your sales after adding everything including tax, discount, etc. In this format: 10.00
amount_paid
decimal (10,2)
Required
The amount received from the customer when creating this sale. If the amount is zero (0) and the payment method is none, it means the invoice status is DRAFT
discount
decimal (10,2)
Optional
Discounts given to the customer on sale can be null. Discount is in value not percentage. Example: 10.00
# List Expenses
A list of all expenses may be obtained using this endpoint. For emphasis on specific results, you can add filters based on business code, expense type, and other variables.
## Endpoint
**`GET`** `https://api.xtrakit.com/api/v1/expenses`
## Headers
`Authorization: Bearer API_KEY`
## **Query Parameters**
<?php
$id = 'YOUR_EXPENSE_ID'; // Replace 'YOUR_EXPENSE_ID' with your actual expense ID
$url = 'https://api.xtrakit.com/api/v1/expenses/' . $id;
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer API_KEY', // Replace 'API_KEY' with your actual API key
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
{% endtab %}
{% tab title="NodeJS" %}
```javascript
const axios = require('axios');
const id = 'YOUR_EXPENSE_ID'; // Replace 'YOUR_EXPENSE_ID' with your actual expense ID
const config = {
method: 'get',
url: `https://api.xtrakit.com/api/v1/expenses/{id}`,
headers: {
'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key
}
};
axios(config).then(function(response) {
console.log(JSON.stringify(response.data));
}).catch(function(error) {
console.error(error);
});
```
{% endtab %}
{% tab title="Python" %}
import requests
id = 'YOUR_EXPENSE_ID' # Replace 'YOUR_EXPENSE_ID' with your actual expense ID
url = f'https://api.xtrakit.com/api/v1/expenses/{id}'
headers = {
"Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
}
try:
response = requests.get(url, headers=headers)
print(response.json())
except requests.exceptions.RequestException as e:
print(e)
{% endtab %}
{% endtabs %}
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"message": "Expense found",
"data": {
"expense": {
"id": 1,
"expense_type": "Travel",
"expense_description": "Flight ticket to Kumasi",
"expense_amount": "200.00",
"payment_method": "MOMO",
"expense_image": "https://url-to-image.com/image.jpg",
"created_by": "Edward",
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
}
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Authentication invalid"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Add Expense
Adding new expenses may be obtained using this endpoint. For emphasis on specific results, you can add the following parameters when creating new expenses.
## Endpoint
**`POST`** `https://api.xtrakit.com/api/v1/expenses/add`
## Headers
`Authorization: Bearer API_KEY`
## **Body Parameters**
Parameters
Type
Description
expense_type
string
Required
The type of the expense.
expense_description
string
Optional
A detailed description of the expense.
expense_amount
decimal(10,2)
Required
The amount of the expense in this format: 10.00
payment_method
string
Required
The method used for payment.
expense_image
string
Optional
URL to an image or receipt associated with the expense.
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Authentication invalid"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Inventory
XtraKit's Inventory API allows you to programmatically handle items data. Items management may be easily integrated into your applications by using it to retrieve, add, change, or manage items.
List Items GET
Retrieve a list of all items and you can also filter your results.
# List Items
A list of all items available in the inventory may be obtained using this endpoint. For emphasis on specific results, you can add filters based on user, business, or category.
## Endpoint
**`GET`** `https://api.xtrakit.com/api/v1/inventory/items`
## Headers
`Authorization: Bearer API_KEY`
## **Query Parameters**
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Authentication invalid"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Add Item
Allows you to add a new item to the inventory. This endpoint is used when introducing new products to your stock. You’ll need to provide essential details such as the item name, price and others.
## Endpoint
**`POST`** `https://api.xtrakit.com/api/v1/inventory/items/add`
## Headers
`Authorization: Bearer API_KEY`
## **Body Parameters**
Parameters
Type
Description
item_name
string
Required
The name or title of the item.
category_id
int
Required
The ID representing the category this item belongs to.
unit
string
Required
The unit of measure for the item.
(pcs, kg, liters,...)
description
string
Optional
A detailed description of the item, providing more information about its features.
unit_cost
decimal(10,2)
Required
The cost price of a single unit of the item in this format: 10.00
item_price
decimal(10,2)
Required
The selling price of the item in this format: 10.00
previous_price
decimal(10,2)
Optional
The previous selling price of the item in this format: 10.00
quantity
string
Required
The available stock or quantity of the item.
minimum_qty_alert
string
Optional
A threshold quantity that triggers an alert when stock falls below this level.
online
int
Required
Indicator whether the item is available online.
Accepts 1 (true) or 0 (false)
status
string
Required
The availability status of the item.
(available, out of stock).
barcode
string
Optional
The barcode assigned to the item.
sku
string
Optional
The Stock Keeping Unit (SKU) for tracking inventory.
warehouse_id
int
Optional
The ID of the warehouse where the item is stored.
item_location
string
Optional
The physical location of the item within the warehouse.
item_slug
string
Optional
A URL-friendly version of the item name used in links and routes.
# Create Store
Allows you to add a new store record using this endpoint. This endpoint is used when introducing new stores.
## Endpoint
**`POST`** `https://api.xtrakit.com/api/v1/stores/add`
## Headers
`Authorization: Bearer API_KEY`
## **Query Parameters**
Parameters
Type
Description
invoice_code
string
Optional
Specify invoice code to retreive
customer_id
number
Optional
Filter sales by customer ID
invoice_type
string
Optional
Filter sales based on the invoice type
(pos, invoice, storefront)
payment_date
date
Optional
Filter sales by payment date
payment_status
string
Optional
Filter sales by payment status
(paid, partial, draft)
created_at
datetime
Optional
Start date for filtering sales records
(format: YYYY-MM-DD H:m:s)
due_date
date
Optional
End date for filtering sales records
(format: YYYY-MM-DD)
## Sample Requests
{% tabs %}
{% tab title="PHP" %}
{% code fullWidth="true" %}
```php
'https://api.xtrakit.com/api/v1/stores/add',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer API_KEY', // Replace 'API_KEY' with your actual API key
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
```
{% endcode %}
{% endtab %}
{% tab title="NodeJS" %}
```javascript
const axios = require('axios');
const config = {
method: 'get',
url: 'https://api.xtrakit.com/api/v1/stores/add',
headers: {
'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key
}
};
axios(config).then(function(response) {
console.log(JSON.stringify(response.data));
}).catch(function(error) {
console.error(error);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.xtrakit.com/api/v1/stores/add"
headers = {
"Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
}
response = requests.get(url, headers=headers)
print(response.json())
```
{% endtab %}
{% endtabs %}
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"message": "Store added successfully",
"data": {
"store": {
"id": 32,
"invoice_code": 324232,
"invoice_number": "INV-000001",
"customer_id": "42",
"sub_total_amount": "100.00",
"total_amount": "200.00",
"amount_paid": "200.00",
"discount": "0.00",
"invoice_type": "pos",
"invoice_colour": "#FFFFFF",
"invoice_note": null,
"invoice_terms": "Thanks for doing business",
"payment_internal_note": null,
"payment_date": "2024-08-04",
"payment_type": "2024-08-04",
"payment_status": "paid",
"issued_by": "Jones Nathal",
"due_date": "2024-08-30",
"reminder_date": "2024-08-25",
"reminder_message": null,
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
},
...
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Fetch Store Orders
Retrieve a specific store using the store id. To retrieve complete store details, use this endpoint. For emphasis on specific results, you can add filters based on other variables.
## Endpoint
**`GET`** `https://api.xtrakit.com/api/v1/stores/{id}`
## Headers
`Authorization: Bearer API_KEY`
## **Path Parameters**
Parameters
Type
Description
id
string
Required
The unique identifier of the store. Should be passed through the URL
const axios = require('axios');
const id = 'STORE_ID'; // Replace 'STORE_ID' with your actual store ID
const config = {
method: 'put',
url: `https://api.xtrakit.com/api/v1/stores/{id}`,
headers: {
'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key
}
};
axios(config).then(function(response) {
console.log(JSON.stringify(response.data));
}).catch(function(error) {
console.error(error);
});
{% endtab %}
{% tab title="Python" %}
```python
import requests
id = 'STORE_ID' # Replace 'STORE_ID' with your actual store ID
url = f'https://api.xtrakit.com/api/v1/stores/{id}'
headers = {
"Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
}
try:
response = requests.put(url, headers=headers)
print(response.json())
except requests.exceptions.RequestException as e:
print(e)
```
{% endtab %}
{% endtabs %}
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"message": "Store updated successfully",
"data": {
"store": {
"id": 32,
"invoice_code": 324232,
"invoice_number": "INV-000001",
"customer_id": "42",
"sub_total_amount": "100.00",
"total_amount": "200.00",
"amount_paid": "200.00",
"discount": "0.00",
"invoice_type": "pos",
"invoice_colour": "#FFFFFF",
"invoice_note": null,
"invoice_terms": "Thanks for doing business",
"payment_internal_note": null,
"payment_date": "2024-08-04",
"payment_type": "2024-08-04",
"payment_status": "paid",
"issued_by": "Jones Nathal",
"due_date": "2024-08-30",
"reminder_date": "2024-08-25",
"reminder_message": null,
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
},
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Customers
XtraKit's Customer API allows you to programmatically handle customers data. Customers management may be easily integrated into your applications by using it to retrieve, add, or manage customers.
List Customers GET
Retrieve a list of all customers and you can also filter your results.
Modify an existing customer's information. In an unfinalized customer, this endpoint can be used to change customer name, customer phone, or customer email'
Modify an existing customer group's information. In an unfinalized customer group, this endpoint can be used to change group name and group description.
# List Customers
A list of all customers may be obtained using this endpoint. For emphasis on specific results, you can add filters based on customer's group id and other variables.
## Endpoint
**`GET`** `https://api.xtrakit.com/api/v1/customers`
## Headers
`Authorization: Bearer API_KEY`
## **Query Parameters**
Parameters
Type
Description
customer_group_id
int
Optional
Filters customers by the group to which this customer belongs.
created_at
datetime
Optional
Start date for filtering customers records.
(format: YYYY-MM-DD H:m:s)
updated_at
date
Optional
End date for filtering customers records.
(format: YYYY-MM-DD)
## Sample Requests
{% tabs %}
{% tab title="PHP" %}
{% code fullWidth="true" %}
```php
'https://api.xtrakit.com/api/v1/customers',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer API_KEY', // Replace 'API_KEY' with your actual API key
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
```
{% endcode %}
{% endtab %}
{% tab title="NodeJS" %}
```javascript
const axios = require('axios');
const config = {
method: 'get',
url: 'https://api.xtrakit.com/api/v1/customers',
headers: {
'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key
}
};
axios(config).then(function(response) {
console.log(JSON.stringify(response.data));
}).catch(function(error) {
console.error(error);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.xtrakit.com/api/v1/customers"
headers = {
"Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
}
response = requests.get(url, headers=headers)
print(response.json())
```
{% endtab %}
{% endtabs %}
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"message": "Customers found: 20",
"data": {
"customers": {
"id": 1,
"customer_group_id": 1,
"customer_name": "Jane Doe",
"customer_email": "jane.doe@example.com",
"customer_phone": "+233244567890",
"customer_whatsapp": "+233244567890",
"customer_country": "Ghana",
"customer_city": "Accra",
"customer_state": "Greater Accra",
"customer_zip": "00233",
"address1": "123 Main Street",
"address2": "Apt 4B, Downtown Complex",
"customer_profile": "https://example.com/profiles/customer123.jpg",
"created_by": "Edward",
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
},
...
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Fetch Customer
Retrieves detailed information for a specific customer based on the customer ID provided in the request URL. This is useful when you need in-depth information on a particular customer.
## Endpoint
**`GET`** `https://api.xtrakit.com/api/v1/customers/{id}`
## Headers
`Authorization: Bearer API_KEY`
## **Path Parameters**
Parameters
Type
Description
id
string
Required
The unique identifier of the customer. Should be passed through the URL
<?php
$id = 'CUSTOMER_GROUP_ID'; // Replace 'CUSTOMER_GROUP_ID' with your actual customer group ID
$url = 'https://api.xtrakit.com/api/v1/customer-groups/' . $id;
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer API_KEY', // Replace 'API_KEY' with your actual API key
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
{% endtab %}
{% tab title="NodeJS" %}
```javascript
const axios = require('axios');
const id = 'CUSTOMER_GROUP_ID'; // Replace 'CUSTOMER_GROUP_ID' with your actual customer group ID
const config = {
method: 'get',
url: `https://api.xtrakit.com/api/v1/customer-groups/{id}`,
headers: {
'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key
}
};
axios(config).then(function(response) {
console.log(JSON.stringify(response.data));
}).catch(function(error) {
console.error(error);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
id = 'CUSTOMER_GROUP_ID' # Replace 'CUSTOMER_GROUP_ID' with your actual customer group ID
url = f'https://api.xtrakit.com/api/v1/customer-groups/{id}'
headers = {
"Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
}
try:
response = requests.get(url, headers=headers)
print(response.json())
except requests.exceptions.RequestException as e:
print(e)
```
{% endtab %}
{% endtabs %}
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"message": "Group found",
"data": {
"group": {
"id": 1,
"group_name": "Premium Customers",
"group_description": "Customers who have spent over $1000 and have been with the business for over a year.",
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
}
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# List Customer Group
A list of all customer groups may be obtained using this endpoint. For emphasis on specific results, you can add filters based on business code, date created and other variables.
## Endpoint
**`GET`** `https://api.xtrakit.com/api/v1/customer-groups`
## Headers
`Authorization: Bearer API_KEY`
## **Query Parameters**
Parameters
Type
Description
business_code
int
Optional
Filters customer groups by the unique business code associated with the customer group.
created_at
datetime
Optional
Start date for filtering customers records.
(format: YYYY-MM-DD H:m:s)
updated_at
date
Optional
End date for filtering customers records.
(format: YYYY-MM-DD)
## Sample Requests
{% tabs %}
{% tab title="PHP" %}
{% code fullWidth="true" %}
```php
'https://api.xtrakit.com/api/v1/customer-groups',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer API_KEY', // Replace 'API_KEY' with your actual API key
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
```
{% endcode %}
{% endtab %}
{% tab title="NodeJS" %}
```javascript
const axios = require('axios');
const config = {
method: 'get',
url: 'https://api.xtrakit.com/api/v1/customer-groups',
headers: {
'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key
}
};
axios(config).then(function(response) {
console.log(JSON.stringify(response.data));
}).catch(function(error) {
console.error(error);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.xtrakit.com/api/v1/customer-groups"
headers = {
"Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
}
response = requests.get(url, headers=headers)
print(response.json())
```
{% endtab %}
{% endtabs %}
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"message": "Groups found: 20",
"data": {
"groups": {
"id": 1,
"group_name": "Premium Customers",
"group_description": "Customers who have spent over $1000 and have been with the business for over a year.",
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
},
...
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Add Customer
This endpoint allows you to add a new customer to the system. You can store customer details like name, email, phone, address, and other relevant information.
## Endpoint
**`POST`** `https://api.xtrakit.com/api/v1/customers/add`
## Headers
`Authorization: Bearer API_KEY`
## **Body Parameters**
Parameters
Type
Description
customer_group_id
int
Optional
The ID of the group to which this customer belongs.
customer_name
string
Required
The full name of the customer, used for identification and personalization within the system.
customer_email
string
Optional
The email address of the customer, used for communications like receipts, notifications, or offers.
customer_phone
string
Required
The primary phone number for contacting the customer. It is useful for both communication and verification purposes.
customer_whatsapp
string
Optional
The customer's WhatsApp number. This is used for instant messaging or sending transactional notifications.
customer_country
string
Required
The country in which the customer resides. This is necessary for shipping, billing, or other region-specific activities.
customer_city
string
Required
The city where the customer is located. It helps in localizing deliveries, services, and communication.
customer_state
string
Required
The state or region where the customer is based. This is useful for regional identification within a country.
customer_zip
string
Optional
The postal code for the customer's location. It is generally used for mailing, shipping, and regional classification.
(eg: 00233)
address1
string
Required
The primary address of the customer, typically used for billing or shipping purposes. It can contain house numbers, street names, etc.
address2
string
Optional
The secondary address, such as apartment numbers or additional details not covered in address1. This is helpful when the customer's address is complex.
customer_profile
string
Optional
A URL or path to the customer's profile image, typically used for identification or personalization within the user interface.
created_by
string
Required
The identifier or username of the person who created this customer entry in the system. This helps in tracking changes and updates.
The name of the customer group. Typically short, identifying the purpose of the group.
group_description
string
Optional
A detailed description explaining the group and its purpose. Can include criteria and benefits.
## Sample Requests
{% tabs %}
{% tab title="PHP" %}
{% code fullWidth="true" %}
```php
"Platinum Customers",
'group_description' => "Customers who have spent over $5000 and have been with the business for over a year."
];
$url = 'https://api.xtrakit.com/api/v1/customer-groups/add';
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => $data,
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer API_KEY', // Replace 'API_KEY' with your actual API key
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
```
{% endcode %}
{% endtab %}
{% tab title="NodeJS" %}
```javascript
const axios = require('axios');
const data = {
'group_name': "Platinum Customers",
'group_description': "Customers who have spent over $5000 and have been with the business for over a year."
};
const config = {
method: 'post',
url: `https://api.xtrakit.com/api/v1/customer-groups/add`,
headers: {
'Authorization': 'Bearer API_KEY', // Replace 'API_KEY' with your actual API key
'Content-Type': 'application/json'
},
data: data
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.error(error);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
data = {
'group_name': "Platinum Customers",
'group_description': "Customers who have spent over $5000 and have been with the business for over a year."
}
url = f'https://api.xtrakit.com/api/v1/customer-groups/add'
headers = {
"Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
"Content-Type": "application/json"
}
try:
response = requests.post(url, headers=headers, json=data)
print(response.json())
except requests.exceptions.RequestException as e:
print(e)
```
{% endtab %}
{% endtabs %}
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"message": "Group added successfully",
"data": {
"group": {
"id": 2,
"group_name": "Platinum Customers",
"group_description": "Customers who have spent over $5000 and have been with the business for over a year.",
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
}
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Edit Customer
Updates the information of an existing customer. You can modify various fields such as customer details, addresses, and status.
## Endpoint
**`PUT`** `https://api.xtrakit.com/api/v1/customers/{id}`
## Headers
`Authorization: Bearer API_KEY`
## **Path Parameters**
Parameters
Type
Description
id
string
Required
The unique identifier of the customer. Should be passed through the URL
## Body Parameters
Parameters
Type
Description
customer_group_id
int
Optional
The ID of the group to which this customer belongs.
customer_name
string
Required
The full name of the customer, used for identification and personalization within the system.
customer_email
string
Optional
The email address of the customer, used for communications like receipts, notifications, or offers.
customer_phone
string
Required
The primary phone number for contacting the customer. It is useful for both communication and verification purposes.
customer_whatsapp
string
Optional
The customer's WhatsApp number. This is used for instant messaging or sending transactional notifications.
customer_country
string
Required
The country in which the customer resides. This is necessary for shipping, billing, or other region-specific activities.
customer_city
string
Required
The city where the customer is located. It helps in localizing deliveries, services, and communication.
customer_state
string
Required
The state or region where the customer is based. This is useful for regional identification within a country.
customer_zip
string
Optional
The postal code for the customer's location. It is generally used for mailing, shipping, and regional classification.
(eg: 00233)
address1
string
Required
The primary address of the customer, typically used for billing or shipping purposes. It can contain house numbers, street names, etc.
address2
string
Optional
The secondary address, such as apartment numbers or additional details not covered in address1. This is helpful when the customer's address is complex.
customer_profile
string
Optional
A URL or path to the customer's profile image, typically used for identification or personalization within the user interface.
created_by
string
Required
The identifier or username of the person who created this customer entry in the system. This helps in tracking changes and updates.
## Sample Requests
{% tabs %}
{% tab title="PHP" %}
{% code fullWidth="true" %}
```php
1,
'customer_name' => "Jane Doe",
'customer_email' => "jane.doe@example.com",
'customer_phone' => "+233244567890",
'customer_whatsapp' => "+233244567890",
'customer_country' => "Ghana",
'customer_city' => "Accra",
'customer_state' => "Greater Accra",
'customer_zip' => "00233",
'address1' => "123 Main Street",
'address2' => "Apt 4B, Downtown Complex",
'customer_profile' => "https://example.com/profiles/customer123.jpg",
"created_by" => "Edward"
];
$url = 'https://api.xtrakit.com/api/v1/customers/' . $id;
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_POSTFIELDS => $data,
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer API_KEY', // Replace 'API_KEY' with your actual API key
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
```
{% endcode %}
{% endtab %}
{% tab title="NodeJS" %}
```javascript
const axios = require('axios');
const id = 'CUSTOMER_ID'; // Replace 'CUSTOMER_ID' with your actual customer ID
const data = {
'customer_group_id': 1,
'customer_name': "Jane Doe",
'customer_email': "jane.doe@example.com",
'customer_phone': "+233244567890",
'customer_whatsapp': "+233244567890",
'customer_country': "Ghana",
'customer_city': "Accra",
'customer_state': "Greater Accra",
'customer_zip': "00233",
'address1': "123 Main Street",
'address2': "Apt 4B, Downtown Complex",
'customer_profile': "https://example.com/profiles/customer123.jpg",
"created_by": "Edward"
};
const config = {
method: 'put',
url: `https://api.xtrakit.com/api/v1/customers/{id}`,
headers: {
'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key
},
data: data
};
axios(config).then(function(response) {
console.log(JSON.stringify(response.data));
}).catch(function(error) {
console.error(error);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
id = 'CUSTOMER_ID' # Replace 'CUSTOMER_ID' with your actual customer ID
data = {
'customer_group_id': 1,
'customer_name': "Jane Doe",
'customer_email': "jane.doe@example.com",
'customer_phone': "+233244567890",
'customer_whatsapp': "+233244567890",
'customer_country': "Ghana",
'customer_city': "Accra",
'customer_state': "Greater Accra",
'customer_zip': "00233",
'address1': "123 Main Street",
'address2': "Apt 4B, Downtown Complex",
'customer_profile': "https://example.com/profiles/customer123.jpg",
"created_by": "Edward"
}
url = f'https://api.xtrakit.com/api/v1/customers/{id}'
headers = {
"Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
}
try:
response = requests.put(url, headers=headers, json=data)
print(response.json())
except requests.exceptions.RequestException as e:
print(e)
```
{% endtab %}
{% endtabs %}
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"message": "Customer updated successfully",
"data": {
"customer": {
"id": 1,
"customer_group_id": 1,
"customer_name": "Jane Doe",
"customer_email": "jane.doe@example.com",
"customer_phone": "+233244567890",
"customer_whatsapp": "+233244567890",
"customer_country": "Ghana",
"customer_city": "Accra",
"customer_state": "Greater Accra",
"customer_zip": "00233",
"address1": "123 Main Street",
"address2": "Apt 4B, Downtown Complex",
"customer_profile": "https://example.com/profiles/customer123.jpg",
"created_by": "Edward",
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
},
"customer-group": [
{
"id": 1,
"group_name": "Premium Customers",
"group_description": "Customers who have spent over $1000 and have been with the business for over a year.",
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
},
...
],
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Edit Customer Group
Updates the information of an existing customer group, allowing changes to the name, description, and other fields.
## Endpoint
**`PUT`** `https://api.xtrakit.com/api/v1/customer-groups/{id}`
## Headers
`Authorization: Bearer API_KEY`
## **Path Parameters**
Parameters
Type
Description
id
string
Required
The unique identifier of the customer group. Should be passed through the URL
## Body Parameters
Parameters
Type
Description
group_name
string
Required
The name of the customer group. Typically short, identifying the purpose of the group.
group_description
string
Optional
A detailed description explaining the group and its purpose. Can include criteria and benefits.
## Sample Requests
{% tabs %}
{% tab title="PHP" %}
{% code fullWidth="true" %}
```php
"Premium Customers",
'group_description' => "Customers who have spent over $1000 and have been with the business for over a year."
];
$url = 'https://api.xtrakit.com/api/v1/customer-groups/' . $id;
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_POSTFIELDS => $data,
CURLOPT_HTTPHEADER => array(
'Authorization: Bearer API_KEY', // Replace 'API_KEY' with your actual API key
'Content-Type: application/json'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
?>
```
{% endcode %}
{% endtab %}
{% tab title="NodeJS" %}
```javascript
const axios = require('axios');
const id = 'CUSTOMER_GROUP_ID'; // Replace 'CUSTOMER_GROUP_ID' with your actual customer group ID
const data = {
'group_name': "Premium Customers",
'group_description': "Customers who have spent over $1000 and have been with the business for over a year."
};
const config = {
method: 'put',
url: `https://api.xtrakit.com/api/v1/customer-groups/{id}`,
headers: {
'Authorization': 'Bearer API_KEY' // Replace 'API_KEY' with your actual API key
},
data: data
};
axios(config).then(function(response) {
console.log(JSON.stringify(response.data));
}).catch(function(error) {
console.error(error);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
id = 'CUSTOMER_GROUP_ID' # Replace 'CUSTOMER_GROUP_ID' with your actual customer group ID
data = {
'group_name': "Premium Customers",
'group_description': "Customers who have spent over $1000 and have been with the business for over a year."
}
url = f'https://api.xtrakit.com/api/v1/customer-groups/{id}'
headers = {
"Authorization": "Bearer API_KEY" # Replace 'API_KEY' with your actual API key
}
try:
response = requests.put(url, headers=headers, json=data)
print(response.json())
except requests.exceptions.RequestException as e:
print(e)
```
{% endtab %}
{% endtabs %}
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"message": "Group updated successfully",
"data": {
"group": {
"id": 1,
"group_name": "Premium Customers",
"group_description": "Customers who have spent over $1000 and have been with the business for over a year.",
"created_at": "2024-08-04 08:23:45",
"updated_at": "2024-08-04 02:00:43"
}
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Payments
Welcome to the XtraPay Mobile Money Payment API documentation. The XtraPay API enables developers and businesses to seamlessly accept and verify Mobile Money payments within their websites and apps.
Fetch Payment Methods POST
Retrieve a list of all payment methods like MTN, AirtelTigo and Telecel
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": "1016",
"data": {
"accountId": "+23354xxxxxxxx",
"accountName": "Kofi Amartey"
},
"message": "Account resolution results."
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Initiate Payout
This endpoint performs the following actions:
* Validates and resolves the account holder's name for both bank accounts and MTN Mobile Money numbers.
* Creates and logs the transaction, preparing it
### Initiate remittance transaction
## Endpoint
**`POST`** `https://api.xtrakit.com/api/v1/payout/initiates`
## Headers
`Authorization: Bearer API_KEY`
## **Request Body**
{% tabs %}
{% tab title="MoMo Payout" %}
```php
//sample payout initiation request
//A. Mobile Money Payout (MoMo)
{
"business_code": "YOUR_BUSINESS_CODE",
"amount": 100.00,
"currency": "GHS",
"type": "momo",
"payment_method_id": "MOMO_MTN",
"payment_details": {
"recipient_name": "Kofi Mensah",
"account_number": "0240000000",
"phone_number": "0240000000",
"narration": "Payout for services"
}
}
```
{% endtab %}
{% tab title="Bank Payout" %}
```php
//sample payout initiation request
// B. Bank Account Payout (GhIPSS Instant Pay)
{
"business_code": "YOUR_BUSINESS_CODE",
"amount": 500.00,
"currency": "GHS",
"type": "bank",
"payment_method_id": "BANK",
"payment_details": {
"recipient_name": "Ama Serwaa",
"account_number": "1023456789012",
"bank_code": "300304",
"phone_number": "0240000000",
"narration": "Vendor invoice settlement"
}
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
| Parameter | Type | Required | Description |
| -------------------------------- | -------- | -------- | --------------------------------------------------------------------------- |
| `business_code` | `string` | **Yes** | Your business unique code from the merchant dashboard |
| `amount` | `number` | **Yes** | Amount to send (minimum `1.00`) |
| `currency` | `string` | No | Currency code (defaults to `GHS`) |
| `type` | `string` | **Yes** | Target type: `momo` or `bank` |
| `payment_method_id` | `string` | **Yes** | Method ID e.g. `MOMO_MTN`, `MOMO_TELECEL`, `MOMO_AT`, or Bank code `300304` |
| `payment_details` | `object` | **Yes** | Recipient and destination details |
| `payment_details.recipient_name` | `string` | **Yes** | Full name of the recipient / account holder |
| `payment_details.account_number` | `string` | **Yes** | Destination Mobile Money number or Bank account number |
| `payment_details.phone_number` | `string` | No | Recipient phone number (for SMS notification) |
| `payment_details.bank_code` | `string` | No | Bank routing code (required if `type` is `bank`, e.g. `300304` for GCB) |
| `payment_details.narration` | `string` | No | Reason or note for the payout (e.g. `Payout for Invoice #102`) |
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
//sample initiate payout momo payout response
{
"status": "000",
"data": {
"transaction_id": "PAYOUT-K9F2L9P0X1",
"interpay_trans_ref_no": "987654321",
"business_code": "YOUR_BUSINESS_CODE",
"amount": "100.00",
"fee": "1.00",
"currency": "GHS",
"status": "pending",
"created_at": "2026-08-22T11:15:00.000000Z"
},
"message": "Payout initiated and is being processed"
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Execute Payout Transaction
Executes previous initiate transaction This endpoint completes the payout to the specified accountId provided in the initiate endpoint.
**NB: Ensure you use the transactionId from the payout initiation.**
## Endpoint
**`POST`** `https://api.xtrakit.com/api/v1/payout/executes`
## Headers
`Authorization: Bearer API_KEY`
## **Request Body**
Parameters
Type
Description
transactionId
string
Required
Transaction reference generated by payout business
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": "1006",
"data": {
"xtrapayTransactionId": "BRJPAAS202509024xxxxxx",
"transactiondId": "Merchant-Transaction-Id"
},
"message": "Payout transaction is being processed"
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Query Transaction
Get transaction status.
## Query transaction status using your generated XtraPay transaction ID
## Endpoint
**`POST`** `https://api.xtrakit.com/api/v1/`payout/transaction/statu`s/{Xtrapay-Transaction-Id}`
## Headers
`Authorization: Bearer API_KEY`
## Sample Response
{% tabs %}
{% tab title="Success" %}
```json
{
"status": 200,
"data": {
"transaction_type": "api-payout",
"transaction_id": "Partner-Transaction-Id",
"interpay_trans_ref_no": "BRJPAAS2025xxxxxx",
"amount": "1.00",
"currency": "GHS",
"status": "successful",
"description": "Payout description",
"transaction_date": "2026-07-03T19:40:50.000000Z"
},
"message": "Transaction fetched"
}
```
{% endtab %}
{% tab title="Error" %}
```json
{
"status": 401,
"error": "Unauthorized: Missing Bearer Token"
},
{
"status": 401,
"error": "Unauthorized: Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
# Webhook
This is the request we make to the callback URL you have sent on the merchant dashboard
## Endpoint
**`POST`** `{YOUR CALLBACK URL}`
**How to set up a signed webhook**
Log in to your [XtraPay Account ](https://pay.xtrakit.com/)and go to:
Settings → Developers → [API Keys & Webhooks](https://pay.xtrakit.com/settings/developers).
Find the Callback Secret field, click to update, enter your secret key (without spaces), and then click Save.
**`NOTE:`** After configuring your webhook, every callback sent to your server will include an **HMAC-SHA256 signature**. You should verify this signature to confirm that the webhook originated from XtraPay and that the payload has not been altered during transmission.
## Headers
`Authorization: Bearer API_KEY`
Name
Key
Description
Signature
signature
The signature is an HMAC SHA256 hash of the raw webhook payload, generated using your Merchant Callback Secret. It is included in the request header to verify the source and integrity of the webhook.
The signature header is present only when a secret is configured; otherwise, it is not included.
