How to connect Stripe for reconciliation

Ledfra needs a restricted Stripe key that can read three things and change nothing. Your ledger records what your code posted. Stripe records what actually happened to the money: the charge, the fee it kept, the days the funds spent pending before it released them. Stripe reconciliation is comparing the two, and it is how you find the refund your code never recorded or the fee you modelled at the wrong rate. This page takes you from a new key to a ledger Ledfra compares against Stripe every few minutes.

What Ledfra reads, and what it never does

Ledfra reads your Stripe balance and its balance transactions, the record of every movement in and out of it. It never creates a charge, a refund, or a payout, and it never writes anything to Stripe.

That is why the key should be a restricted key, not your secret key. A secret key can do anything your account can, including move money. A restricted key can do only what you grant it, and Ledfra needs nothing beyond reading.

1. Create a restricted key

In the Stripe Dashboard, open Developers, then API keys, and choose Create restricted key.
Name it after what it is for, such as Ledfra reconciliation. The name is what you will look for in a year when you wonder what the key does.
Set these three permissions to Read, and leave every other permission at None.

Permission	Access	Why Ledfra needs it
Account	Read	To learn which Stripe account the key belongs to.
Balance	Read	To compare Stripe's pending and available balances with your ledger.
Balance transaction sources	Read	To read each movement, so a difference can be traced to the payment behind it.

A key created in test mode reads Stripe's test data, and a live key reads real money. Create the one that matches what this ledger records.

All three, or nothing works

Ledfra checks that the key works when you connect it, but not that it holds all three permissions. A key missing one is accepted and then cannot read what it needs, so the ledger quietly stops updating. If you connect a key and the reconciliation report never fills in, check these three first.

2. Connect it in Ledfra

Open the ledger, choose Payment processors in the sidebar, select Stripe, paste the key, and choose Connect Stripe.

Ledfra checks the key with Stripe before storing it. A key Stripe refuses is not stored, and the reason is shown in Stripe's own words, which tell an expired key apart from a revoked one. Once stored, the key cannot be read back by the screen, the API, or anything else. Only its last four characters are kept, so you can tell which key is installed.

The Stripe card then shows the account the key belongs to and whether it is a test mode or a live key, read from the key itself: Stripe starts test keys with sk_test_ or rk_test_, and live keys with sk_live_ or rk_live_.

3. Link the accounts that mirror Stripe's balances

Stripe keeps two balances per currency. Pending is money charged and not yet released, which typically sits there for several days. Available is money you can pay out. Ledfra compares each one with an asset account in your ledger, so you link two accounts per currency. The form starts with two new ones, already named and keyed. Pick existing accounts instead if your integration already posts to them.

The form shows what Stripe holds beside each account's balance, then asks where reconciliation should start:

The beginning compares the whole Stripe history. Choose it for a new Stripe account, or a ledger that already records every past movement.
Now takes what Stripe holds today as the opening balance and posts it in your ledger. Choose it when the account has history this ledger does not record. It is the default, because a new account holds nothing yet.

Splitting pending from available is the part most ledgers get wrong. Counting pending money as cash reports a platform as solvent days before it is. Accounts explains how to model the two.

Where the opening balance comes from

Starting from now, Ledfra posts what Stripe holds as an opening entry, dated at the moment it read Stripe. It debits your available and pending accounts and credits an equity account called Opening balances, which Ledfra creates the first time and reuses for every processor you connect after that. Without it, the account would read $0 while Stripe holds the money, and the first payout drawn from it would be refused as overdrawing an account that Stripe says is full.

Accountants know this as an opening balance offset, the same role QuickBooks gives its Opening Balance Equity account. Yours may reclassify it by journal when they close the books. Renaming it is safe too, because Ledfra remembers it by its id rather than its name.

Charges still pending at that moment need one more step. Each one moves into available on Stripe's own schedule, and your integration only records that move for charges it made itself. So for a charge made before you connected, Ledfra posts the move: it debits your available account and credits your pending account, dated the day Stripe released the money, with the charge's balance transaction id as its reference. Your ledger's cash then matches Stripe's as each one clears. These entries are Ledfra's, so they never appear among the postings the reconciliation asks you to explain.

An existing account that already carries postings cannot start from now: its own postings plus the opening would count the same money twice. The form says so as soon as you pick one. Start that account from the beginning, or link a new account.

What you see next

Within a few minutes the first read pulls in the account's history, and the Reconciliation report under Reports fills in. Its balance proof says whether each balance agrees with your ledger, and the list beneath it shows every Stripe movement next to the posting that recorded it, or the gap where a posting should be.

Limits

One Stripe account per ledger. Once accounts are linked, a key for a different Stripe account is refused, because the history already matched belongs to the first one. A second Stripe account needs a ledger of its own.
Links are permanent. The movements already matched stay with the accounts they were matched to. Replacing or withdrawing the key leaves the links in place.
Nothing converts between currencies. Each currency is linked and compared on its own, and a USD pair says nothing about EUR.
This compares your ledger with Stripe, not with your bank. A payout that left Stripe is a movement Stripe reports. Whether it arrived in your bank account is outside what Ledfra reads.

Where to go next

How to connect PayPal - the same setup for a PayPal account.
Transactions - how to post a payment and the processor's fee in one transaction.
What is Ledfra? - where reconciliation fits in the whole model.