Tracepos Developer HubTracepos Developer Hub
Home
Guide
POS & Integrations
API Reference
Webhooks
Postman Collection
Home
Guide
POS & Integrations
API Reference
Webhooks
Postman Collection
  • Overview & Specifications

    • Tracepos Public API Reference
  • Core Catalog & Outlets

    • Products API
    • Categories & Brands API
    • Warehouses & Outlets API
  • Parties & CRM

    • Customers & Suppliers API
  • Operations & Stock

    • Sales & Transactions API
    • Purchases & Procurement API
    • Inventory & Price Adjustments API
    • Returns & Reversals API
  • Financial Ledger & Expenses

    • Payments & Settlements API
    • Expense Management API
    • Double-Entry Accounting Architecture
  • Real-Time Sync

    • Webhooks & Real-Time Sync

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.

GET/api/v1/public/payment-modesScope: read

Headers

HeaderTypeRequiredDescription
X-Tracepos-Public-KeyStringYesWarehouse public API key
X-Tracepos-Secret-KeyStringYesWarehouse secret API key
AcceptStringYesapplication/json

Code Samples

cURL
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"
Node.js (Axios)
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;
}
Python (Requests)
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 (Guzzle)
<?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.

GET/api/v1/public/paymentsScope: read

Query Parameters

ParameterTypeDefaultDescription
datesString-Filter by date range YYYY-MM-DD,YYYY-MM-DD.
payment_modeString-Filter by payment mode type (cash, bank).
limitInteger20Results per page (max: 100).
pageInteger1Page number.

Code Samples

cURL
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"
Node.js (Axios)
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;
}
Python (Requests)
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 (Guzzle)
<?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.

GET/api/v1/public/payments/user-invoicesScope: read

Query Parameters

ParameterTypeRequiredDescription
user_idString / IntegerYesParty Hash ID (xid) or numeric ID.
payment_typeStringYesSet 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.

GET/api/v1/public/payments/customer-suppliersScope: read

Response (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.

POST/api/v1/public/paymentsScope: write

Request Parameters

ParameterTypeRequiredDescription
user_idString / IntegerYesCustomer xid or Supplier xid.
amountNumericYesTotal tender amount (min: 0.01).
payment_typeStringYes'in' (Customer payment) or 'out' (Supplier disbursement).
payment_mode_idString / IntegerYesPayment mode xid (discovered via GET /payment-modes).
dateDateYesTransaction date (YYYY-MM-DD).
invoicesArrayNoInvoice allocation array for specific invoice reconciliation.
invoices[].order_idString / IntegerYes (if allocating)Sale or purchase order xid (or numeric ID).
invoices[].amountNumericYes (if allocating)Amount credited to this specific invoice.
notesStringNoPayment 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
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"
  }'
Node.js (Axios)
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;
}
Python (Requests)
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 (Guzzle)
<?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: 11500 Accounts Receivable (reducing customer debt)
  • Supplier Payment (payment_type = "out"):
    • Debit: 21100 Accounts Payable (reducing vendor debt)
    • Credit: 11100 (Cash on Hand) or Payment Mode Linked Bank Account
Next
Expense Management API