Skip to main content
Available in version 0.7.0 and later.
Reconciliation compares and matches your Blnk Ledger with external records such as bank statements, payment processor reports, etc. to identify and resolve discrepancies in your financial data. When performed effectively, reconciliation enhances operational efficiency, financial transparency, and stakeholder trust. In this guide, you’ll learn how to run reconciliation processes with Blnk Core.

​
Before you start

To successfully run reconciliation, you need to first do three things:
  1. Prepare your external data: Format your external data according to the specified structure to enable seamless matching with your Ledger. See External Data Preparation for details.
  2. Define your matching rules: Set rules to compare fields like amount, date, or reference between your ledger and external records. These rules determine how closely records must match. See Matching Rules for details.
  3. Set your reconciliation strategy: Specify how transactions are distributed between both records, e.g., one transaction in your ledger can be split into 2 or more in a bank statement. See Reconciliation Strategies for details.

​
Reconciliation options

Blnk offers two reconciliation options based on your needs:
  1. Batch reconciliation: Ideal for scheduled bulk processing, such as daily bank reconciliations. It’s efficient for handling large volumes of transactions at once.
  2. Instant reconciliation: Best for real-time accuracy, like immediate fraud detection or on-the-fly transaction matching. It ensures your ledger stays up-to-date as transactions occur.

​
Option 1: Batch reconciliation

To reconcile in batches, you need to:
  1. Prepare and upload your external data in a CSV or JSON file for upload.
  2. Pass the upload_id from your successful upload in the request body.
  3. Set your matching rules and reconciliation strategy.
To run your batch reconciliation, call the Start Reconciliation endpoint: 
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/reconciliation/start" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "upload_8c700d1b-09c0-4ef4-9ab1-a0decf3d0aa3",
    "strategy": "one_to_many",
    "dry_run": false,
    "grouping_criteria": "reference",
    "matching_rule_ids": [
      "rule_890bdbc4-467f-4670-8424-5667e41daf29",
      "rule_a1b2c3d4-5678-90ef-ghij-klmnopqrstuv"
    ]
  }'
Response
{
  "reconciliation_id": "recon_6e6feddd-930b-4e3-8ba-1a3eee659bb3"
}
FieldTypeDescription
upload_idStringUnique identifier of the uploaded external record for reconciliation.
strategyStringDefines the reconciliation strategy to be used.
matching_rule_idsArrayAn array of rule ids that determine how the records are matched.
grouping_criteriaStringSpecifies the field used to group related records during reconciliation. Not required for one_to_one.
dry_runBooleanIf false, result is saved to the database. If true, it is not.
dry_run is useful for debugging and testing strategies when performing reconciliation. If set to true, Blnk performs the reconciliation and prints the result without saving to the database.

​
Option 2: Instant reconciliation

Available on version 0.10.1 or later.
To reconcile transactions instantly, provide the external records as an array of transactions in your request body instead of a bulk upload.
Max number of external transactions is 10,000 per request.
To run your reconciliation, call the Instant Reconciliation endpoint: 
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/reconciliation/start-instant" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "external_transactions": [
    {
      "id": "txn1a2b3c4d5e6f7g8h9i0",
      "amount": 5.49,
      "reference": "INV-2023-002",
      "currency": "GBP",
      "description": "Card payment",
      "date": "2024-11-15T14:25:30Z",
      "source": "bank-api"
    },
    {
      "id": "txn9z8y7x6w5v4u3t2s1",
      "amount": 12.75,
      "reference": "INV-2023-003",
      "currency": "GBP",
      "description": "Subscription renewal",
      "date": "2024-11-15T14:40:15Z",
      "source": "bank-api"
    },
    {
      "id": "txn5p4o3n2m1l0k9j8h7",
      "amount": 8.99,
      "reference": "INV-2023-004",
      "currency": "GBP",
      "description": "Online purchase",
      "date": "2024-11-15T14:55:10Z",
      "source": "bank-api"
    }
  ],
  "strategy": "one_to_one",
  "matching_rule_ids": [
    "rule_04c4a59e-08a1-423b-bfae-48feebe16473"
  ]
}'
Response
{
  "reconciliation_id": "recon_6e6feddd-930b-4e3-8ba-1a3eee659bb3"
}

​
Get reconciliation results

Both start endpoints return only reconciliation_id. Poll Get reconciliation for run status, match counts, and timestamps.
1

Save the reconciliation ID

Store reconciliation_id from the start response. You need it for every status poll.
2

Poll until the run finishes

Call GET /reconciliation/{reconciliation_id} until status is completed or failed.
curl -X GET "http://YOUR_BLNK_INSTANCE_URL/reconciliation/recon_6e6feddd-930b-4e3-8ba-1a3eee659bb3" \
  -H "X-blnk-key: <api-key>"
Response
{
  "reconciliation_id": "recon_6e6feddd-930b-4e3-8ba-1a3eee659bb3",
  "status": "completed",
  "matched_transactions": 3,
  "unmatched_transactions": 0,
  "is_dry_run": false,
  "started_at": "2025-03-15T17:43:26.463849Z",
  "completed_at": "2025-03-15T17:43:26.508514Z"
}
Batch runs may return status: "in_progress" on early polls. Instant runs may already be completed on the first poll, but you still need the GET response to read match counts and verify the result.

​
Verifying reconciled transactions

You can verify whether a transaction was reconciled by retrieving its details with the Get Transaction endpoint. 
curl -X GET "https://YOUR_BLNK_INSTANCE_URL/transactions/{transaction_id}" \
  -H "X-blnk-key: <api-key>"
You’ll find the reconciliation results in the meta_data object as shown below:
Response
{
  ...
  "meta_data": {
    "external_txn_id": "txn9z8y7x6w5v4u3t2s1",
    "reconciled": true,
    "reconciled_at": "2025-03-15T18:11:52.61+00",
    "reconciliation_amount": 12.75,
    "reconciliation_id": "recon_9134cb8-a3f6-47e9-b566-4fb93fa051"
  }
}
FieldDescription
external_txn_idID of the matched external transaction.
reconciled: trueIf matched successfully.
reconciled_atWhen the reconciliation was done.
reconciliation_amountAmount from the external record.
reconciliation_idUnique ID of the reconciliation process.

​
Common use cases

Reconciliation can be a great fit for you if you are building:
  1. BNPL platforms: Verify loan disbursements and repayments match merchant records, preventing billing errors and ensuring smooth settlements.
  2. Fintech apps: Sync payments from multiple sources (e.g., cards, wallets) for accurate reporting and user trust.
  3. Crypto exchanges: Reconcile transactions between wallets, smart contracts, and fiat ramps to maintain balance integrity.
  4. Payment processors: Ensure funds move correctly between merchants, banks, and users, avoiding costly mismatches.
  5. Multi-currency systems: Align balances across regions and providers, simplifying global operations.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.