Retrieve Payment Records : /payments
Purpose
This endpoint fetch all payment records from the system. It provides comprehensive details including payment status, applied payments, linked invoices, payment methods, and metadata like creation date and user.
Use Case
The endpoint is used to retrieve all recorded payments in the system. In Exsited’s standard workflow, users first select an item, create an invoice for that item, and then process the payment using one of the supported payment methods. This endpoint allows businesses to track all these processed payments, including how the payments were applied, their reconciliation status, linked invoices, and audit information like who created or last updated the payment.
Path Parameters
No request body is required for this endpoint.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | Number | Limits the number of payment records returned per request. |
| offset | Number | Skips the specified number of records for pagination. |
Request Body
No request body is required for this endpoint.
Response
The API endpoint response returns a list of payment records along with their detailed attributes. Each record includes the payment ID, status, origin, reconciliation status, total applied amount, and related invoices. It also shows how the payment was applied via bank deposits, credits, or gift certificates. Additional metadata like creation timestamps, user information, and custom attributes are included. Pagination data is provided to navigate through multiple records.
{
"payments": [
{
"status": "PAYMENT_STATUS",
"id": "PAYMENT_ID",
"date": "TIMESTAMP",
"origin": "PAYMENT_ORIGIN",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "DECIMAL_VALUE",
"payment_applied": [
{
"amount": DECIMAL_VALUE,
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "EMPTY"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "DECIMAL_VALUE",
"due_date": "TIMESTAMP",
"id": "INVOICE_ID",
"issue_date": "TIMESTAMP",
"outstanding": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE"
}
],
"created_by": "CREATED_BY",
"created_on": "TIMESTAMP",
"last_updated_by": "EMPTY",
"last_updated_on": "EMPTY",
"uuid": "PAYMENT_UUID",
"payment_note": "EMPTY",
"version": "VERSION_NUMBER",
"custom_attributes": [],
"custom_objects": []
}
],
"pagination": {
"records": NUMBER,
"limit": NUMBER,
"offset": NUMBER,
"previous_page": "PAGINATION_URL",
"next_page": "PAGINATION_URL"
}
}| Attribute | Type | Description |
|---|---|---|
| status | String | Current status of the payment (e.g., ACTIVE). |
| id | String | Unique identifier of the payment. |
| date | DateTime | Date when the payment was made. |
| origin | String | Origin reference of the payment. |
| reconcile_status | String | Indicates if the payment is reconciled or not. |
| total_applied | String (decimal) | Total amount applied from the payment. |
| amount | Number | Amount applied via specific payment method. |
| .method | String | Method name used for payment. |
| processor | String | Processor type (e.g., Bank Deposit). |
| amount | String | Credit amount applied to the payment. |
| code | String | Credit code used. |
| amount | String | Amount applied using a gift certificate. |
| code | String | Gift certificate code used. |
| id | String | Invoice ID associated with the payment. |
| applied | String | Amount applied to the invoice. |
| due_date | DateTime | Due date of the invoice. |
| issue_date | DateTime | Issue date of the invoice. |
| total | String | Total amount of the invoice. |
| created_by | String | Name of the user who created the payment. |
| created_on | DateTime | Creation timestamp. |
| last_updated_by | String | Name of the user who last updated the record. |
| last_updated_on | DateTime | Last update timestamp. |
| uuid | String | UUID of the payment record. |
| payment_note | String | Optional note attached to the payment. |
| version | String | Version of the payment record. |
| custom_attributes[] | Array | List of custom attributes added to the payment. |
| pagination.records | Integer | Total number of records available. |
| pagination.limit | Integer | Number of records returned in the current response. |
| pagination.offset | Integer | Current offset in the list of results. |
| pagination.previous_page | String | Link to the previous page of results. |
| pagination.next_page | String | Link to the next page of results. |
Retrieve a Specific Payment Record : /payments/{payment_id}
Purpose
This endpoint retrieve the full details of a specific payment record based on its unique payment ID. It includes information such as payment status, date, applied amount, method, related invoices, and metadata like creator and timestamps.
Use Case
The endpoint is used to fetch the complete detail of a single payment transaction. This is typically used when a user wants to view or verify how a specific payment was applied including its amount, method, status, and which invoice it was linked to. It provides transparency into the payment lifecycle and helps with reconciliation or auditing processes within the Exsited platform.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| payment_id | String | Unique ID of the payment to fetch. |
Query Parameters
This endpoint does not have any query parameters.
Request Body
No request body is required for this endpoint.
Response
The API endpoint response returns detailed information about a single payment. It includes the payment ID, status, payment date, total amount applied, and how the payment was processed (method and processor). It also contains associated invoice details like invoice ID, due date, and outstanding balance. Metadata such as the user who created the payment and creation timestamps are also included, along with any custom attributes or objects if defined.
{
"payment": {
"status": "PAYMENT_STATUS",
"id": "PAYMENT_ID",
"date": "TIMESTAMP",
"origin": "EMPTY",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "DECIMAL_VALUE",
"payment_applied": [
{
"amount": DECIMAL_VALUE,
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "EMPTY"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "DECIMAL_VALUE",
"due_date": "TIMESTAMP",
"id": "INVOICE_ID",
"issue_date": "TIMESTAMP",
"outstanding": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE"
}
],
"created_by": "CREATED_BY",
"created_on": "TIMESTAMP",
"last_updated_by": "EMPTY",
"last_updated_on": "EMPTY",
"uuid": "PAYMENT_UUID",
"payment_note": "EMPTY",
"version": "VERSION_NUMBER",
"custom_attributes": [],
"custom_objects": []
}
}| Attribute | Type | Description |
|---|---|---|
| status | String | Current status of the payment (e.g., ACTIVE). |
| id | String | Unique payment ID. |
| date | DateTime | Date when the payment occurred. |
| origin | String | Source or origin of the payment, if any. |
| reconcile_status | String | Reconciliation status (e.g., NOT_RECONCILE). |
| total_applied | String | Total amount applied from the payment. |
| payment_applied[].amount | Number | Amount paid using a specific method. |
| method | String | Payment method (e.g., Cash_PX348X). |
| processor | String | Payment processor used (e.g., Cash). |
| reference | String | Reference information (if any). |
| credit_applied | Array | List of any applied credits. Empty if none. |
| gift_certificate_applied | Array | List of applied gift certificates. Empty if none. |
| id | String | Invoice ID linked to the payment. |
| applied | String | Amount applied to the invoice. |
| due_date | DateTime | Invoice due date. |
| issue_date | DateTime | Invoice issue date. |
| outstanding | String | Remaining amount to be paid. |
| total | String | Total amount of the invoice. |
| created_by | String | Name of the user who created the payment. |
| created_on | DateTime | Date and time the payment was created. |
| last_updated_by | String | Name of the last user who updated it (if any). |
| last_updated_on | DateTime | Last update timestamp (if any). |
| uuid | String | UUID of the payment. |
| payment_note | String | Optional notes associated with the payment. |
| version | String | Version number of the payment record. |
| custom_attributes | Array | List of custom attributes, if any. |
| custom_objects | Array | List of custom objects, if any. |
Retrieve All Payments from a Specific Account : /accounts/{account_id}/payments
Purpose
This API endpoint retrieves a list of all payments made from a specific account, including payment metadata, applied amounts, payment methods, associated invoices, and pagination details. It helps in tracking the full payment history for an account.
Use Case
The endpoint is used to retrieve all the payment records associated with a specific account. It is useful for finance teams, customer service, or admin panels to review customer transaction history, verify invoice payments, and monitor reconciliation status. This can be part of billing audits, customer queries, or financial reporting.
Path Parameters
| Name | Type | Description |
|---|---|---|
| account_id | String | Unique identifier of the account. |
Query Parameters
This endpoint does not have any query parameters.
Request Body
No request body is required for this endpoint.
Response
The API endpoint response contains an object that includes a list of payment records and pagination metadata. Each payment object includes information such as status, ID, date, reconciliation status, amount applied, the method and processor used, any linked invoices (with applied and outstanding values), and audit data like creation and update timestamps. This comprehensive structure ensures users have complete visibility into account-level payment activities.
{
"account": {
"payments": [
{
"status": "STATUS",
"id": "PAYMENT_ID",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"origin": "",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "DECIMAL_VALUE",
"payment_applied": [
{
"amount": "DECIMAL_VALUE",
"gateway_response": null,
"id": NUMBER,
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "REFERENCE_NUMBER"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "DECIMAL_VALUE",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"id": "INVOICE_ID",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"outstanding": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE"
}
],
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "",
"last_updated_on": "",
"uuid": "UUID",
"payment_note": "",
"version": "VERSION",
"custom_attributes": [],
"custom_objects": [],
"sale_order_id": "ORDER_ID"
}
],
"pagination": {
"records": "NUMBER",
"limit": "NUMBER",
"offset": "NUMBER",
"previous_page": "PAGINATION_URL",
"next_page": "PAGINATION_URL"
}
}
}| Attribute | Type | Description |
|---|---|---|
| status | String | Status of the payment (e.g., ACTIVE). |
| id | String | Unique identifier for the payment. |
| date | String | Date when the payment was made. |
| origin | String | Origin of the payment (if applicable). |
| reconcile_status | String | Reconciliation status (e.g., NOT_RECONCILE). |
| total_applied | String | Total amount applied in the payment. |
| payment_applied[] | Array | List of payment methods used in this transaction. |
| amount | Number | Amount applied via the payment method. |
| method | String | Payment method (credit card info). |
| processor | String | Payment processor name. |
| reference | String | Payment reference, often linked to an invoice. |
| invoices[] | Array | Invoices the payment was applied to. |
| id | String | Invoice ID. |
| applied | String | Amount applied to the invoice. |
| outstanding | String | Remaining balance on the invoice. |
| total | String | Total invoice amount. |
| created_by | String | User who created the payment. |
| created_on | String (ISO 8601) | Timestamp when the payment was created. |
| last_updated_by | String | User who last updated the payment. |
| last_updated_on | String | Last update timestamp. |
| uuid | String | UUID of the payment. |
| payment_note | String | Optional note related to the payment. |
| version | String | Version number of the payment record. |
| sale_order_id | String | Linked sale order ID. |
| records | Integer | Total number of payment records. |
| limit | Integer | Number of records per page. |
| offset | Integer | Current page offset. |
| previous_page | String | URL to fetch the previous page. |
| next_page | String | URL to fetch the next page. |
Retrieve Payment Details for an Order : /orders/{order_id}/payments
Purpose
This API retrieves all payment records associated with a specific order. It includes comprehensive details such as payment amounts, methods, processors, references, and invoice information, enabling accurate tracking and reconciliation of payments made toward the order.
Use Case
The API is used when a user need to retrieve the payment history of a particular order. For instance, a finance officer might call this endpoint to verify all payment transactions made against an order for auditing or customer support purposes.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| order_id | String | Unique identifier of the order. |
Query Parameters
This endpoint does not have any query parameters.
Request Body
No request body is required for this endpoint.
Response
The API endpoint response contains a list of payments made for the specified order. Each payment includes metadata such as status, payment ID, date, reconcile status, amount applied, method used, processor details, references, and the corresponding invoices. The response also includes pagination details to support large datasets and ensure efficient retrieval of data.
{
"order": {
"payments": [
{
"status": "STATUS",
"id": "PAYMENT_ID_1",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"origin": "",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "DECIMAL_VALUE",
"payment_applied": [
{
"amount": "DECIMAL_VALUE",
"gateway_response": null,
"id": "NUMBER",
"method": "PAYMENT_METHOD_1",
"processor": "PAYMENT_PROCESSOR_1",
"reference": "REFERENCE_NUMBER_1"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "DECIMAL_VALUE",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"id": "INVOICE_ID_1",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"outstanding": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE"
}
],
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "",
"last_updated_on": "",
"uuid": "UUID_1",
"payment_note": "",
"version": "VERSION",
"custom_attributes": [],
"custom_objects": [],
"sale_order_id": "ORDER_ID"
},
{
"status": "STATUS",
"id": "PAYMENT_ID_2",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"origin": "",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "DECIMAL_VALUE",
"payment_applied": [
{
"amount": "DECIMAL_VALUE",
"gateway_response": null,
"id": "NUMBER",
"method": "PAYMENT_METHOD_2",
"processor": "PAYMENT_PROCESSOR_2",
"reference": "REFERENCE_NUMBER_2"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "DECIMAL_VALUE",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"id": "INVOICE_ID_1",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"outstanding": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE"
}
],
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "",
"last_updated_on": "",
"uuid": "UUID_2",
"payment_note": "",
"version": "VERSION",
"custom_attributes": [],
"custom_objects": [],
"sale_order_id": "ORDER_ID"
}
],
"pagination": {
"records": "NUMBER",
"limit": "NUMBER",
"offset": "NUMBER",
"previous_page": "PAGINATION_URL",
"next_page": "PAGINATION_URL"
}
}
}| Attribute | Type | Description |
|---|---|---|
| payments | Array | A list of payment objects for the specified order. |
| status | String | Current status of the payment (ACTIVE). |
| id | String | Unique identifier for the payment. |
| date | String | Date the payment was made (ISO format). |
| reconcile_status | String | Indicates whether the payment has been reconciled. |
| total_applied | String | Total amount applied from the payment. |
| payment_applied | Array | List of details about how the payment was applied (method, amount, etc.). |
| invoices | Array | List of invoices associated with the payment, including totals and dates. |
| created_by | String | Name of the user who created the payment record. |
| created_on | String | Timestamp when the payment was created. |
| uuid | String | Universally unique identifier for the payment. |
| version | String | Version number of the payment record. |
| sale_order_id | String | Identifier of the associated sale order. |
| records | Integer | Total number of payment records. |
| limit | Integer | Maximum number of records returned per page. |
| offset | Integer | Offset index for paginated data. |
| previous_page | String | URL to fetch the previous page of results. |
| next_page | String | URL to fetch the next page of results. |
Retrieve Invoice Payments : /invoices/{invoice_id}/payments
Purpose
This endpoint retrieves all payment records associated with a specific invoice, including applied amounts, payment methods, processor details, and invoice reconciliation status.
Use Case
The endpoint is used to fetch a list of payments applied to a specific invoice. It helps finance or billing systems track how and when payments were made, by whom, and via which processors. It also supports auditing and reconciliation by showing how much was applied to the invoice and the remaining outstanding amount.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| invoice_id | String | Unique identifier of the invoice |
Query Parameters
This endpoint does not have any query parameters.
Request Body
No request body is required for this endpoint.
Response
The API response returns a detailed list of payment records associated with the invoice. Each payment includes the amount, payment method, processor, reference ID, creation info, and any custom metadata. It also includes pagination information to navigate through multiple payment records if they exist.
{
"invoice": {
"payments": [
{
"status": "STATUS",
"id": "PAYMENT_ID",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"origin": "EMPTY",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "DECIMAL_VALUE",
"payment_applied": [
{
"amount": "DECIMAL_VALUE",
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "EMPTY"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "DECIMAL_VALUE",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"id": "INVOICE_ID",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"outstanding": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE"
}
],
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "EMPTY",
"last_updated_on": "EMPTY",
"uuid": "UUID",
"payment_note": "EMPTY",
"version": "VERSION",
"custom_attributes": [],
"custom_objects": []
},
{
"status": "STATUS",
"id": "PAYMENT_ID",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"origin": "EMPTY",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "DECIMAL_VALUE",
"payment_applied": [
{
"amount": "DECIMAL_VALUE",
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "REFERENCE_NUMBER"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "DECIMAL_VALUE",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"id": "INVOICE_ID",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"outstanding": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE"
}
],
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "EMPTY",
"last_updated_on": "EMPTY",
"uuid": "UUID",
"payment_note": "EMPTY",
"version": "VERSION",
"custom_attributes": [],
"custom_objects": []
},
{
"status": "STATUS",
"id": "PAYMENT_ID",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"origin": "EMPTY",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "DECIMAL_VALUE",
"payment_applied": [
{
"amount": DECIMAL_VALUE,
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "REFERENCE_NUMBER"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "DECIMAL_VALUE",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"id": "INVOICE_ID",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"outstanding": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE"
}
],
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "EMPTY",
"last_updated_on": "EMPTY",
"uuid": "UUID",
"payment_note": "EMPTY",
"version": "VERSION",
"custom_attributes": [],
"custom_objects": []
},
{
"status": "STATUS",
"id": "PAYMENT_ID",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"origin": "EMPTY",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "DECIMAL_VALUE",
"payment_applied": [
{
"amount": DECIMAL_VALUE,
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "REFERENCE_NUMBER"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "DECIMAL_VALUE",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"id": "INVOICE_ID",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"outstanding": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE"
}
],
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "EMPTY",
"last_updated_on": "EMPTY",
"uuid": "UUID",
"payment_note": "EMPTY",
"version": "VERSION",
"custom_attributes": [],
"custom_objects": []
},
{
"status": "STATUS",
"id": "PAYMENT_ID",
"date": "YYYY-MM-DDTHH:MM:SSZ",
"origin": "EMPTY",
"reconcile_status": "RECONCILE_STATUS",
"total_applied": "DECIMAL_VALUE",
"payment_applied": [
{
"amount": "DECIMAL_VALUE",
"method": "PAYMENT_METHOD",
"processor": "PAYMENT_PROCESSOR",
"reference": "REFERENCE_NUMBER"
}
],
"credit_applied": [],
"gift_certificate_applied": [],
"invoices": [
{
"applied": "DECIMAL_VALUE",
"due_date": "YYYY-MM-DDTHH:MM:SSZ",
"id": "INVOICE_ID",
"issue_date": "YYYY-MM-DDTHH:MM:SSZ",
"outstanding": "DECIMAL_VALUE",
"total": "DECIMAL_VALUE"
}
],
"created_by": "CREATED_BY",
"created_on": "YYYY-MM-DDTHH:MM:SSZ",
"last_updated_by": "EMPTY",
"last_updated_on": "EMPTY",
"uuid": "UUID",
"payment_note": "EMPTY",
"version": "VERSION",
"custom_attributes": [],
"custom_objects": []
}
],
"pagination": {
"records": NUMBER,
"limit": NUMBER,
"offset": NUMBER,
"previous_page": "EMPTY",
"next_page": "NULL"
}
}
}| Attribute | Type | Description |
|---|---|---|
| payments | Array | List of payment records applied to the invoice |
| status | String | Status of the payment (e.g., ACTIVE) |
| id | String | Unique identifier for the payment |
| date | String | Date the payment was made |
| total_applied | String | Total amount applied from the payment |
| payment_applied | Array | List of payment methods used with amount and reference |
| invoices | Array | List of invoices to which the payment was applied |
| created_by | String | Name of the user who created the payment |
| created_on | String | Timestamp when the payment was created |
| uuid | String | Unique identifier of the payment record |
| pagination | Object | Pagination information for the payments list |
| records | Integer | Total number of payment records |
| limit | Integer | Number of records returned per page |
| offset | Integer | Pagination offset |
| previous_page | String | URL or identifier for the previous page |
| next_page | String | URL or identifier for the next page |
Retrieve Notes for a Payment: /payments/{payment_id}/notes
Purpose
This endpoint retrieves all notes associated with a specific payment. Notes can include descriptive text, audit information (such as who created or updated them), optional attached files, and any custom attributes defined by the client.
Use Case
- Retrieve all notes linked to a payment for review or auditing.
- Display payment-related notes in a UI, including metadata and optional file attachments.
- Provide supporting details for financial or reconciliation processes.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| payment_id | string | Yes | Unique identifier of the payment. |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | int | No | Number of records to return per page (default: 20). |
| offset | int | No | Number of records to skip for pagination. |
Request Body
No data is required for the request body.
Response
On success, the API returns a payment object containing a list of notes. Each note includes a UUID, version number, content (HTML-supported), attached files, creator details, timestamps, and optional custom attributes. A pagination object is also included to manage large result sets.
Response Body
{
"payment": {
"notes": [
{
"uuid": "{{NOTE_UUID}}",
"version": "1",
"content": "{{note_content}}",
"files": [],
"created_by": "{{created_by_user}}",
"created_on": "{{created_timestamp}}",
"last_updated_by": "{{last_updated_by_user}}",
"last_updated_on": "{{last_updated_timestamp}}",
"custom_attributes": []
}
],
"pagination": {
"records": 1,
"limit": 20,
"offset": 0,
"previous_page": "",
"next_page": "NULL"
}
}
}
| Attribute | Type | Description |
|---|---|---|
| payment | object | Container object holding payment data. |
| payment.notes | array | List of notes associated with the payment. |
| payment.notes[].uuid | string | Unique identifier of the note (UUID). |
| payment.notes[].version | string | Version number of the note (used for concurrency control). |
| payment.notes[].content | string | Content of the note (supports HTML). |
| payment.notes[].files | array | List of files attached to the note (if any). |
| payment.notes[].created_by | string | User who created the note. |
| payment.notes[].created_on | string | Timestamp when the note was created (ISO 8601). |
| payment.notes[].last_updated_by | string | User who last updated the note. |
| payment.notes[].last_updated_on | string | Timestamp when the note was last updated (ISO 8601). |
| payment.notes[].custom_attributes | array | Custom attributes defined for the note. |
| payment.pagination | object | Pagination metadata for the notes list. |
| payment.pagination.records | integer | Total number of records available. |
| payment.pagination.limit | integer | Maximum number of records returned per page. |
| payment.pagination.offset | integer | Number of records skipped. |
| payment.pagination.previous_page | string | URL of the previous page (if available). |
| payment.pagination.next_page | string | URL of the next page (if available). |
Retrieve a Specific Note for a Payment: /payments/{payment_id}/notes/{NOTE_UUID}
Purpose
This endpoint retrieves the details of a specific note attached to a payment. Notes contain descriptive content, audit metadata, optional file attachments, and client-defined custom attributes.
Use Case
- Fetch detailed information for a single payment note.
- Display note content, files, and metadata in financial records or audit logs.
- Enable reconciliation workflows where each note provides supporting evidence.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| payment_id | string | Yes | Unique identifier of the payment. |
| NOTE_UUID | string | Yes | Unique identifier (UUID) of the note. |
Query Parameters
This endpoint does not support query parameters.
Request Body
No data is required for the request body.
Response
On success, the API returns a payment object containing a single note. The note includes its unique identifier, version, textual content (HTML or plain text), a list of attached files (if any), audit details such as creator and timestamps, and optional custom attributes for extended metadata.
Response Body
{
"payment": {
"note": {
"uuid": "{{NOTE_UUID}}",
"version": "1",
"content": "{{note_content}}",
"files": [],
"created_by": "{{created_by_user}}",
"created_on": "{{created_timestamp}}",
"last_updated_by": "{{last_updated_by_user}}",
"last_updated_on": "{{last_updated_timestamp}}",
"custom_attributes": []
}
}
}
| Attribute | Type | Description |
|---|---|---|
| payment | object | Container object holding payment data. |
| payment.note | object | The note associated with the payment. |
| payment.note.uuid | string | Unique identifier (UUID) of the note. |
| payment.note.version | string | Version number of the note (used for concurrency control). |
| payment.note.content | string | Content of the note (supports HTML). |
| payment.note.files | array | Files attached to the note (if any). |
| payment.note.created_by | string | User who created the note. |
| payment.note.created_on | string | Timestamp when the note was created (ISO 8601). |
| payment.note.last_updated_by | string | User who last updated the note. |
| payment.note.last_updated_on | string | Timestamp when the note was last updated (ISO 8601). |
| payment.note.custom_attributes | array | Custom attributes defined for the note. |
Retrieve Files for a Payment Note: /payments/{payment_id}/notes/{NOTE_UUID}/files
Purpose
This endpoint retrieves all files attached to a specific note within a payment. Files can include receipts, supporting documents, or images that provide additional context for the note.
Use Case
- Retrieve supporting documents uploaded with a payment note.
- Enable audit and compliance workflows by linking payment notes with evidence files.
- Display attached files in user interfaces for financial review or verification.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| payment_id | string | Yes | Unique identifier of the payment. |
| NOTE_UUID | string | Yes | Unique identifier (UUID) of the note. |
Query Parameters
This endpoint does not support query parameters.
Request Body
No data is required for the request body.
Response
On success, the API returns a payment object containing the note with its associated files. Each file includes a unique identifier (UUID), file name, and version number. Custom attributes are also available for extending metadata at the note level.
Response Body
{
"payment": {
"note": {
"files": [
{
"uuid": "{{FILE_UUID}}",
"name": "{{file_name}}",
"version": "1"
}
],
"custom_attributes": []
}
}
}
| Attribute | Type | Description |
|---|---|---|
| payment | object | Container object holding payment data. |
| payment.note | object | The note associated with the payment. |
| payment.note.files | array | List of files attached to the note. |
| payment.note.files[].uuid | string | Unique identifier (UUID) of the file. |
| payment.note.files[].name | string | Name of the uploaded file. |
| payment.note.files[].version | string | Version number of the file. |
| payment.note.custom_attributes | array | Custom attributes defined for the note. |
Retrieve a Specific File from a Payment Note: /payments/{payment_id}/notes/{NOTE_UUID}/files/{FILE_UUID}
Purpose
This endpoint retrieves details of a specific file attached to a payment note. It provides metadata such as the file’s UUID, name, and version. This allows systems to locate, display, or manage individual files linked to payment notes.
Use Case
- Retrieve supporting documents uploaded with a payment note.
- Enable audit and compliance workflows by linking payment notes with evidence files.
- Display attached files in user interfaces for financial review or verification.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| payment_id | string | Yes | Unique identifier of the payment. |
| NOTE_UUID | string | Yes | Unique identifier (UUID) of the note. |
| FILE_UUID | string | Yes | Unique identifier (UUID) of the file. |
Query Parameters
This endpoint does not support query parameters.
Request Body
No data is required for the request body.
Response
On success, the API returns a payment object containing the note with its file object. The file object includes its unique UUID, name, and version number. Additionally, custom attributes may be included for extending metadata about the note.
Response Body
{
"payment": {
"note": {
"file": {
"uuid": "{{FILE_UUID}}",
"name": "{{file_name}}",
"version": "1"
},
"custom_attributes": []
}
}
}
| Attribute | Type | Description |
|---|---|---|
| payment | object | Container object holding payment data. |
| payment.note | object | The note associated with the payment. |
| payment.note.file | object | Specific file object attached to the note. |
| payment.note.file.uuid | string | Unique identifier (UUID) of the file. |
| payment.note.file.name | string | Name of the uploaded file. |
| payment.note.file.version | string | Version number of the file. |
| payment.note.custom_attributes | array | Custom attributes defined for the note. |