Payment records

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.

📘

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, 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: 2024-01-31' \
     -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 or receivable. The object.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: 2024-01-31' \
     -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: 2024-01-31' \
     -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: 2024-01-31' \
     -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: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'