Invoice Payments (Offline/Manual Recording)

Record payments against invoices that were received through offline/manual methods (cash, bank transfers, checks, etc.).

WARNING

Offline Payments Only

This endpoint is for recording payments received OUTSIDE the Jokoor platform.

✅ Use this for:

Cash payments

Direct bank transfers

Checks/cheques

Western Union, MoneyGram

Any payment received outside Jokoor

❌ Don't use this for:

Wave, Afrimoney, Card, QMoney payments

For online payments, customers should visit the invoice payment_url (the hosted page handles payment processing automatically)

How It Works

When you record an offline payment:

Creates an "offline" transaction in the system

Updates invoice amounts:

Increases paid_amount

Decreases remaining_amount

Automatically generates a receipt for the payment

Updates invoice status:

partially_paid if amount < remaining amount

paid if amount = remaining amount

Record Invoice Payment

Record a payment received through offline/manual methods.

Endpoint: POST /v1/pay/invoices/{id}/payments

Authentication: Required

Request Body:

Field	Type	Required	Description
`amount`	string	Yes	Payment amount as decimal string (e.g., "500.00")
`payment_method`	string	Yes	Payment method used (e.g., `cash`, `bank_transfer`, `check`, `western_union`, `other`)
`transaction_id`	string	No	External transaction reference ID (e.g., bank transaction number, check number)
`notes`	string	No	Payment notes or remarks (e.g., "Received via Chase Bank, Ref: CHK-123456")

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "id": "inv_abc123",
    "invoice_number": "INV-2024-12-0001",
    "total_amount": "1150.00",
    "paid_amount": "500.00",
    "remaining_amount": "650.00",
    "status": "partially_paid"
  }
}

TIP

Partial Payments: You can record multiple partial payments until the invoice is fully paid. The invoice status automatically updates to partially_paid or paid. A receipt is automatically generated for each payment recorded.

INFO

Transaction Record: Recording an offline payment automatically creates a transaction with:

payment_type: "offline"

payment_method: Your specified method (e.g., "cash", "bank_transfer")

status: "completed"

Automatic receipt generation

Common Use Cases

Cash Payment

Bank Transfer with Reference

Check Payment

Partial Payment

List Invoice Payments

Get all payments recorded against an invoice.

Endpoint: GET /v1/pay/invoices/{id}/payments

Success Response (200):

{
  "data": [
    {
      "id": "invpay_123",
      "invoice_id": "inv_abc123",
      "amount": "500.00",
      "currency": "GMD",
      "payment_method": "bank_transfer",
      "transaction_id": "TXN123456",
      "payment_date": "2024-01-15T14:30:00Z",
      "notes": "Payment received via bank transfer",
      "created_at": "2024-01-15T14:30:00Z"
    }
  ]
}

Get Invoice Receipts

Get all payment receipts associated with an invoice.

Endpoint: GET /v1/pay/invoices/{id}/receipts

Invoice Payments (Offline/Manual Recording)

How It Works#

Record Invoice Payment#

Common Use Cases#

Cash Payment#

Bank Transfer with Reference#

Check Payment#

Partial Payment#

List Invoice Payments#

Get Invoice Receipts#

How It Works

Record Invoice Payment

Common Use Cases

Cash Payment

Bank Transfer with Reference

Check Payment

Partial Payment

List Invoice Payments

Get Invoice Receipts