Create Payment for a Single Invoice : /invoices/{invoice_id}/payments
Purpose
This API create and apply a new payment against a specific invoice using one or more processors (Cash, Cheque, Bank Deposit, or Gateway). It ensures that payment entries are properly recorded and associated with the corresponding invoice.
Use Case
The endpoint is used when a user wants to apply a payment (partial or full) to a specific invoice using one or more payment processors, this API allows them to submit the payment details including amount, processor type, and reference. This is particularly useful for real-time invoice settlement, reconciliations, and payment tracking in systems where multiple payment methods are accepted.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| invoice_id | String | Unique identifier of the invoice to pay for |
Query Parameters
This endpoint does not have any query parameters.
Request Body
The request body must include the payment date, an optional note, and a list of payment_applied entries. Each payment entry must specify the processor type (e.g., Cash, Cheque, Stripe), the amount to be applied, and a unique reference. Additional fields also can included depending on the processor (e.g., card details for Stripe).
{
"payment": {
"date": "TIMESTAMP",
"note": "STRING_VALUE",
"payment_applied": [
{
"processor": "PAYMENT_PROCESSOR",
"amount": "NUMBER",
"reference": "PAYMENT_REFERENCE"
},
{
"processor": "PAYMENT_PROCESSOR",
"amount": "NUMBER",
"reference": "PAYMENT_REFERENCE"
},
{
"processor": "PAYMENT_PROCESSOR",
"amount": "NUMBER",
"reference": "PAYMENT_REFERENCE"
}
]
}
}| Attribute | Type | Description |
|---|---|---|
| payment.date | String | The payment date in YYYY-MM-DD format. |
| payment.note | String | Optional note related to the payment. |
| payment.payment_applied | Array | List of payment entries. Each item contains processor details. |
| processor | String | Payment processor (e.g., Cash, Cheque, Bank Deposit, Stripe, etc.). |
| amount | String | Amount to apply from the specified processor. |
| reference | String | Unique payment reference (e.g., receipt number, transaction ID). |
| card_type | String | (Optional, for Stripe) Type of card (e.g., Visa, MasterCard). |
| token | String | (Optional, for Stripe) Encrypted payment token. |
| card_number | String | (Optional, for Stripe) Masked card number. |
| expiry_month | String | (Optional, for Stripe) Card expiry month. |
| expiry_year | String | (Optional, for Stripe) Card expiry year. |
| method | String | (Optional, for secure processors) Full payment method string. |
Response
The API endpoint response returns a full summary of the created payment applied to the specified invoice. It includes the payment ID, date, processor details, reconciliation status, total amount applied, and the invoice breakdown. It also provides metadata such as creation timestamps, user, and related sale order ID.
{
"payment": {
"status": "STATUS",
"id": "PAYMENT_ID",
"date": "TIMESTAMP",
"origin": "EMPTY",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "NUMBER",
"payment_applied": [
{
"amount": NUMBER,
"gateway_response": "NULL",
"id": NUMBER,
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "PAYMENT_REFERENCE"
},
{
"amount": NUMBER,
"gateway_response": "NULL",
"id": NUMBER,
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "PAYMENT_REFERENCE"
},
{
"amount": NUMBER,
"gateway_response": "NULL",
"id": NUMBER,
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "PAYMENT_REFERENCE"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "NUMBER",
"due_date": "TIMESTAMP",
"id": "INVOICE_ID",
"issue_date": "TIMESTAMP",
"outstanding": "NUMBER",
"total": "NUMBER"
}
],
"created_by": "CREATED_BY",
"created_on": "TIMESTAMP",
"last_updated_by": "EMPTY",
"last_updated_on": "EMPTY",
"uuid": "UUID",
"payment_note": "EMPTY",
"version": "VERSION",
"custom_attributes": [],
"custom_objects": [],
"sale_order_id": "ORDER_ID"
}
}| Attribute | Type | Description |
|---|---|---|
| status | String | Status of the payment (e.g., ACTIVE). |
| id | String | Unique payment ID generated. |
| date | String | Timestamp when the payment was recorded. |
| reconcile_status | String | Indicates if the payment has been reconciled. |
| total_applied | String | Total amount applied through the payment. |
| payment_applied | Array | List of payment methods and their attributes. |
| amount | Float | Amount applied from this processor. |
| processor | String | Processor type used (e.g., Cash, Cheque). |
| reference | String | Reference associated with this payment. |
| method | String | Unique processor method used (e.g., Cheque_TADQYD). |
| invoices | Array | Invoices this payment was applied to. |
| id | String | Invoice ID. |
| applied | String | Amount applied to this invoice. |
| total | String | Total amount of the invoice. |
| outstanding | String | Remaining balance after applying this payment. |
| issue_date | String | Invoice issue date. |
| due_date | String | Invoice due date. |
| created_by | String | User who recorded the payment. |
| created_on | String | Timestamp when the payment was created. |
| sale_order_id | String | Associated sale order ID. |
| uuid | String | UUID of the payment entry. |
| version | String | Version of the payment record. |
Create Payment Note: /payments/{payment_id}/notes
Purpose
This API allows clients to add a new note to a payment. The note can include descriptive text and optional file attachments.
Use Case
- Record internal remarks, clarifications, or instructions against a payment.
- Attach supporting documents (e.g., remittance advice, screenshots, or scanned receipts).
- Maintain an audit trail of comments related to payment transactions.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| payment_id | string | Yes | Unique identifier of the payment to which the note should be added. |
Query Parameters
This endpoint does not support query parameters.
Request Body
The request body must be sent as multipart/form-data because it includes both text and file fields.
| Attribute | Type | Description |
|---|---|---|
| note | string | Content of the note. |
| file | file | File to attach with the note. Accepts common document and image formats. |
Response
On success, the API returns a payment object containing a notes object with the unique identifier (uuid) of the newly created note. This UUID can be used in subsequent API calls to retrieve, update, or manage the note.
Response Body
{
"payment": {
"notes": {
"uuid": "{{NOTE_UUID}}"
}
}
}
| Attribute | Type | Description |
|---|---|---|
| payment | object | Container holding payment details. |
| payment.notes | object | Container holding the newly created note details. |
| payment.notes.uuid | string (UUID) | Unique identifier of the newly created note. |