Create Purchase Payment: /purchase-payments
Purpose
This API is used to create a new purchase payment record in the system. A purchase payment represents the settlement of outstanding amounts on purchase invoices using one or more payment methods linked to a supplier account. Supported methods include cash, cheque, bank deposit, and credit notes. The endpoint records payment details such as applied invoices, payment methods, processors, references, and notes. It also supports applying multiple payment methods in a single transaction, ensuring flexibility in how invoices are settled.
Use Case
This endpoint is used to record payments made to suppliers for outstanding purchase invoices. It supports scenarios such as partial payments across different methods (part cash and part bank deposit), applying credits from purchase credit notes, and attaching metadata such as notes, effective dates, and custom attributes. The API ensures that payments are properly tracked, reconciled, and linked to the correct invoices and purchase orders, supporting accurate financial management and reporting.
Path Parameters
This endpoint does not require path parameters.
Query Parameters
This endpoint does not require query parameters.
Request Body
{
"purchase_payment": {
"id": "PAYMENT_ID",
"date": "PAYMENT_DATE",
"note": "PAYMENT_NOTE",
"effective_date": "EFFECTIVE_DATE",
"purchase_invoices": [
{
"id": "INVOICE_ID",
"amount": "INVOICE_AMOUNT"
}
],
"purchase_payment_applied": [
{
"processor": "PAYMENT_PROCESSOR",
"amount": "AMOUNT",
"reference": "REFERENCE"
},
{
"processor": "PAYMENT_PROCESSOR",
"amount": "AMOUNT"
}
]
}
}
| Attribute | Type | Description |
|---|---|---|
| purchase_payment | Object | Contains all details for creating the purchase payment. |
| id | String | Unique identifier for the purchase payment record. |
| date | Date | Date when the payment is created. |
| note | String | Optional note or remark for the payment. |
| effective_date | Date | The date when the payment becomes effective. If current date, it is effective immediately. |
| purchase_invoices | Array | List of purchase invoices to which the payment will be applied. |
| id | String | Identifier of the purchase invoice being paid. |
| amount | Decimal | Amount from the payment applied to the invoice. |
| purchase_payment_applied | Array | List of payment entries detailing methods and amounts. |
| processor | String | Payment processor name (example: Cash, Bank Deposit, Online). |
| amount | Decimal | Payment amount for the corresponding processor. |
| reference | String | Optional reference for tracking payment source or transaction ID. |
Response
On success, the API returns a purchase_payment object containing the details of the newly created payment record. High-level attributes include payment status, ID, payment date, total applied amount, and any linked purchase order. Nested structures provide granular details:
- purchase_payment_applied: lists the distribution of amounts across payment methods, processors, and references.
- purchase_credit_applied: shows credits applied from purchase credit notes, if any.
- purchase_invoices: details invoice-level data such as applied amounts, totals, outstanding balances, issue dates, and due dates.
Additional metadata includes creator details, timestamps, UUID, versioning, and any custom attributes or objects. This structure confirms that the payment has been successfully recorded, applied to the correct invoices, and is available for reconciliation, reporting, and auditing.
Response Body
{
"purchase_payment": {
"status": "STATUS",
"id": "PAYMENT_ID",
"origin": "ORIGIN",
"purchase_payment_date": "PAYMENT_DATE",
"total_applied": "TOTAL_APPLIED_AMOUNT",
"purchase_order_id": "PURCHASE_ORDER_ID",
"purchase_payment_note": "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": "APPLIED_AMOUNT",
"id": "INVOICE_ID",
"due_date": "DUE_DATE",
"issue_date": "ISSUE_DATE",
"outstanding": "OUTSTANDING_AMOUNT",
"total": "TOTAL_AMOUNT"
}
],
"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": [],
"custom_objects": []
}
}
| Attribute | Type | Description |
|---|---|---|
| purchase_payment | Object | Contains all details of the created purchase payment record. |
| status | String | Current status of the purchase payment (example: ACTIVE). |
| id | String | Unique identifier of the purchase payment. |
| origin | String | Source of creation for the payment (if applicable). |
| purchase_payment_date | DateTime | Date when the payment was recorded in the system. |
| total_applied | Decimal | Total amount applied from all payment methods combined. |
| purchase_order_id | String | Identifier of the related purchase order, if applicable. |
| purchase_payment_note | String | Note or remark associated with the payment. |
| purchase_payment_applied | Array | List of payment method entries used in the transaction. |
| id | Integer | System-generated ID of the payment method record. |
| amount | Decimal | Amount applied using the specified payment method. |
| method | String | Payment method used (example: Cash, Bank Deposit). |
| processor | String | Payment processor or channel name. |
| reference | String | Optional reference or transaction identifier. |
| purchase_credit_applied | Array | List of applied purchase credits (if any). |
| purchase_invoices | Array | List of purchase invoices linked to this payment. |
| applied | Decimal | Amount applied to the specific invoice. |
| id | String | Identifier of the purchase invoice. |
| due_date | DateTime | Due date of the invoice. |
| issue_date | DateTime | Issue date of the invoice. |
| outstanding | Decimal | Remaining amount due on the invoice after payment. |
| total | Decimal | Total amount of the purchase invoice. |
| created_by | String | Username of the user who created the record. |
| created_on | DateTime | Timestamp when the record was created. |
| last_updated_by | String | Username of the user who last updated the record. |
| last_updated_on | DateTime | Timestamp when the record was last updated. |
| uuid | UUID | System-generated unique identifier of the purchase payment record. |
| version | String | Version number of the purchase payment record. |
| custom_attributes | Array | List of custom attributes linked to the payment. |
| custom_objects | Array | List of custom objects linked to the payment. |
Create a Purchase Payment for a Specific Purchase Invoice: /purchase-invoices/{purchase_invoice_id}/purchase-payments
Purpose
This API creates a new purchase payment against a specific purchase invoice. A purchase payment represents money paid to a supplier using one or more payment methods such as cash, cheque, bank deposit, credit notes, or online processors. The endpoint allows businesses to record payments directly against outstanding invoices, ensuring that settlements are properly tracked and reconciled. It also supports storing additional metadata such as notes, effective dates, and custom attributes for flexible financial management.
Use Case
This endpoint is used to suppliers for outstanding purchase invoices. It supports scenarios such as applying partial or full payments, distributing amounts across multiple payment methods, and applying credits from purchase credit notes. Finance teams can use it to track payment details including method, processor, references, and notes, while developers can integrate it into dashboards or accounting systems to enable reconciliation, reporting, and audit workflows. Custom attributes provide extensibility for storing business-specific metadata such as seasonal tags or operational notes.
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
{
"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
On success, the API returns a purchase_payment object containing all details of the newly created payment. High-level attributes include payment status, ID, payment date, total applied amount, and any linked purchase order. Nested structures provide granular details:
- purchase_payment_applied: lists the distribution of amounts across payment methods, processors, and references.
- purchase_credit_applied: shows credits applied from purchase credit notes, if any.
- purchase_invoices: details invoice-level data such as applied amounts, totals, outstanding balances, issue dates, and due dates.
Additional metadata includes creator details, timestamps, UUID, versioning, and any custom attributes or objects. This structure ensures full traceability of how the payment was recorded, applied to invoices, and linked across supplier records, supporting accurate reconciliation and financial reporting.
Response Body
{
"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. |
| id | integer | System-generated identifier of the applied payment record. |
| amount | decimal | Amount applied using this method. |
| method | string | Method of payment (example: Cash, Bank, Cheque). |
| processor | string | Processor or channel through which payment was made. |
| 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. |
| applied | decimal | Amount applied to the given invoice. |
| id | string | Unique identifier of the purchase invoice. |
| due_date | string (date-time) | Due date of the invoice. |
| issue_date | string (date-time) | Issue date of the invoice. |
| outstanding | decimal | Outstanding balance remaining on the invoice after payment. |
| 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. |
| name | string | Name of the custom attribute. |
| value | string | Value of the custom attribute. |
| custom_objects | array | List of custom objects linked to this payment (empty if none). |