Payments & Settlements API
In Tracepos, payments are direct double-entry ledger transactions that settle outstanding receivables (A/R from customers) or payables (A/P to suppliers).
The Payments API supports:
- Payment Mode Discovery: Discovering active payment modes (Cash, Bank, POS Card) configured for the warehouse.
- Bulk Invoice Settlement: Distributing a single lump-sum wire or POS card transfer across multiple outstanding invoices.
- On-Account Float: Accepting advance unallocated credit recorded against a customer's ledger (
unused_amount). - Multi-Tender Reconciliation: Tracking cash, POS cards, direct bank debits, and mobile wallets.
1. List Payment Modes
Discover available payment methods enabled for the authenticated warehouse branch. Every payment and sale transaction requires a valid payment_mode_id.
/api/v1/public/payment-modesScope: readHeaders
| Header | Type | Required | Description |
|---|---|---|---|
X-Tracepos-Public-Key | String | Yes | Warehouse public API key |
X-Tracepos-Secret-Key | String | Yes | Warehouse secret API key |
Accept | String | Yes | application/json |
Code Samples
curl -X GET "https://app.tracepos.net/api/v1/public/payment-modes" \
-H "X-Tracepos-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Tracepos-Secret-Key: YOUR_SECRET_KEY" \
-H "Accept: application/json"
const axios = require('axios');
async function getPaymentModes() {
const response = await axios.get('https://app.tracepos.net/api/v1/public/payment-modes', {
headers: {
'X-Tracepos-Public-Key': process.env.TRACEPOS_PUBLIC_KEY,
'X-Tracepos-Secret-Key': process.env.TRACEPOS_SECRET_KEY,
'Accept': 'application/json',
},
});
return response.data.data;
}
import os
import requests
headers = {
"X-Tracepos-Public-Key": os.getenv("TRACEPOS_PUBLIC_KEY"),
"X-Tracepos-Secret-Key": os.getenv("TRACEPOS_SECRET_KEY"),
"Accept": "application/json",
}
response = requests.get("https://app.tracepos.net/api/v1/public/payment-modes", headers=headers)
print(response.json())
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client(['base_uri' => 'https://app.tracepos.net/api/v1/public/']);
$response = $client->get('payment-modes', [
'headers' => [
'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
'Accept' => 'application/json',
],
]);
echo $response->getBody();
Response (200 OK)
{
"status": "success",
"data": {
"current_page": 1,
"per_page": 20,
"total": 4,
"data": [
{
"id": 1,
"name": "Cash",
"mode_type": "cash",
"warehouse_id": null,
"is_global": 1
},
{
"id": 2,
"name": "POS Terminal Card",
"mode_type": "bank",
"warehouse_id": 1,
"is_global": 0
},
{
"id": 3,
"name": "Bank Transfer",
"mode_type": "bank",
"warehouse_id": null,
"is_global": 1
}
]
}
}
2. List Payments History
Retrieve recorded incoming and outgoing payments for the authorized warehouse.
/api/v1/public/paymentsScope: readQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dates | String | - | Filter by date range YYYY-MM-DD,YYYY-MM-DD. |
payment_mode | String | - | Filter by payment mode type (cash, bank). |
limit | Integer | 20 | Results per page (max: 100). |
page | Integer | 1 | Page number. |
Code Samples
curl -X GET "https://app.tracepos.net/api/v1/public/payments?payment_mode=bank&limit=20" \
-H "X-Tracepos-Public-Key: YOUR_PUBLIC_KEY" \
-H "X-Tracepos-Secret-Key: YOUR_SECRET_KEY" \
-H "Accept: application/json"
const axios = require('axios');
async function listPayments() {
const response = await axios.get('https://app.tracepos.net/api/v1/public/payments', {
params: { limit: 20 },
headers: {
'X-Tracepos-Public-Key': process.env.TRACEPOS_PUBLIC_KEY,
'X-Tracepos-Secret-Key': process.env.TRACEPOS_SECRET_KEY,
'Accept': 'application/json',
},
});
return response.data.data;
}
import os
import requests
headers = {
"X-Tracepos-Public-Key": os.getenv("TRACEPOS_PUBLIC_KEY"),
"X-Tracepos-Secret-Key": os.getenv("TRACEPOS_SECRET_KEY"),
"Accept": "application/json",
}
response = requests.get(
"https://app.tracepos.net/api/v1/public/payments",
params={"limit": 20},
headers=headers,
)
payments = response.json().get("data", {})
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client(['base_uri' => 'https://app.tracepos.net/api/v1/public/']);
$response = $client->get('payments', [
'headers' => [
'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
'Accept' => 'application/json',
],
]);
$payments = json_decode($response->getBody()->getContents(), true)['data'];
Response (200 OK)
{
"status": "success",
"data": {
"current_page": 1,
"per_page": 20,
"total": 120,
"data": [
{
"id": 88,
"payment_number": "PAY-IN-48",
"payment_type": "in",
"amount": "15000.00",
"paid_amount": "15000.00",
"unused_amount": "0.00",
"date": "2026-09-30",
"user": {
"id": 105,
"name": "Adeola Adeleke"
},
"payment_mode": {
"id": 2,
"name": "POS Terminal Card"
}
}
]
}
}
3. Discover Unpaid Invoices
Before collecting funds or initiating a payout, query all unpaid or partially paid invoices for a given customer or supplier.
/api/v1/public/payments/user-invoicesScope: readQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id | String / Integer | Yes | Party Hash ID (xid) or numeric ID. |
payment_type | String | Yes | Set payment_type=in for sales and purchase-return invoices; any other value (e.g. out) retrieves purchase and sales-return invoices. |
Response (200 OK)
{
"status": "success",
"data": [
{
"id": 182,
"xid": "ord_9182ab3c4d5e",
"invoice_number": "SAL-00451",
"order_type": "sales",
"order_date": "2026-09-28",
"total": "10000.00",
"paid_amount": "0.00",
"due_amount": "10000.00",
"payment_status": "unpaid"
},
{
"id": 183,
"xid": "ord_8912bc3d4e5f",
"invoice_number": "SAL-00452",
"order_type": "sales",
"order_date": "2026-09-29",
"total": "5000.00",
"paid_amount": "0.00",
"due_amount": "5000.00",
"payment_status": "unpaid"
}
]
}
4. List Customer & Supplier Directory
Fetch a lightweight directory of all parties (customers and suppliers) eligible for payments within the company.
/api/v1/public/payments/customer-suppliersScope: readResponse (200 OK)
{
"status": "success",
"data": [
{
"id": 105,
"xid": "usr_9x8a7b6c5d4e",
"name": "Adeola Adeleke",
"user_type": "customers"
},
{
"id": 201,
"xid": "usr_7z6y5x4w3v2u",
"name": "Dangote Sugar Refinery Plc",
"user_type": "suppliers"
}
]
}
5. Record Payment & Settle Invoices
Record an inward customer collection or an outward supplier disbursement.
/api/v1/public/paymentsScope: writeRequest Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id | String / Integer | Yes | Customer xid or Supplier xid. |
amount | Numeric | Yes | Total tender amount (min: 0.01). |
payment_type | String | Yes | 'in' (Customer payment) or 'out' (Supplier disbursement). |
payment_mode_id | String / Integer | Yes | Payment mode xid (discovered via GET /payment-modes). |
date | Date | Yes | Transaction date (YYYY-MM-DD). |
invoices | Array | No | Invoice allocation array for specific invoice reconciliation. |
invoices[].order_id | String / Integer | Yes (if allocating) | Sale or purchase order xid (or numeric ID). |
invoices[].amount | Numeric | Yes (if allocating) | Amount credited to this specific invoice. |
notes | String | No | Payment description or bank transaction reference. |
Request Payload Example
{
"user_id": "<customer-or-supplier-xid>",
"amount": 3000,
"payment_type": "in",
"payment_mode_id": "<payment-mode-xid>",
"date": "2026-10-02"
}
Code Samples
curl -X POST "https://app.tracepos.net/api/v1/public/payments" \
-H "X-Tracepos-Public-Key: <public-key>" \
-H "X-Tracepos-Secret-Key: <secret-key>" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"user_id": "<customer-or-supplier-xid>",
"payment_type": "in",
"amount": 3000.00,
"payment_mode_id": "<payment-mode-xid>",
"date": "2026-10-02",
"invoices": [
{"order_id": "<order-xid>", "amount": 3000.00}
],
"notes": "POS Settlement Ref: TXN-POS-893012"
}'
const axios = require('axios');
async function recordPayment() {
const payload = {
user_id: '<customer-or-supplier-xid>',
payment_type: 'in',
amount: 3000.00,
payment_mode_id: '<payment-mode-xid>',
date: '2026-10-02',
invoices: [
{ order_id: '<order-xid>', amount: 3000.00 }
],
notes: 'POS Settlement Ref: TXN-POS-893012',
};
const response = await axios.post(
'https://app.tracepos.net/api/v1/public/payments',
payload,
{
headers: {
'X-Tracepos-Public-Key': process.env.TRACEPOS_PUBLIC_KEY,
'X-Tracepos-Secret-Key': process.env.TRACEPOS_SECRET_KEY,
'Content-Type': 'application/json',
'Accept': 'application/json',
},
}
);
return response.data;
}
import os
import requests
headers = {
"X-Tracepos-Public-Key": os.getenv("TRACEPOS_PUBLIC_KEY"),
"X-Tracepos-Secret-Key": os.getenv("TRACEPOS_SECRET_KEY"),
"Content-Type": "application/json",
"Accept": "application/json",
}
payload = {
"user_id": "<customer-or-supplier-xid>",
"payment_type": "in",
"amount": 3000.00,
"payment_mode_id": "<payment-mode-xid>",
"date": "2026-10-02",
"invoices": [
{"order_id": "<order-xid>", "amount": 3000.00}
],
"notes": "POS Settlement Ref: TXN-POS-893012",
}
response = requests.post("https://app.tracepos.net/api/v1/public/payments", json=payload, headers=headers)
print(response.json())
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client(['base_uri' => 'https://app.tracepos.net/api/v1/public/']);
$response = $client->post('payments', [
'headers' => [
'X-Tracepos-Public-Key' => getenv('TRACEPOS_PUBLIC_KEY'),
'X-Tracepos-Secret-Key' => getenv('TRACEPOS_SECRET_KEY'),
'Content-Type' => 'application/json',
'Accept' => 'application/json',
],
'json' => [
'user_id' => '<customer-or-supplier-xid>',
'payment_type' => 'in',
'amount' => 3000.00,
'payment_mode_id' => '<payment-mode-xid>',
'date' => '2026-10-02',
'invoices' => [
['order_id' => '<order-xid>', 'amount' => 3000.00],
],
'notes' => 'POS Settlement Ref: TXN-POS-893012',
],
]);
$result = json_decode($response->getBody()->getContents(), true);
echo print_r($result, true);
Response (200 OK)
{
"status": "success",
"payment_number": "PAY-IN-48",
"journal_entry_xid": "jent_8192a7b6c5d4",
"unused_amount": 0
}
Double-Entry Posting Logic
Every payment produces a balanced journal entry generated by AccountingService:
- Customer Payment (
payment_type = "in"):- Debit:
11100(Cash on Hand) or Payment Mode Linked Bank Account - Credit:
11500Accounts Receivable (reducing customer debt)
- Debit:
- Supplier Payment (
payment_type = "out"):- Debit:
21100Accounts Payable (reducing vendor debt) - Credit:
11100(Cash on Hand) or Payment Mode Linked Bank Account
- Debit:
