Bank Disbursement

This endpoint is used to initiate a bank disbursement from a merchant wallet to a beneficiary bank account.

Sandbox Endpoint

POST https://api.lipila.dev/api/v1/disbursements/bank

---

Headers

The following headers are accepted.

Header	Type	Description	Required
accept	application/json	Expected response format	Yes
x-api-key	string	Merchant API authentication key	Yes
Content-Type	application/json	Request payload format	Yes
callbackUrl	string	URL to receive asynchronous callback notifications	Optional

---

Request Body

The following fields are expected in the request payload.

Field	Type	Description	Required
referenceId	string	Unique reference ID for the disbursement transaction	Yes
amount	number	Amount to be disbursed	Yes
currency	string	Transaction currency (e.g. ZMW)	Yes
narration	string	Description or narration for the disbursement	Yes
accountNumber	string	Beneficiary bank account number	Yes
swiftCode	string	Bank SWIFT code	Yes
firstName	string	Beneficiary first name	Yes
lastName	string	Beneficiary last name	Yes
accountHolderName	string	Full name of the account holder	Yes
phoneNumber	string	Beneficiary mobile number	Yes
email	string	Beneficiary email	No
callbackUrl	string	callback url	No

---

Example Request

cURL

curl -X 'POST' \
  'https://api.lipila.dev/api/v1/disbursements/bank' \
  -H 'accept: application/json' \
  -H 'x-api-key: your_api_key' \
  -H 'callbackUrl: https://lipila.io/callback' \
  -H 'Content-Type: application/json' \
  -d '{
  "referenceId": "12345", // Use this Id to check the transaction status
  "amount": 1,
  "narration": "Settlement Payout",
  "accountNumber": "532346464756758674654744564646546464",
  "currency": "ZMW",
  "swiftCode": "ZNCOZMLU",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "260xxxxxxxxx",
  "accountHolderName": "John Doe"
}'

Python

import requests

url = "https://api.lipila.dev/api/v1/disbursements/bank"

headers = {
    "accept": "application/json",
    "x-api-key": "your_api_key",
    "callbackUrl": "https://lipila.io/callback",
    "Content-Type": "application/json"
}

payload = {
    "referenceId": "12345",
    "amount": 1,
    "narration": "Settlement Payout",
    "accountNumber": "532346464756758674654744564646546464",
    "currency": "ZMW",
    "swiftCode": "ZNCOZMLU",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "260xxxxxxxxx",
    "accountHolderName": "John Doe"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

C#

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();

client.DefaultRequestHeaders.Add("accept", "application/json");
client.DefaultRequestHeaders.Add("x-api-key", "your_api_key");
client.DefaultRequestHeaders.Add("callbackUrl", "https://lipila.io/callback");

var payload = new {
    referenceId = "12345",
    amount = 1,
    narration = "Settlement Payout",
    accountNumber = "532346464756758674654744564646546464",
    currency = "ZMW",
    swiftCode = "ZNCOZMLU",
    firstName = "John",
    lastName = "Doe",
    phoneNumber = "260xxxxxxxxx",
    accountHolderName = "John Doe"
};

var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.lipila.dev/api/v1/disbursements/bank",
    content
);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Node.js

const response = await fetch("https://api.lipila.dev/api/v1/disbursements/bank", {
  method: "POST",
  headers: {
    "accept": "application/json",
    "x-api-key": "your_api_key",
    "callbackUrl": "https://lipila.io/callback",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    referenceId: "12345", 
    amount: 1,
    narration: "Settlement Payout",
    accountNumber: "532346464756758674654744564646546464",
    currency: "ZMW",
    swiftCode: "ZNCOZMLU",
    firstName: "John",
    lastName: "Doe",
    phoneNumber: "260xxxxxxxxx",
    accountHolderName: "John Doe"
  })
});

const data = await response.json();
console.log(data);

PHP

<?php

$url = "https://api.lipila.dev/api/v1/disbursements/bank";

$headers = [
    "accept: application/json",
    "x-api-key: your_api_key",
    "callbackUrl: https://lipila.io/callback",
    "Content-Type: application/json"
];

$payload = json_encode([
    "referenceId" => "12345",
    "amount" => 1,
    "narration" => "Settlement Payout",
    "accountNumber" => "532346464756758674654744564646546464",
    "currency" => "ZMW",
    "swiftCode" => "ZNCOZMLU",
    "firstName" => "John",
    "lastName" => "Doe",
    "phoneNumber" => "260xxxxxxxxx",
    "accountHolderName" => "John Doe"
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Important

referenceId should always be unique

Example Successful Response

Below is an example successful response.

HTTP Status Code	Description
200	SUCCESS

{
  "amount": 1,
  "externalId": null,
  "narration": "Settlement Payout",
  "ipAddress": "102.212.181.61",
  "referenceId": "12345",
  "status": "Pending",
  "currency": "ZMW",
  "type": "Disbursement",
  "accountNumber": "532346464756758674654744564646546464",
  "paymentType": "Bank",
  "createdAt": "2025-12-09T09:56:35.4174786+00:00",
  "identifier": "LPLXD-20261209-095635-417-2344"
}

Error Codes

HTTP Status Code	Error Code	Description
400	BAD REQUEST	Invalid or missing request parameters
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	API key is inactive or unauthorized
429	TOO MANY REQUESTS	Rate limit exceeded, slow down requests

Important

Do not share your api key with anyone, Use permissions on your dashboard to keep it safe.