Record a payment against an invoice

POST

/api/public/v1/invoices/{invoice_id}/payments

Code sample: cURL

curl --request POST \
  --url 'https://api.getzutax.com/api/public/v1/invoices/f3df2967-7cbe-4cca-8c8c-975ee2f6857f/payments' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <unique-request-key>' \
  --data '{
  "external_id": "pay-bank-2026-0001",
  "amount_naira": 231125,
  "method": "bank_transfer",
  "reference": "NIP-TRF-928344102",
  "received_at": "2026-02-14T09:30:00Z",
  "notes": "Customer paid via bank transfer."
}'

• Production API
• Staging API

Records a payment on the invoice’s immutable payment ledger. Idempotent on (invoice_id, external_id) — a duplicate external_id for the same invoice returns 409 conflict.

Authorizations

• HTTPBearer

Parameters

Path Parameters

invoice_id

required

Invoice Id

string format: uuid

Request Body ^required

Media type application/json

PaymentCreateInput

object

external_id

required

External Id

string

>= 1 characters <= 255 characters

amount_naira

required

Any of:

number

number

> 0

string

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

method

required

Method

string

Allowed values: flutterwave bank_transfer cash manual

reference

Any of:

string

string

null

null

received_at

required

Received At

string format: date-time

notes

Any of:

string

string

null

null

Examples

Example Bank transfer payment

Record a customer payment against an invoice

{
  "external_id": "pay-bank-2026-0001",
  "amount_naira": 231125,
  "method": "bank_transfer",
  "reference": "NIP-TRF-928344102",
  "received_at": "2026-02-14T09:30:00Z",
  "notes": "Customer paid via bank transfer."
}

Responses

200

Successful Response

Media type application/json

PaymentResponse

object

id

required

Id

string format: uuid

external_id

required

Any of:

string

string

null

null

invoice_id

required

Invoice Id

string format: uuid

amount_naira

required

Amount Naira

string

/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/

method

required

Method

string

Allowed values: flutterwave bank_transfer cash manual

reference

required

Any of:

string

string

null

null

received_at

required

Received At

string format: date-time

Examples

Example Sample response

200 response example

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "external_id": "string",
  "invoice_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount_naira": "100.00",
  "method": "flutterwave",
  "reference": "string",
  "received_at": "2026-02-11T10:00:00Z"
}

422

Validation Error

Media type application/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Examples

Example Sample response

422 response example

{
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string"
    }
  ]
}