Payment records
Learn how to track and keep a history of payments.
Overview
Payment records are a way to track the payment history of payables (bills) and accounts receivable invoices. The /payment_records
endpoint allows you to take note of every payment made towards a payable or an invoice.
If you use Monite payment rails together with account payables or accounts receivable, Monite automatically stores all payment information for payables and receivable invoices. However, when using external payment rails, you must manually create records for each payment instance - full or partial - made towards invoices.
Roles and permissions
To use the /payment_records*
endpoints with an entity user token, this entity user must have a role with the payment_record
permission.
If using a partner-level token, no special permissions are needed.
Create a payment record
To create a payment record for a payable or receivable invoice, call POST /payment_records
. The request fields are described below:
payment_intent_id
- the external payment reference number or transaction ID for the payment.object.type
- defines the invoice type for which the payment was made -payable
orreceivable
.object.id
- represents the UUID of the payable or receivable.
Monite automatically updates the status
of the specified invoice to reflect the payment made and returns the old and new statuses in the response. The response also contains a unique id
assigned to this payment record.
Some important response fields are described below:
-
status
- status of the payment record indicating its current stage. The possible values arecreated
,processing
, andsucceeded
. -
payment_intent_status
- the payment status or payment intent in the partner’s payment rails. -
payment_method
- payment method used or planned for the transaction. -
planned_payment_date
- scheduled date for future payments, required when the payment is planned but not yet executed. -
paid_at
- the time when the payment was executed.
Retrieve a payment record
Monite stores all of an entity’s payment records. This includes payment records created manually via the POST /payment_records
endpoint and those automatically created when an entity uses Monite payment rails. To retrieve an existing payment record, call GET /payment_records/{payment_record_id}
as shown:
The successful response contains complete details of the payment record requested:
The is_external
field in the response indicates whether the payment record was created manually (true
) or automatically triggered via Monite’s payment rails (false
).
Get all payment records
To get a list of all payment records, send a GET
request to the /payment_records
endpoint as shown:
The successful request returns a paginated history of all payment records—internal or external.
You can sort and filter the results of this request by the order, limit, object UUID, and other fields. For the full list of available sort and filter parameters, see the description of the GET /payment_records
endpoint.
Get all payment records for a payable or receivable
To retrieve all payment records associated with a payable or receivable, call GET /payment_records
and include the object_id
query parameter. For example, the following snippet will return all payment records associated with a particular invoice:
Get all internal or external payment records
To filter payment records by their origin, call GET /payment_records
and include the is_external
query parameter. For example, the following snippet will return payment records created using Monite’s payment rails:
External payment records
External payment records are allocated with a status that indicates their progress on the external payment system. In Monite, external payment records can have the following statuses:
-
created
- This is the status for draft payment records. The payment record exists and is linked to an invoice but has not been applied yet, so it does not affect the invoice’s status or amounts. -
processing
- This is the status for scheduled payment records while they are being processed. To move the payment record to this status, callPOST /payment_records/{payment_record_id}/start_processing
. -
succeeded
- This is the terminal status for the payment records. It means the payment record is registered. To move the payment record to this status, callPOST /payment_records/{payment_record_id}/mark_as_succeeded
passing thepaid_at
field in the body request.
Updating or canceling a payment record
External payment records in the created
status can be manually canceled or updated:
- To update a payment record, call
PATCH /payment_records/{payment_record_id}
. - To cancel a payment record in the
created
orprocessing
statuses, callPOST /payment_records/{payment_record_id/cancel}
. Succeeded payment records cannot be canceled. - To refund a payment that has already succeeded, you must create a new payment record with a negative value in the
amount
field.
Only payment records in the created
status can be updated.