Payment records

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 or receivable.
• object.id - represents the UUID of the payable or receivable.

1
curl -X POST 'https://api.sandbox.monite.com/v1/payment_records' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "object": {
8
         "type": "receivable",
9
         "id": "1877d46f-2f16-484d-a44a-b537b30c2f34"
10
       },
11
       "amount": 500,
12
       "currency": "EUR",
13
       "payment_intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
14
     }'

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.

1
{
2
  "id": "7d3e16c4a133-b2ed-17b8-4462-2724e6bf",
3
  "amount": 1,
4
  "currency": "EUR",
5
  "is_external": true,
6
  "object": {
7
    "id": "1877d46f-2f16-484d-a44a-b537b30c2f34",
8
    "new_status": "paid",
9
    "old_status": "issued",
10
    "type": "receivable"
11
  },
12
  "payment_intent_id": "5a584e56-1a1e-4f9f-b031-ddceb5484470",
13
  "entity_user_id": "c8192600-d792-4f2d-aaf8-cdd123563619",
14
  "overpaid_amount": 0,
15
  "paid_at": "2024-01-15T09:30:00Z",
16
  "payment_intent_status": "settled",
17
  "payment_method": "sepa_credit",
18
  "planned_payment_date": "2024-01-15T09:30:00Z",
19
  "status": "succeeded"
20
}

Some important response fields are described below:

• status - status of the payment record indicating its current stage. The possible values are created, processing, and succeeded.

• 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:

1
curl -X GET 'https://api.sandbox.monite.com/v1/payment_records/7d3e16c4a133-b2ed-17b8-4462-2724e6bf' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

The successful response contains complete details of the payment record requested:

1
{
2
  "id": "7d3e16c4a133-b2ed-17b8-4462-2724e6bf",
3
  "entity_user_id": "2724e6bf-17b8-4462-b2ed-7d3e16c4a133",
4
  "payment_intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
5
  "object": {
6
    "id": "1877d46f-2f16-484d-a44a-b537b30c2f34",
7
    "type": "receivable",
8
    "new_status": "partially_paid",
9
    "old_status": "issued"
10
  },
11
  "paid_at": "2023-10-16T11:59:54.789Z",
12
  "amount": 500,
13
  "currency": "EUR",
14
  "overpaid_amount": 0,
15
  "is_external": true
16
}

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:

1
curl -X GET 'https://api.sandbox.monite.com/v1/payment_records' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -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, 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:

1
curl -X GET 'https://api.sandbox.monite.com/v1/payment_records?object_id=1877d46f-2f16-484d-a44a-b537b30c2f34' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

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:

1
curl -X GET 'https://api.sandbox.monite.com/v1/payment_records?is_external=false' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

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, call POST /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, call POST /payment_records/{payment_record_id}/mark_as_succeeded passing the paid_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 or processing statuses, call POST /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.