Payment records
Learn how to track and keep a history of payments.
Payment records are a way to track the payment history of a payable or receivable. The /payment_records
endpoint allows you to take note of every payment made towards a payable or receivable.
Monite's payment rails automatically store all payment information for a payable or receivable. However, when using external payment rails, you must manually create records for each payment instance—full or partial—made towards a payable or receivable.
Create a payment record
To create a payment record for a payable or receivable, make a POST
request to the /payment_records
endpoint. You must provide the external payment reference number or transaction ID for the payment made using the payment_intent_id
field as shown:
curl -X POST 'https://api.sandbox.monite.com/v1/payment_records' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"entity_user_id": "2724e6bf-17b8-4462-b2ed-7d3e16c4a133",
"payment_intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"object": {
"id": "1877d46f-2f16-484d-a44a-b537b30c2f34",
"type": "receivable"
},
"paid_at": "2023-10-16T11:59:54.789Z",
"amount": 500,
"currency": "EUR"
}'
The
object.type
field defines the account type for which the payment was made—payable
orreceivable
. Theobject.id
field represents the UUID of the payable or receivable.
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's payment rails. To retrieve a payment record, make a GET
request to the /payment_records/{payment_record_id}
endpoint as shown:
curl -X GET 'https://api.sandbox.monite.com/v1/payment_records/7d3e16c4a133-b2ed-17b8-4462-2724e6bf' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
The successful response contains complete details of the payment record requested:
{
"entity_user_id": "2724e6bf-17b8-4462-b2ed-7d3e16c4a133",
"payment_intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"object": {
"id": "1877d46f-2f16-484d-a44a-b537b30c2f34",
"type": "receivable",
"new_status": "partially_paid",
"old_status": "issued"
},
"paid_at": "2023-10-16T11:59:54.789Z",
"amount": 500,
"currency": "EUR",
"id": "7d3e16c4a133-b2ed-17b8-4462-2724e6bf",
"overpaid_amount": 0,
"is_external": true
}
The
is_external
field in the response object is a boolean that shows whether or not the payment record was created manually or automatically triggered via Monite's payment rails.
Get all payment records
To get a list of all payment records, make a GET
request to the /payment_records
endpoint as shown:
curl -X GET 'https://api.sandbox.monite.com/v1/payment_records' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
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, you must make a GET
request to the payment_records
endpoint and include the object_id
query parameter. For illustration, the following snippet will return all payment records associated with a particular invoice:
curl -X GET 'https://api.sandbox.monite.com/v1/payment_records?object_id=1877d46f-2f16-484d-a44a-b537b30c2f34' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
Get all internal or external payment records
To filter payment records by their origin, you must make a GET
request to the payment_records
endpoint and include the is_external
query parameter. For example, the following snippet will return payment records created using Monite's payment rails:
curl -X GET 'https://api.sandbox.monite.com/v1/payment_records?is_external=false' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
Updated 26 days ago