As transactions are posted on a connected account, Numeral automatically reconciles them with unreconciled payments, based on their respective attributes. Payments and transactions can also be reconciled manually using the Numeral API or web app.

A reconciliation takes the form of a Reconciliation object and always reconciles a single payment with a single transaction. Multiple reconciliations can be created to reconcile a single payment with multiple transactions or multiple payments with a single transaction.

The types of payments that can be reconciled are:

Automated reconciliation engine

Numeral automatically reconciles payments and transactions. You can use the default reconciliation engine or setup custom reconciliation rules. A reconciliation rule has a type (one-to-one or one-to-many) and criteria, which include:

  • Amount (mandatory)
  • Direction (debit or credit) (mandatory)
  • Date
  • Connected account
  • Counterparty information (name, account number…)
  • Transaction category
  • Description (or reference)
  • Virtual account used
  • Direct debit mandate reference
  • Technical IDs (e.g. end_to_end_id or message_id)
  • Metadata

Criteria can be combined to create a reconciliation rule. Reconciliation rules are ranked. The engine goes through reconciliation rules, based on their rank. The engine automatically stops when a reconciliation is created.

Example: a customer creates the two following reconciliation one-to-one rules:

  • Rule #1 based on date and virtual account
  • Rule #2 based on date and mandate reference

As a result, a new transaction is reconciled with a payment, if:

  • Rule #1: their amount and direction and date and virtual account match OR
  • Rule #2: if their amount and direction and date and mandate reference match

Manually reconcile a payment with a transaction

It can happen that Numeral is not able to automatically reconcile one or multiple payments. When this happens, you can use the Numeral API or web app to manually create a reconciliation, using the Create a reconciliation feature.


curl --request POST \
  --url \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY'
  --data '
      "payment_id": "ae14358d-e8bf-4d29-8367-50dd23782c83",
      "transaction_id": "eb6bc39b-73a5-401f-997b-138d84514c44",
      "amount": 120


  "id": "7d399984-b435-4a63-ab11-4a4185c13cba",
  "object": "reconciliation",
  "amount": 120,
  "match_type": "manual",
  "transaction_id": "eb6bc39b-73a5-401f-997b-138d84514c44",
  "payment_id": "ae14358d-e8bf-4d29-8367-50dd23782c83",
  "payment_type": "payment_order",
  "metadata": {},
  "canceled_at": null,
  "created_at": "2023-08-09T12:17:07.48448Z"

If you need to reconcile a payment with multiple transactions or a transaction with multiple payments, you should create multiple reconciliations.

You can list the reconciliations related to one transaction or one payment using the List all reconciliations feature, passing the transaction ID in the transaction body parameter or the payment ID in the payment body parameter.

Reconciled amount

As a payment or transaction gets reconciled, its reconciled_amount is computed and updated.

Reconciliation status

As payment and transactions are reconciled, their reconciliation_status is updated:

Reconciliation statusLogic
unreconciledreconciled_amount = 0
partially_reconciledamount > reconciled_amount > 0
reconciledamount = reconciled_amount

Cancel a reconciliation

If you or Numeral have created an incorrect reconciliation, you can cancel it using the Cancel a reconciliation feature.