All Tools
Tools/ISO 8583 ↔ On-Chain Settlement Mapper
🔁
BlockchainBeta
ISO 8583 ↔ On-Chain Settlement Mapper
Map card settlement fields — DE 4, 5, 9, 15, 32, 49, 50, 97 and the reconciliation totals — to their on-chain stablecoin equivalents, see what exists on only one side, and convert one settlement amount into both forms.
Worked example
| ISO 8583 / clearing | On-chain | |
|---|---|---|
| Amount | DE 4 / DE 5 = 000000125000 | 1250000000 (6 decimals) |
| Currency | DE 49 / DE 50 = 840 (USD) | USDC on Base — 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
| Settlement date | DE 15 = 1005 (2026-10-05, next business day) | 2026-10-03 — block timestamp; can settle the same day, weekends included |
| Reference | Settlement report / batch ID from clearing | Transaction hash of the settlement transfer |
| Counterparty | DE 32 acquiring institution ID | Registered settlement wallet address |
USDC uses 6 decimals, so the on-chain integer is 4 digits longer than DE 4. Scaling with the wrong decimals is the classic reconciliation break.
2026-10-03 is a Saturday: fiat settlement waits 2 days, until 2026-10-05, while an on-chain transfer can settle the same day.
Field mapping
Amount & currency
| ISO 8583 / clearing | On-chain | Relationship |
|---|---|---|
| DE 4 — Amount, transaction (n12, minor units) | Token amount (integer in the token's decimals) | Changes form |
| ISO 8583 scales by the currency's ISO 4217 exponent (USD 2); a token scales by its contract decimals (USDC 6, USDP 18). The same $1,250.00 is 000000125000 in DE 4 and 1250000000 USDC units. | ||
| DE 49 / DE 50 — Currency code, transaction / settlement (ISO 4217 numeric) | Token contract on a specific chain | Changes form |
| On-chain, the "currency" is a contract address. USDC on Ethereum and USDC on Solana are different assets to reconcile, and USD can arrive as USDC, PYUSD or USDG. | ||
| DE 5 — Amount, settlement | Amount transferred to the settlement wallet | Same concept |
| The net or gross settlement amount becomes the value of the transfer between network and member wallets. | ||
| DE 9 — Conversion rate, settlement | Peg / mint-redeem rate, plus FX when currencies differ | Changes form |
| A USD stablecoin settles USD 1:1 against its reserve, so the rate is the peg — but on- and off-ramp fees and any EUR↔USD conversion still need recording. | ||
| DE 6 / DE 10 / DE 51 — Cardholder billing amount, rate, currency | — | No on-chain equivalent |
| Cardholder billing is the issuer's fiat side and does not change; the cardholder never sees the stablecoin. | ||
| — | Network fee (gas) | On-chain only |
| Each transfer costs gas in the chain's native asset — or in USDC on chains such as Arc. It is a settlement cost with no ISO 8583 field. | ||
Dates & finality
| ISO 8583 / clearing | On-chain | Relationship |
|---|---|---|
| DE 15 — Date, settlement (MMDD) | Block timestamp of the settlement transfer | Changes form |
| A business-day date becomes a timestamp. On-chain settlement runs every day of the week, so weekend and holiday settlement no longer rolls to the next business day. | ||
| — | Block number, confirmations, finality status | On-chain only |
| Record when the transfer became final (seconds to minutes, depending on the chain) — that is the moment funds are irrevocably settled. | ||
| DE 7 — Transmission date and time | — | No on-chain equivalent |
| Authorization and clearing messages keep their own timestamps; they are not on-chain. | ||
Identification
| ISO 8583 / clearing | On-chain | Relationship |
|---|---|---|
| DE 32 / DE 33 — Acquiring / forwarding institution ID | Registered settlement wallet address | Changes form |
| Members settle to wallets registered (allowlisted) with the network; a payment to any other address is an exception to investigate, not a settlement. | ||
| DE 11 STAN, DE 37 RRN, DE 38 Approval code | — | No on-chain equivalent |
| Transaction-level references stay off-chain. A settlement transfer moves a batch total and carries no per-transaction detail. | ||
| — | Transaction hash | On-chain only |
| The unique, publicly verifiable reference for the settlement movement. Store it against the settlement batch or report ID — it is the join key between the clearing file and the chain. | ||
| — | Chain ID and token contract | On-chain only |
| Needed to look the transfer up at all; the same hash format exists on many EVM chains. | ||
Reconciliation
| ISO 8583 / clearing | On-chain | Relationship |
|---|---|---|
| DE 74–77 / DE 86–89 — Credit and debit counts and amounts | Sum of transfers in the settlement window | Changes form |
| Reconciliation totals still come from clearing; the chain proves only that the net amount moved. | ||
| DE 97 — Amount, net settlement | Net settlement transfer | Same concept |
| Usually one transfer per member, currency and window; match amount, wallet and window. | ||
| Clearing records (IPM, Base II) | — | No on-chain equivalent |
| Clearing files keep their formats; only the funds movement changes rail. | ||
Exceptions
| ISO 8583 / clearing | On-chain | Relationship |
|---|---|---|
| Reversals (0400 / 0420) | — | No on-chain equivalent |
| Transfers are final. A correction is a new transfer in the opposite direction in a later settlement, never a reversal of the old one. | ||
| Chargebacks (DE 25 reason codes, dispute cycle) | — | No on-chain equivalent |
| Disputes run off-chain as before; their financial outcome lands in a future settlement total. | ||
| — | Frozen or blocklisted address | On-chain only |
| Regulated issuers can freeze addresses. A settlement wallet that gets frozen is an operational incident with no card-rail equivalent. | ||
What does not move on-chain
Authorization stays ISO 8583 with EMV cryptograms and network tokens, and clearing keeps its files. Only the funds movement between the network and its members changes rail — so reconciliation gains the on-chain fields above (hash, chain, contract, finality), while reversals and chargebacks keep working off-chain and settle as new transfers. Background: Stablecoin Payments 101, Settlement & Clearing; coins, chains and contracts: Stablecoin Reference; decode a settlement transfer in the Calldata Decoder.
Something wrong or missing? Report a problem— we check reports against the specs and fix them.