Endpoint: POST /api/v3/invoices/{invoice_id}/payments
Purpose
Apply payments to a specific invoice, including basic offline payments, direct credit, and direct debit transactions.
Use Case
This endpoint is used to record payments against an invoice, supporting offline cash transactions, direct credit payment gateways, and direct debit options.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| invoice_id | String | Unique identifier of the invoice. |
Request
The request supports three payment types for an invoice: basic offline, direct credit, and direct debit. Basic payments require a date, processor (e.g., "Cash"), amount, and reference. Direct credit includes additional card details like type, token, and expiry. Direct debit requires the processor, card type, amount, and reference for streamlined payment processing.
Offline Payment
{
"payment": {
"date": "DATE",
"payment_applied": [
{
"processor": "OFFLINE_PROCESSOR",
"amount": "AMOUNT",
"reference": "REFERENCE"
}
]
}
}
Direct Credit Payment
{
"payment": {
"date": "DATE",
"payment_applied": [
{
"processor": "DIRECT_CREDIT_PROCESSOR",
"amount": "AMOUNT",
"card_type": "CARD_TYPE",
"token": "TOKEN",
"card_number": "CARD_NUMBER",
"expiry_month": "EXPIRY_MONTH",
"expiry_year": "EXPIRY_YEAR",
"reference": "REFERENCE"
}
]
}
}
Direct Debit Payment
{
"payment": {
"date": "DATE",
"payment_applied": [
{
"processor": "DIRECT_DEBIT_PROCESSOR",
"amount": "AMOUNT",
"card_type": "CARD_TYPE",
"reference": "REFERENCE"
}
]
}
}
Response
A successful response confirms that the payment has been applied to the specified invoice, including details about the payment processor, amount applied, reference used, and transaction date. Also, the response includes the total amount applied to the invoice, making sure that the updated payment status is clear. This allows users to verify that the payment has been processed successfully and that it is reflected accurately on the invoice.
Offlilne Payment
{
"payment": {
"status": "STATUS",
"id": "ID",
"date": "DATE",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "TOTAL_APPLIED",
"payment_applied": [
{
"amount": AMOUNT,
"method": "METHOD",
"processor": "OFFLINE_PROCESSOR",
"reference": "REFERENCE"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "APPLIED_AMOUNT",
"code": "INVOICE_CODE",
"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": [
{
"name": "CUSTOM_ATTRIBUTE_NAME",
"value": "CUSTOM_ATTRIBUTE_VALUE"
}
],
"custom_objects": []
}
}
Direct Credit
{
"payment": {
"status": "STATUS",
"id": "ID",
"date": "DATE",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "TOTAL_APPLIED",
"payment_applied": [
{
"amount": AMOUNT,
"method": "METHOD",
"processor": "DIRECT_CREDIT_PROCESSOR",
"reference": "REFERENCE"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "APPLIED_AMOUNT",
"code": "INVOICE_CODE",
"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": [
{
"name": "CUSTOM_ATTRIBUTE_NAME",
"value": "CUSTOM_ATTRIBUTE_VALUE"
}
],
"custom_objects": []
}
}
Direct Debit
{
"payment": {
"status": "STATUS",
"id": "ID",
"date": "DATE",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "TOTAL_APPLIED",
"payment_applied": [
{
"amount": AMOUNT,
"method": "METHOD",
"processor": "DIRECT_DEBIT_PROCESSOR",
"reference": "REFERENCE"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "APPLIED_AMOUNT",
"code": "INVOICE_CODE",
"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": [
{
"name": "CUSTOM_ATTRIBUTE_NAME",
"value": "CUSTOM_ATTRIBUTE_VALUE"
}
],
"custom_objects": []
}
}
Endpoint: POST /api/v3/payments
Purpose
This endpoint enables users to create and apply payments to multiple invoices, using various payment methods, credits, and gift certificates, ensuring accurate tracking of transactions and balances.
Use Case
A merchant processes payments from a customer using a combination of cash, credit cards, and gift certificates, distributing the payments across multiple invoices to settle outstanding balances.
Path Parameters
None.
Request Body
The request must include details about the payment, such as associated invoices, payment methods, credits, and gift certificates.
{
"payment": {
"id": "PMT-PLACEHOLDER",
"invoices": [
{
"id": "INV-PLACEHOLDER-1",
"amount": "AMOUNT_PLACEHOLDER"
},
{
"id": "INV-PLACEHOLDER-2",
"amount": "AMOUNT_PLACEHOLDER"
}
],
"date": "YYYY-MM-DD",
"payment_applied": [
{
"processor": "PROCESSOR_PLACEHOLDER_1",
"amount": "AMOUNT_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER_1"
},
{
"processor": "PROCESSOR_PLACEHOLDER_2",
"amount": "AMOUNT_PLACEHOLDER",
"reference": "REFERENCE_PLACEHOLDER_2"
}
],
"note": "NOTE_PLACEHOLDER",
"credit_applied": [
{
"id": "CRN-PLACEHOLDER-1",
"amount": "AMOUNT_PLACEHOLDER"
}
],
"gift_certificates": [
{
"code": "GC-PLACEHOLDER-1",
"applied": "AMOUNT_PLACEHOLDER"
},
{
"code": "GC-PLACEHOLDER-2",
"applied": "AMOUNT_PLACEHOLDER"
}
],
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME_PLACEHOLDER",
"value": "ATTRIBUTE_VALUE_PLACEHOLDER"
}
]
}
}
Response
The response provides a breakdown of the payment details, its status, reconciliation information, and how the payment was applied to invoices, credits, and gift certificates.
{
"payment": {
"status": "STATUS_PLACEHOLDER",
"id": "PMT-PLACEHOLDER",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"reconcile_status": "RECONCILE_STATUS_PLACEHOLDER",
"total_applied": "AMOUNT_PLACEHOLDER",
"payment_applied": [
{
"amount": "AMOUNT_PLACEHOLDER",
"method": "METHOD_PLACEHOLDER_1",
"processor": "PROCESSOR_PLACEHOLDER_1",
"reference": "REFERENCE_PLACEHOLDER_1"
},
{
"amount": "AMOUNT_PLACEHOLDER",
"method": "METHOD_PLACEHOLDER_2",
"processor": "PROCESSOR_PLACEHOLDER_2",
"reference": "REFERENCE_PLACEHOLDER_2"
},
{
"amount": "AMOUNT_PLACEHOLDER",
"method": "METHOD_PLACEHOLDER_3",
"processor": "PROCESSOR_PLACEHOLDER_3",
"reference": "REFERENCE_PLACEHOLDER_3"
},
{
"amount": "AMOUNT_PLACEHOLDER",
"method": "METHOD_PLACEHOLDER_4",
"processor": "PROCESSOR_PLACEHOLDER_4",
"reference": "REFERENCE_PLACEHOLDER_4"
}
],
"credit_applied": [],
"gift_certificate_applied": [
{
"amount": "AMOUNT_PLACEHOLDER",
"code": "GC-PLACEHOLDER_1"
},
{
"amount": "AMOUNT_PLACEHOLDER",
"code": "GC-PLACEHOLDER_2"
}
],
"invoices": [
{
"applied": "AMOUNT_PLACEHOLDER",
"code": "INV-PLACEHOLDER_1",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"outstanding": "AMOUNT_PLACEHOLDER",
"total": "AMOUNT_PLACEHOLDER"
},
{
"applied": "AMOUNT_PLACEHOLDER",
"code": "INV-PLACEHOLDER_2",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"outstanding": "AMOUNT_PLACEHOLDER",
"total": "AMOUNT_PLACEHOLDER"
}
],
"created_by": "CREATOR_PLACEHOLDER",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "UPDATER_PLACEHOLDER",
"last_updated_on": "YYYY-MM-DDTHH:MM:SSZ",
"uuid": "UUID-PLACEHOLDER",
"version": "VERSION_PLACEHOLDER",
"custom_attributes": [
{
"name": "ATTRIBUTE_NAME_PLACEHOLDER_1",
"value": "ATTRIBUTE_VALUE_PLACEHOLDER_1"
},
{
"name": "ATTRIBUTE_NAME_PLACEHOLDER_2",
"value": "ATTRIBUTE_VALUE_PLACEHOLDER_2"
}
],
"custom_objects": []
}
}