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.

Payment record types

There are two types of payment records:

• Monite-created payment records - These are created automatically for all payments made via the Monite payment links. Each payment intent gets an associated payment record that is used to reconciliate this payment with the related payable or receivable invoice.

  Monite-created payment records have the is_external field set to false. These payment records can only be retrieved, but not modified directly by users.

• External payment records - can be created and updated by the entity. These are intended for entities that use their own payment rails, and are meant to record information about full or partial payments made via external channels.

  External payment records can have different statuses to mirror the payment procesing status from external systems. They can also store information about future scheduled payments.

Entities that use Monite payment rails can also create external payment records to reflect payments made outside the Monite platform.

Get all payment records

To get a list of all payment records, call GET /payment_records:

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—both Monite-created and external.

To get only Monite-created or only external payment records, use the is_external query parameter. For example, the following snippet returns only payment records created using Monite 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'

You can sort and filter the results of this request by invoice type (payable or receivable), payment record status, and other parameters. For the full list of available sort and filter parameters, see the description of the GET /payment_records endpoint.

Get payment records for an invoice

To find all payment records associated with a specific payable or receivable invoice, call GET /payment_records and specify the invoice ID in the object_id query parameter:

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'

External payment records

Payment record statuses

External payment records are allocated with a status that indicates their progress in the external payment system.

created

This is the status for draft payment records that are created manually. 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 amount due. Payment records in the created status can be fully edited.

processing

This status is used for payments that are being processed by the bank or financial institution. To move the payment record to this status, call POST /payment_records/{payment_record_id}/start_processing.

Payment records in the processing status cannot be modified but is still not applied to the invoice. You must manually move it to succeeded or canceled status once the external payment completes.

succeeded

This is a final status that indicates successful payments and sucessful refunds. To move a payment record to this status, call POST /payment_records/{payment_record_id}/mark_as_succeeded passing the paid_at field in the body request.

Succeeded payment records modify the amount due and status of the linked invoice:

• Records with a positive amount increase the invoice’s amount_paid and reduce the amount_due.
• Records with a negative amount (that is, refunds) reduce the invoice’s amount_paid and increase the amount_due.

canceled

Payment records in the created and processing statuses can be canceled. Once canceled, the payment record will not be applied to the invoice and cannot be modified further. This is a final status.

Create a payment record

To create a payment record for a payable or receivable invoice, call POST /payment_records with the following request fields:

• object.type - the invoice type (payable or receivable) for which the payment was made.
• object.id - ID of the payable or receivable invoice.
• amount and currency - use a positive amount value for payments made toward the invoice, and negative values for refunds.
• payment_intent_id - the external payment reference number or transaction ID for the payment.

Additional optional fields:

• status - the status of the payment record. You can create records in the created, processing, or succeeded status. If omitted, defaults to succeeded.
• payment_intent_status - the status of the corresponding payment or payment intent in the partner’s payment rails. A user-defined string.
• payment_method - payment method used or planned for the transaction. A user-defined string.
• For records in the created status that indicate future scheduled payments:
  • planned_payment_date - scheduled date for a future payment, required when the payment is planned but not yet executed.
• For records in the succeeded status:
  • paid_at - date and time when the payment was made.

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
     }'

The response also contains a unique id assigned to this payment record. Monite automatically updates the status of the specified invoice to reflect the payment made and returns the old and new statuses in the response:

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
}

Update or cancel 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.

Refunds

If a succeeded payment record has been refunded, you can record the refund by creating a new payment record with a negative value in the amount field. This reduces the invoice’s amount_paid, increase the amount_due, and also updates the invoice’s status if needed.

Scheduled payment records

Scheduled external payment records represent invoice payments that are planned but not yet made. The payment can be full or partial.

Monite does not trigger payments based on scheduled payment records. The payment is supposed to be made by the entity itself via their preferred channel. The purpose of scheduled payment records is to record the fact that the payment is planned, and to mirror the payment status from the external system so that Monite can reconciliate the external payment with the associated invoice.

Create a scheduled payment

To create a schedule payment, call POST /payment_records and provide the following fields in addition to the required ones:

• status - set to created,
• planned_payment_date - use the YYYY-MM-DD format,
• payment_method - (optional) a user-defined identifier of the payment method that will be used, for example, bank_transfer, card, or cash.

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": "payable",
9
         "id": "41b3d21c-d113-4ca7-8be0-698da4b409fe"
10
       },
11
       "amount": 50000,
12
       "currency": "EUR",
13
       "status": "created",
14
       "planned_payment_date": "2025-08-15",
15
       "payment_method": "bank_transfer"
16
     }'

The created payment record has the created status and will not affect the invoice’s status or amounts until it’s marked as succeeded.

Update scheduled payment details

While a scheduled payment record is still in the created status and has not started processing, you can update its details in Monite: amount, planned_payment_date, payment_method, and other fields. To update the scheduled payment details, call PATCH /payment_records/{payment_record_id}.

Start processing a scheduled payment

When a scheduled payment begins processing in your external system, call POST /payment_records/{payment_record_id}/start_processing to move the corresponding payment record to the processing status. In the request body, you can optionally provide the payment_intent_status field containing the payment status in the external system (as an arbitrary user-defined string):

1
curl -X POST 'https://api.sandbox.monite.com/v1/payment_records/60b58b07-e29d-43fd-822f-f6474820f8b2/start_processing' \
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
       "payment_intent_status": "approved"
8
     }'

While a payment record is in the processing status, the invoice status and amounts are still not updated until the payment is marked as succeeded.

Complete a scheduled payment

When the external payment succeeds, call POST /payment_records/{payment_record_id}/mark_as_succeeded to apply the payment to the invoice. In the request body, provide the paid_at value and, optionally, the new external payment_intent_status:

1
curl -X POST 'https://api.sandbox.monite.com/v1/payment_records/60b58b07-e29d-43fd-822f-f6474820f8b2/mark_as_succeeded' \
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
       "paid_at": "2025-08-15T09:30:00Z",
8
       "payment_intent_status": "completed"
9
     }'

This moves the payment record to succeeded status and updates the invoice’s amount_paid, amount_due, and status accordingly.

Cancel a scheduled payment

To cancel a scheduled payment that hasn’t been executed, call POST /payment_records/{payment_record_id}/cancel. You can cancel payment records in the created and processing statuses.