Card processor

The card processor runs your organisation’s cards on its behalf. It connects to the card schemes, holds the card numbers, and asks your organisation whether to approve each purchase. Your organisation keeps the accounts and the record of what was spent.

What the processor does, and what your organisation does

flowchart LR
    Shop[Merchant] --> Scheme[Card scheme]
    Scheme --> Processor[Card processor]
    Processor -- "May I approve?" --> Bank[Your organisation]
    Bank -- "Approved or declined" --> Processor
    Processor -- "Daily clearing file" --> Bank
The processor Your organisation
Holds every card number, and never sends one to you. Knows each card by a token, its first digits and its last four.
Asks you to approve each purchase, and stands in if you do not answer in time. Answers each request inside the decision budget.
Sends a clearing file each morning for the day before. Imports the file and keeps it as the record of what cleared.

Your organisation never stores a card number. The processor holds it, so the systems that hold one stay with the processor. See the PCI DSS v4.0 — scope avoidance row in the standards register.

What you see

The Card processor page shows the processor your organisation uses.

Field What it tells you
Connection The institution connection the processor speaks over.
Processor Which processor answers on that connection.
Environment The processor’s environment, such as its sandbox or production service.
API address Where your organisation calls the processor.
Credential Whether the secret your organisation presents to the processor is set.
Decision budget How long your organisation has to answer a purchase.
Settlement account The account the processor settles your cards through.
Operating entity The entity that owns the settlement account.

Declaring the processor

  1. Declare the processor as an institution connection first, with transport ProcessorApi.
  2. On the Card processor page, select Declare processor.
  3. Choose the Connection.
  4. Choose the Processor.
  5. Enter the API address and the name of the Credential.
  6. Choose the Operating entity, and enter the Settlement account.
  7. Enter the Decision budget in seconds.
  8. Select Save.

Enter the credential’s value on the Secrets page. The processor page holds only its name.

If the connection does not use transport ProcessorApi, the processor is refused.

The decision budget

If your organisation does not answer a purchase inside the budget, the processor answers for you. It uses the rules your organisation agreed with it, called stand-in. Your organisation then records the request as not answered.

The budget is at least half a second and at most ten seconds. It is two seconds unless you change it.

The simulator

In a demonstration or test environment, the processor can be a simulator. The simulator behaves like a real processor: it creates cards, asks for approvals, and writes a clearing file at end of day.

The simulator is refused unless simulation is switched on for your organisation. Simulation is never available in production.

Simulated credential life shortens how long a simulated card lives, in months, so a demonstration sees a card renewed. A card’s life runs from the trading date it was issued or reissued. The months must outlast every card type’s renewal lead, counting a month as 28 days: two months clears a 45-day lead, one does not. A real processor ignores this setting.

Simulation actions

When simulation is on, the card shows actions that play the merchant’s and the cardholder’s part. Each is an amber button marked SIM, in the colours of the top bar’s simulation badge. When simulation is off, none of them shows, and the simulator refuses the request anyway.

Action Where it sits What it does
Simulate tap The header of the card’s Holds and Authorisations panels Sends a purchase to the card’s authorisation checks. The real checks decide.
Merchant reverses An open row on the card’s Holds panel The merchant cancels part or all of the hold.
Merchant refunds A purchase row on the card’s Purchases panel Queues a refund for the next clearing file.
Add to phone wallet Inside Simulate tap, when you tap with a phone the card does not have yet Puts the card on a phone, answering the step-up as the cardholder would.

The simulator records no person. The card’s history names the processor’s connection, as it would for a real purchase.

Simulating a tap

  1. Open the card and select Holds.
  2. Select SIM Simulate tap.
  3. Choose a Preset. It sets how the card was used.
  4. Enter the Amount charged to the card.
  5. Change the merchant, its category or its country if you need to.
  6. Select Simulate tap.

The result shows under the form: the outcome, the amount approved, and the reason and rule for a decline. The form stays open, so you can tap again.

Preset How the card was used Card present
Shop, chip and PIN In store, chip Yes
Shop, tap card In store, contactless Yes
Shop, tap phone In store, with a phone wallet Yes
Online Online, card details typed No
ATM Cash at an ATM, chip Yes
Abroad, tap card In store abroad, contactless, in a foreign currency Yes

The merchant category is an ISO 18245 code, picked from a short list of common ones. The merchant country is an ISO 3166-1 alpha-2 code, and starts as your organisation’s domestic country.

A tap works on a card in any status. An ordered, suspended or closed card shows the real decline.

Worked example: a card draws on an account with 10,000.00 available. A tap of 250.00 at a grocer is approved for 250.00. The account’s available balance falls to 9,750.00.

A purchase in another currency

If the merchant’s currency differs from the card’s, the form asks for both amounts. The card scheme converts the merchant’s amount, so you type what the card is charged as well. The checks decide on the amount charged to the card. No exchange rate is read.

Cleared at is optional. It sets a different amount for the clearing file, as when the scheme’s rate moved overnight. The hold still releases in full.

If the merchant reverses part of a foreign purchase, its own amount shrinks in the same proportion. It rounds half up to the merchant currency’s minor unit (ISO 4217).

Worked example, a card in rand with a 2.75% currency conversion fee on its price list:

What happened Clears as Conversion fee
A tap of EUR 100.00, charged 1,950.00 EUR 100.00, 1,950.00 53.63
The same tap, the merchant reverses 975.00 EUR 50.00, 975.00 26.81
The same tap, cleared at 1,962.40 EUR 100.00, 1,962.40 53.97

Reversing and refunding

Merchant reverses takes an amount, or none for the whole hold. Worked example: a fuel tap of 500.00 holds 500.00. The merchant reverses 180.00, and the hold is 320.00.

Merchant refunds takes an amount in the card’s currency. Nothing posts when you select it: the refund is queued for the next end of day, and the account is credited then. Refunds on one purchase cannot add up to more than the purchase.

Worked example: a purchase of 250.00 posted. The merchant refunds 80.00. At the next end of day the account is credited 80.00. A dispute for the full 250.00 is still accepted, because a refund is a separate credit.

Receipts

Every question the processor asks is kept as a receipt, whatever the answer. The Receipts table lists them for the trading dates you choose, newest first. It shows today’s trading date when the page opens.

Kind What the processor asked
Authorisation May the card pay this merchant this amount?
Reversal The merchant cancelled an authorisation.
Token provisioning May a phone or watch wallet hold the card?
Outcome What it means
Approved Your organisation said yes. A reversal of a known authorisation also reads Approved.
Partially approved Your organisation approved part of the amount.
Declined Your organisation said no. The Reason column says why.
Not answered No answer came inside the decision budget, so the processor stood in.
Unknown authorisation The processor reversed an authorisation your organisation never saw. It is accepted, because the processor’s record is the one that counts.
Step up The wallet must confirm the cardholder before it holds the card.

The processor may ask the same question twice. The second time it gets the first answer, and no second receipt is written.

A receipt belongs to the trading date it arrived on. A request that arrives after end of day belongs to the new trading date, even if the clock has not reached midnight.

For example, if the processor approves a 5,000.00 authorisation, reverses it, declines a 1,250.00 one as not ready, and asks to provision a wallet, you see four receipts. The wallet’s Step up is on top, because it arrived last.

Clearing batches

Each morning the processor sends a clearing file for the day before. It lists every purchase, refund and reversal that settled that day. Your organisation keeps one clearing batch per business date.

The Clearing batches table shows each business date, how many items cleared, the file version it was read from, and whether the simulator wrote it.

Situation What happens
The processor has published the file End of day fetches it and keeps it as that date’s batch.
The file is not published yet No batch is written. The next end of day asks again.
End of day was missed for a few days The next end of day fetches every day since the last batch.
A day had no card activity The batch exists and has no items.

Cards clear on weekends and public holidays too, so a Monday end of day also fetches Saturday and Sunday.

A batch is keyed by the business date its items cleared on, never by the day it was fetched. That is the date a reconciliation matches against.

Posting the clearing lines

At end of day, each clearing line posts to the cardholder’s account and releases its hold.

A hold of 1,200.00 on an account holding 4,200.00 clears at 1,150.00, after a tip was taken off. The account is debited 1,150.00 and the whole hold is released, so the balance and the available balance both read 3,050.00.

Line Where it posts
A purchase with a hold The account the hold is on, for the final amount
A purchase with no hold, or one already ended The hold’s account, or the first account in the card’s funding rule
A refund The account the purchase went to, as a credit
A reversal The account its purchase posted to, as a credit
A chargeback Nothing posts. It shows as an exception for the dispute process.

A purchase posts even when the account does not have the money. The processor has already paid the merchant. A line the account refuses, for example because it is closed, shows as an exception on the batch. It is tried again at every end of day, and the hold stays until it posts or expires.

Each line posts once. Fetching the same file again posts nothing twice.

One processor per organisation

Your organisation has one card processor. If you point it at another connection, the first connection is freed. While the processor uses a connection, that connection cannot be removed.

If your organisation requires a second person to approve settings changes, the same checks run again when they approve.

What your organisation configures

Which external system may speak for the connection is not a tenant setting. A platform administrator registers it.

Cards on this processor

The processor answers for the cards your organisation issues. Issue, suspend, reissue and close cards from the customer’s Cards panel — see Cards. Card types are set up under Card types.

From the LedgerTM product guide, as shipped with the software and written with it. Copied from the platform repository on 2026-11-11.