Skip to Content
Open Books for developers

Payment settlements

Check gateway settlement arithmetic and payout totals with Open Books, then reconcile released amounts against bank credits.

Payment providers collect money, deduct fees, and send payouts to a bank account. A settlement export explains how the provider arrived at a payout. Open Books checks the arithmetic within the export. Matching that payout to the receiving bank statement is a second step.

1. Export the settlement detail

Choose the provider's balance or settlement report for the payout you want to verify. Keep the original headers, transaction identifiers, fee columns, and payout totals. See the format matrix for recognized Stripe, Razorpay, PayPal, and Wise layouts.

2. Process the export

This Node.js example uses a Razorpay CSV in INR. Follow the Node.js setup, then install the gateway wrapper with npm install @lumeo_hq/openbooks-gateways.

import { runFile } from "@lumeo_hq/openbooks-gateways";

const result = await runFile("razorpay-settlement.csv", { currency: "INR" });
if (result.kind === "released") {
  console.log(result.document.data.batches);
  console.log(result.document.assertions);
} else {
  console.error(result.code, result.message);
}

Save the example as an .mjs file and run it from the directory containing the export. For Python, pass the same file to process(). The gateway wrapper accepts the layouts listed in its LAYOUTS export.

3. Review the settlement checks

For a simple fee-bearing row, a gross payment of INR 100.00 minus INR 2.00 in fees and INR 0.36 in tax gives a net amount of INR 97.64. Read assertions to see the checks for your layout and compare their expected and computed values. Read data.batches for batch amounts and use evidence to locate the source values. For a refusal, start with the refusal code and message.

Try Razorpay settlement and Stripe export, payout off by 0.01 in the workspace. The Razorpay fixture passes the row arithmetic and payout checks. The Stripe fixture refuses because the source payout is USD 125.06 and the engine computes USD 125.05 from the rows. That message tells you which amounts to trace in the export.

4. Match the payout to a bank credit

  1. Process the receiving account's bank statement and keep both released documents.
  2. Look for a credit with the same currency and exact decimal amount. Compare payout and credit dates within the window that applies to your provider. A payout initiated on Monday can appear on a later bank date.
  3. Compare references when available. If two credits have the same amount or no candidate fits, keep the payout open for review.

Open Books' optional source-checkout linker applies exact amounts, same currency and a date window. It can report ties and grouped payouts. Check link_available in engine health before using POST /v1/link.

PayPal activity and Wise statement layouts follow publicly documented export formats and have been exercised on synthetic files. Verify representative exports before scheduling imports.

View this page as Markdown