Purchase Payment POST API Documentation

Purpose

This API creates a new purchase payment against a specific purchase invoice. A purchase payment represents money paid to a supplier (via cash, bank transfer, or another method) and can be applied to one or more purchase invoices.

Use Case

Record payments made to suppliers against outstanding invoices.
Track payment details including method, processor, reference, and notes.
Apply partial or full payments to one or more purchase invoices.
Store additional payment metadata using custom attributes.
Enable reconciliation and financial reporting.

Path Parameters

Parameter	Type	Required	Description
purchase_invoice_id	string	Yes	Unique identifier of the purchase invoice against which the payment is being created.

Query Parameters

This endpoint does not support query parameters.

Request Body

                JSON
              

                      {
    "purchase_payment": {
        "date": "DATE",
        "note": "NOTE",
        "effective_date": "EFFECTIVE_DATE",
        "purchase_payment_applied": [
            {
                "processor": "PAYMENT_PROCESSOR",
                "amount": "AMOUNT",
                "reference": "REFERENCE"
            }
        ]
    }
}
                    

Attribute	Type	Description
purchase_payment	object	Container for purchase payment details.
date	string (date)	The official date of the payment.
note	string	Optional note describing the payment.
effective_date	string (date)	Date when the payment becomes effective. If set to current date, effective immediately.
purchase_payment_applied	array	List of payment applications detailing method, processor, amount, and reference.

Response

The response returns a purchase_payment object containing all details of the newly created payment. It includes the system-generated payment ID, status, total applied amount, and links to the purchase order and invoices affected by the payment. It also provides metadata such as created by, creation timestamps, UUID, and version number. In addition, it includes details of the applied payment methods (example: Cash), any credits applied, invoice allocation breakdown (applied, outstanding, total), and any configured custom attributes or custom objects. This ensures full traceability of how the payment was recorded and linked across supplier records.

Response Body

                JSON
              

                      {
    "purchase_payment": {
        "status": "STATUS",
        "id": "PURCHASE_PAYMENT_ID",
        "origin": "ORIGIN",
        "purchase_payment_date": "PURCHASE_PAYMENT_DATE",
        "total_applied": "TOTAL_APPLIED",
        "purchase_order_id": "PURCHASE_ORDER_ID",
        "purchase_payment_note": "PURCHASE_PAYMENT_NOTE",
        "purchase_payment_applied": [
            {
                "id": "APPLIED_ID",
                "amount": "APPLIED_AMOUNT",
                "method": "PAYMENT_METHOD",
                "processor": "PAYMENT_PROCESSOR",
                "reference": "REFERENCE"
            }
        ],
        "purchase_credit_applied": [],
        "purchase_invoices": [
            {
                "applied": "INVOICE_APPLIED_AMOUNT",
                "id": "INVOICE_ID",
                "due_date": "INVOICE_DUE_DATE",
                "issue_date": "INVOICE_ISSUE_DATE",
                "outstanding": "INVOICE_OUTSTANDING",
                "total": "INVOICE_TOTAL"
            }
        ],
        "created_by": "CREATED_BY",
        "created_on": "CREATED_ON",
        "last_updated_by": "LAST_UPDATED_BY",
        "last_updated_on": "LAST_UPDATED_ON",
        "uuid": "UUID",
        "version": "VERSION",
        "custom_attributes": [
            { "name": "CUSTOM_ATTRIBUTE_NAME", "value": "CUSTOM_ATTRIBUTE_VALUE" },
            { "name": "CUSTOM_ATTRIBUTE_NAME", "value": "CUSTOM_ATTRIBUTE_VALUE" },
            { "name": "CUSTOM_ATTRIBUTE_NAME", "value": "CUSTOM_ATTRIBUTE_VALUE" },
            { "name": "CUSTOM_ATTRIBUTE_NAME", "value": "CUSTOM_ATTRIBUTE_VALUE" },
            { "name": "CUSTOM_ATTRIBUTE_NAME", "value": "CUSTOM_ATTRIBUTE_VALUE" },
            { "name": "CUSTOM_ATTRIBUTE_NAME", "value": "CUSTOM_ATTRIBUTE_VALUE" }
        ],
        "custom_objects": []
    }
}
                    

Attribute	Type	Description
purchase_payment	object	Container for the created purchase payment details.
status	string	Status of the payment (example: `ACTIVE`).
id	string	System-generated unique identifier for the purchase payment.
origin	string	Source/origin of the payment (blank if created manually).
purchase_payment_date	string (date-time)	The official payment date recorded (ISO 8601 format).
total_applied	string (decimal)	Total amount applied in this payment transaction.
purchase_order_id	string	The purchase order linked with this payment.
purchase_payment_note	string	Note attached to this payment.
purchase_payment_applied	array	List of payment applications applied against this payment.
purchase_payment_applied[].id	integer	System-generated identifier of the applied payment record.
purchase_payment_applied[].amount	decimal	Amount applied using this method.
purchase_payment_applied[].method	string	Method of payment (example: Cash, Bank, Cheque).
purchase_payment_applied[].processor	string	Processor or channel through which payment was made.
purchase_payment_applied[].reference	string	Reference string for identifying the payment (example: transaction ID).
purchase_credit_applied	array	List of purchase credits applied to this payment (empty if none).
purchase_invoices	array	List of purchase invoices affected by this payment.
purchase_invoices[].applied	decimal	Amount applied to the given invoice.
purchase_invoices[].id	string	Unique identifier of the purchase invoice.
purchase_invoices[].due_date	string (date-time)	Due date of the invoice.
purchase_invoices[].issue_date	string (date-time)	Issue date of the invoice.
purchase_invoices[].outstanding	decimal	Outstanding balance remaining on the invoice after payment.
purchase_invoices[].total	decimal	Total amount of the invoice.
created_by	string	User who created the payment record.
created_on	string (date-time)	Timestamp of payment creation.
last_updated_by	string	User who last updated the payment record.
last_updated_on	string (date-time)	Timestamp of last update.
uuid	string (UUID)	Unique identifier of the purchase payment record.
version	string	Version number for concurrency control.
custom_attributes	array	List of custom attributes attached to the payment.
custom_attributes[].name	string	Name of the custom attribute.
custom_attributes[].value	string	Value of the custom attribute.
custom_objects	array	List of custom objects linked to this payment (empty if none).