Payments

Unified resource for customer receipts (flow: INCOMING) and vendor payments (flow: OUTGOING). Create the payment and allocate it to invoices / bills in a single call, or split the work across two calls if you prefer.

Resource shape

{
  "payment_id":   "e8bf7b71-7437-4248-9b3e-cbb4ec48e945",
  "flow":         "INCOMING",            // INCOMING | OUTGOING
  "payment_type": "REGULAR",             // REGULAR | ADVANCE | REFUND
  "contact_id":   "50989551-…",
  "contact_name": "Ice Tales Foods Pvt Ltd",
  "date":         "2026-05-19T00:00:00",
  "amount":       11800.00,
  "mode":         "BANK_TRANSFER",       // CASH | BANK_TRANSFER | CHEQUE | UPI | CARD | OTHER
  "reference_number": "UTR-25051209",
  "description":  null,
  "currency_code":"INR",
  "exchange_rate":1.0,
  "bank_charges": 0.0,
  "tds_amount":   0.0,

  "allocations":  [
    {
      "allocation_id": "3052b92b-…",
      "invoice_id":    "72946802-…",     // null for OUTGOING allocations
      "bill_id":       null,             // null for INCOMING allocations
      "amount":        11800.00
    }
  ],
  "created_time": "...",
  "last_modified_time": "..."
}

Filter by ?flow=INCOMING or ?flow=OUTGOING to keep AR and AP traffic separate. Standard cursor pagination via ?cursor= and ?per_page=.

Create — one-shot (recommended)

Pass allocations[] to record the payment AND apply it to one or more invoices / bills in a single transaction. The journal entry posts immediately and the target document statuses update.

Required fields

Optional fields

Allocations array

Each entry must have exactly one of invoice_id (for INCOMING) or bill_id (for OUTGOING), plus an amount. The sum of allocation amounts may not exceed the payment amount.

Example — customer receipt against one invoice

POST /api/public/v1/payments
Authorization: Bearer aibk_pat_…
Content-Type: application/json

{
  "flow":             "INCOMING",
  "contact_id":       "50989551-…",
  "date":             "2026-05-19",
  "amount":           11800,
  "mode":             "BANK_TRANSFER",
  "bank_account_id":  "177b15de-…",   // HDFC current a/c
  "reference_number": "UTR-25051209",
  "allocations": [
    { "invoice_id": "72946802-…", "amount": 11800 }
  ]
}

Example — split across two invoices

{
  "flow":       "INCOMING",
  "contact_id": "50989551-…",
  "date":       "2026-05-19",
  "amount":     15000,
  "mode":       "BANK_TRANSFER",
  "allocations": [
    { "invoice_id": "<INV-A>", "amount": 11800 },
    { "invoice_id": "<INV-B>", "amount":  3200 }
  ]
}

Example — vendor payment against a bill

{
  "flow":       "OUTGOING",
  "contact_id": "<vendor-id>",
  "date":       "2026-05-19",
  "amount":     50000,
  "mode":       "BANK_TRANSFER",
  "allocations": [
    { "bill_id": "<bill-id>", "amount": 50000 }
  ]
}

Validation

• Sum of allocations[].amount > amount → 400 validation.invalid_value
• INCOMING with a bill_id in any allocation → 400
• OUTGOING with an invoice_id in any allocation → 400
• Allocation amount > target's outstanding balance → 400
• Contact / invoice / bill not in this org → 404

Create — two-step (advance receipts)

Omit allocations to record an unapplied receipt / advance. Apply it later — possibly across multiple invoices over time:

POST /api/public/v1/payments/<payment_id>/apply

{
  "invoice_id": "<invoice-id>",
  "amount":     11800
}

The apply endpoint takes one allocation per call. Call it repeatedly to split a receipt across multiple invoices/bills.

Journal entries

Journal entry posting is automatic and runs in the same transaction as the payment header:

• INCOMING: Dr Bank/Cash / Cr Accounts Receivable
• OUTGOING: Dr Accounts Payable / Cr Bank/Cash
• If tds_amount > 0 on INCOMING: Dr TDS Receivable for the withheld portion.
• If bank_charges > 0: Dr Bank Charges (expense).
• FX: an exchange gain/loss line is posted when the payment rate differs from the invoice/bill rate.

Webhooks emitted

• PAYMENT_RECEIVED on INCOMING create.
• PAYMENT_MADE on OUTGOING create.
• INVOICE_PAID when an allocation clears the invoice balance to zero.
• BILL_PAID when an allocation clears the bill balance to zero.

Update

Update a payment's fields and re-post its journal entry in one call. Every body field is optional— only what you send is changed; the rest is left as-is. The journal entry is regenerated with the correct poster for the payment's direction (receipt vs vendor payment).

Updatable fields

Example — correct the amount and reference of an unapplied receipt

PUT /api/public/v1/payments/<payment_id>
Authorization: Bearer aibk_pat_…
Content-Type: application/json

{
  "amount":           15000,
  "reference_number": "UTR-25051299",
  "description":      "revised per remittance advice"
}

Returns the full updated payment object (same shape as GET /payments/{id}), wrapped in the payment envelope.

Applied-payment guard

Changing amount while the payment is allocated to one or more invoices/bills returns:

409 Conflict
{
  "code":    "conflict.allocated",
  "message": "This payment is applied to invoices/bills. Unapply it before changing the amount, then re-apply.",
  "field":   "amount"
}

To re-amount an applied payment: delete its allocations (or the whole payment and recreate), update, then re-apply. Non-amount fields (date, reference, description, bank account, …) can still be updated while allocated.

Validation

• amount change on an allocated payment → 409 conflict.allocated
• bank_account_id not a BANK/CASH account in this org → 404 not_found.resource
• Payment not in this org → 404

Deleting a payment reverses the bank + AR/AP journal entries and restores the invoice / bill balance. Applied allocations are released and the target document status reverts to SENT / OPEN / PARTIALLY_PAID as appropriate.