Reconciliations
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
orcredit
) (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
ormessage_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
andvirtual account
- Rule #2 based on
date
andmandate reference
As a result, a new transaction is reconciled with a payment, if:
- Rule #1: their
amount
anddirection
anddate
andvirtual account
match OR - Rule #2: if their
amount
anddirection
anddate
andmandate 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.
Request
curl --request POST \
--url https://sandbox.numeral.io/v1/reconciliations \
--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
}
'
Response
{
"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 status | Logic |
---|---|
unreconciled | reconciled_amount = 0 |
partially_reconciled | amount > reconciled_amount > 0 |
reconciled | amount = reconciled_amount |
Cancel a reconciliation
If you or Numeral have created an incorrect reconciliation, you can cancel it using the Cancel a reconciliation feature.
Updated 2 months ago