Payment POST API Documentation

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).

                JSON
              

                      {
    "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
date	String	The payment date in YYYY-MM-DD format.
note	String	Optional note related to the 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.

Response Body

                JSON
              

                      {
    "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.

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

                JSON
              

                      {
    "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.

Purpose

This endpoint create a payment that can be applied across one or multiple invoices. It allows combining different payment methods, credits, and optional gift certificates into a single payment transaction. This helps streamline financial reconciliation by recording mixed payments against multiple outstanding invoices.

Use Case

The endpoint is used when a customer or user wants to settle multiple invoices using various payment methods for example, partial bank deposit, partial cheque, and applying credits all in one transaction. Businesses use this endpoint in payment portals, accounting systems, and invoice management modules to record mixed payments and reduce outstanding balances on multiple invoices at once.

Path Parameters

No path parameters required for this endpoint.

Query Parameters

This endpoint does not have any query parameters.

Request Body

The request body requires a payment object containing the list of invoices to apply payments to, the date of the payment, payment methods used, credits applied, and optional gift certificates . Each invoice entry defines how much of the payment will be applied. Each payment method also includes a specific amount and optional reference number.

                JSON
              

                      {
  "payment": {
    "id": "PAYMENT_ID",
    "invoices": [
      {
        "id": "INVOICE_ID",
        "amount": "INVOICE_AMOUNT"
      }
    ],
    "date": "PAYMENT_DATE",
    "payment_applied": [
      {
        "method": "PAYMENT_METHOD",
        "processor": "PAYMENT_PROCESSOR",
        "amount": "PAYMENT_AMOUNT",
        "reference": "PAYMENT_REFERENCE"
      },
      {
        "method": "PAYMENT_METHOD",
        "processor": "PAYMENT_PROCESSOR",
        "amount": "PAYMENT_AMOUNT",
        "reference": "PAYMENT_REFERENCE"
      }
    ],
    "note": "PAYMENT_NOTE",
    "credit_applied": [
      {
        "id": "CREDIT_NOTE_ID",
        "amount": "CREDIT_AMOUNT"
      }
    ],
    "gift_certificates": [
      {
        "code": "GIFT_CERTIFICATE_CODE",
        "applied": "GIFT_CERTIFICATE_AMOUNT"
      }
    ],
    "custom_attributes": [
      {
        "name": "ATTRIBUTE_NAME",
        "value": "ATTRIBUTE_VALUE"
      }
    ]
  }
}

                    

Attribute	Type	Description
payment	object	Root object containing full payment details.
invoices	array	List of invoices and the specific amount to apply to each invoice.
id	string	Invoice ID (e.g., INV-XXXX).
amount	string	Payment amount applied to this invoice.
date	string (YYYY-MM-DD)	Date on which payment is recorded.
payment_applied	array	List of applied payment methods.
method	string	Name of payment method (e.g., Bank Deposit, Cheque).
processor	string	Processor associated with the method (e.g., Bank Deposit, Stripe).
amount	number	Amount applied from this payment method.
reference	string	Optional reference number or transaction ID.
credit_applied	array	List of credits applied towards payment.
id	string	Credit note ID.
amount	string	Amount applied from the credit.
gift_certificates	array	List of gift certificates applied (optional).
custom_attributes	array	Optional custom metadata fields.

                JSON
              

                      {
  "payment": {
    "status": "PAYMENT_STATUS",
    "id": "PAYMENT_ID",
    "date": "PAYMENT_DATE",
    "origin": "PAYMENT_ORIGIN",
    "reconcile_status": "RECONCILE_STATUS",
    "total_applied": "TOTAL_APPLIED",
    "payment_applied": [
      {
        "id": "PAYMENT_APPLIED_ID",
        "method": "PAYMENT_METHOD",
        "processor": "PAYMENT_PROCESSOR",
        "amount": "PAYMENT_AMOUNT",
        "reference": "PAYMENT_REFERENCE",
        "gateway_response": "GATEWAY_RESPONSE"
      },
      {
        "id": "PAYMENT_APPLIED_ID",
        "method": "PAYMENT_METHOD",
        "processor": "PAYMENT_PROCESSOR",
        "amount": "PAYMENT_AMOUNT",
        "reference": "PAYMENT_REFERENCE",
        "gateway_response": "GATEWAY_RESPONSE"
      }
    ],
    "credit_applied": [
      {
        "amount": "CREDIT_AMOUNT",
        "code": "CREDIT_CODE"
      }
    ],
    "gift_certificate_applied": "GIFT_CERTIFICATES",
    "invoices": [
      {
        "id": "INVOICE_ID",
        "issue_date": "INVOICE_ISSUE_DATE",
        "due_date": "INVOICE_DUE_DATE",
        "total": "INVOICE_TOTAL",
        "applied": "INVOICE_APPLIED",
        "outstanding": "INVOICE_OUTSTANDING"
      }
    ],
    "created_by": "CREATED_BY",
    "created_on": "CREATED_TIMESTAMP",
    "last_updated_by": "LAST_UPDATED_BY",
    "last_updated_on": "LAST_UPDATED_TIMESTAMP",
    "uuid": "PAYMENT_UUID",
    "payment_note": "PAYMENT_NOTE",
    "version": "PAYMENT_VERSION",
    "custom_attributes": "CUSTOM_ATTRIBUTES",
    "custom_objects": "CUSTOM_OBJECTS",
    "sale_order_id": "SALE_ORDER_ID"
  }
}

                    

Attribute	Type	Description
status	string	Status of the payment (e.g., ACTIVE).
id	string	Unique payment ID generated by the system.
date	datetime	Payment date stored in UTC.
origin	string	Payment origin (empty if none).
reconcile_status	string	Reconciliation state of the payment.
total_applied	string	Total amount applied across all invoices.
payment_applied	array	List of applied payment methods.
id	number	Internal ID of the payment method entry.
method	string	Payment method name.
processor	string	Processor used.
amount	number	Amount applied via this method.
reference	string	Reference value.
credit_applied	array	List of applied credit notes.
amount	string	Amount applied via credit.
code	string	Credit note code.
gift_certificate_applied	array	List of applied gift certificates (empty if none).
invoices	array	Invoices affected by the payment.
id	string	Invoice ID.
issue_date	datetime	Issue date of the invoice.
due_date	datetime	Due date for the invoice.
total	string	Invoice total amount.
applied	string	Amount applied to this invoice.
outstanding	string	Remaining unpaid balance.
created_by	string	User who created the payment.
created_on	datetime	Timestamp of creation.
last_updated_by	string	Last user who updated the payment.
last_updated_on	string	Timestamp of last update.
uuid	string	Unique UUID of the payment.
payment_note	string	Optional note.
version	string	Version number.
custom_attributes	array	Custom fields.
custom_objects	array	Additional custom objects.
sale_order_id	string	Associated sale order ID if exists.

Create Payment for a Single Invoice : /invoices/{invoice_id}/payments

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Create Payment Note: /payments/{payment_id}/notes

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response

Response Body

Create Payment for Multiple Invoices : /payments

Purpose

Use Case

Path Parameters

Query Parameters

Request Body

Response