Propose a clearing file's settlement reconciliation to the master account movement
/cards/clearing/files/{id}/settlementsVerified staff on the card clearing desk's narrow scopes only: cards:clearing:read for reads, cards:clearing:write with a step-up within five minutes for writes; cards:write does not reach these routes and no service token or API key does. The file formats are bank-defined approximations of the proprietary Visa BASE II, Mastercard IPM and Discover clearing specifications (services/cards/clearing/README.md); a file from the card clearing simulator is simulated, not network traffic. Proposes a processed file's settlement reconciliation against the evidenced master account movement (reference, lowercase SHA-256 of the retained advice, nonfuture value date, signed amount, positive when the network paid the bank). Every record is categorised (principal, credit, suspense debit or credit, return credit or debit, fee); posted presentments settle in principal batches of at most 250 with their interchange and scheme fees through network finance, and one direct journal carries credits (2310), suspense (2320), matched returns and unattributable interchange (4120) and fees (5500). The categories must add up to the trailer's net settlement and that net must equal the master account movement, or the proposal is 409 conflict. The file settles after its processing date's settlement date is reached, once, and a return credit settles only after the returned exception's own file settled.
Path parameters
idstringRequiredHeaders
Idempotency-KeystringRequiredSend on every write that creates or changes money or state; a replay with the same key returns the original result with 200.
Body parameters
external_cashobjectRequiredExternalCash is the actual master account movement for the file's settlement: the Federal Reserve advice or statement line, positive when the network paid the bank.
4 child attributes
amount_minorinteger or nullOptionalreferencestringRequiredsha256stringRequiredvalue_datestring · dateRequiredA business date, YYYY-MM-DD
reasonstringRequiredReturns
200 OK
chunksarray of objectsRequired9 child attributes
authorization_idsarray of stringsRequiredbatch_keystringRequiredcash_minorintegerRequiredInterchange less fees less principal: the network finance cash reconciliation
indexintegerRequiredinterchange_minorintegerRequiredlinesarray of objectsRequired5 child attributes
amount_minorintegerRequiredauthorization_idstringRequiredExample auth_2tVh8nqLxq4GbDe0K1F6S9zRcWm
kindstringRequiredInterchange or scheme_fee; reversal requires ReversesReference.
referencestringRequiredreverses_referencestringOptionalprincipal_minorintegerRequiredscheme_fee_minorintegerRequiredstatement_datestring · dateRequiredA business date, YYYY-MM-DD
content_sha256stringRequiredcreated_atstring · date-timeRequiredfiguresobjectRequiredSettlementFigures reconcile the file's net settlement to its categories.
16 child attributes
attributable_interchange_minorintegerRequiredattributable_scheme_fee_minorintegerRequiredcredit_minorintegerRequireddirect_interchange_minorintegerRequireddirect_journal_cash_minorintegerRequiredThe master account leg of the direct journal
direct_scheme_fee_minorintegerRequiredexternal_cash_minorintegerRequirednet_minorintegerRequiredThe categories added up: what moves the master account
network_finance_cash_minorintegerRequiredInterchange less fees the network finance cash records move
principal_minorintegerRequiredprincipal_settlement_cash_minorintegerRequiredNegative: what the principal batches move
reported_net_minorintegerRequiredThe file trailer's net settlement
return_credit_minorintegerRequiredreturn_debit_minorintegerRequiredsuspense_credit_minorintegerRequiredsuspense_debit_minorintegerRequiredfile_idstringRequiredExample achf_2tVh8nqLxq4GbDe0K1F6S9zRcWm
file_sha256stringRequiredheaderobjectRequiredHeader is a file without its records.
7 child attributes
file_referencestringRequiredformatstringRequiredinstitution_idstringRequirednetworkstringRequiredprocessing_datestring · dateRequiredA business date, YYYY-MM-DD
settlement_datestring · dateRequiredA business date, YYYY-MM-DD
totalsobjectRequiredTotals are a file's trailer control totals.
8 child attributes
credit_countintegerRequiredcredit_minorintegerRequireddebit_countintegerRequireddebit_minorintegerRequiredinterchange_minorintegerRequirednet_settlement_minorintegerRequiredSigned: positive is paid to the issuer
scheme_fee_minorintegerRequiredtransaction_countintegerRequiredidstringRequiredjournalobjectRequiredThe direct legs; effective date set at execution
18 child attributes
adjusts_periodstringOptionalA sealed period this journal corrects, YYYY-MM
approved_bystringOptionalbackdatedbooleanOptionalEffective_date is before posting_date (read only)
committed_atstring · date-timeOptionaleffective_datestring · dateRequiredA business date, YYYY-MM-DD
entriesarray of objectsRequired4 child attributes
amountintegerRequiredMinor units of the currency (cents for USD)
currency_codestringRequiredISO 4217 code
directionstringRequiredledger_account_idstringRequiredExample lacc_2tVh8nqLxq4GbDe0K1F6S9zRcWm
fx_legsarray of objectsOptionalFXLegs is read only: the legs of a cross-currency journal the ledger's own conversion and close commands posted. A caller's posting never carries them.
7 child attributes
currency_codestringRequiredequivalent_ledger_account_idstringRequiredExample lacc_2tVh8nqLxq4GbDe0K1F6S9zRcWm
native_amountintegerRequiredposition_ledger_account_idstringRequiredExample lacc_2tVh8nqLxq4GbDe0K1F6S9zRcWm
rate_sheet_idstringRequiredusd_equivalent_amountintegerRequiredusd_per_foreign_majorstringRequiredidstringOptionalkindstringRequiredposted_bystringOptionalposting_datestring · dateOptionalA business date, YYYY-MM-DD
protected_command_idstringOptionalreasonstringOptionalRequired on a backdated journal
release_hold_idstringOptionalExample hold_2tVh8nqLxq4GbDe0K1F6S9zRcWm
require_availablebooleanOptionalreversal_ofstringOptionalsource_refstringRequiredsource_servicestringRequiredordinalintegerRequiredproposed_bystringRequiredrequestobjectRequiredSettlementRequest proposes a file's settlement reconciliation.
2 child attributes
external_cashobjectRequiredExternalCash is the actual master account movement for the file's settlement: the Federal Reserve advice or statement line, positive when the network paid the bank.
4 child attributes
amount_minorinteger or nullOptionalreferencestringRequiredsha256stringRequiredvalue_datestring · dateRequiredA business date, YYYY-MM-DD
reasonstringRequiredresultobject or nullOptionalSettlementResult is what applying a settlement posted.
8 child attributes
actorstringRequiredbatch_journal_idsarray of stringsRequiredcompleted_atstring · date-timeRequiredjournal_effective_datestring · dateOptionalA business date, YYYY-MM-DD
journal_idstringOptionalExample jrnl_2tVh8nqLxq4GbDe0K1F6S9zRcWm
network_finance_cash_idsarray of stringsRequirednetwork_finance_statement_idsarray of stringsRequiredreturn_credited_exception_idsarray of stringsRequiredreviewobject or nullOptionalReview is a retained independent decision.
5 child attributes
actorstringRequiredcontent_sha256stringRequiredcreated_atstring · date-timeRequireddecisionstringRequiredreasonstringRequiredsourcesarray of objectsRequired10 child attributes
amount_minorintegerRequiredattributablebooleanRequiredInterchange and fees accrue through network finance against the clearing receipt
authorization_idstringOptionalExample auth_2tVh8nqLxq4GbDe0K1F6S9zRcWm
categorystringRequiredexception_idstringOptionalinterchange_minorintegerRequiredrecord_idstringRequiredresolution_idstringOptionalscheme_fee_minorintegerRequiredsequenceintegerRequiredErrors
Every error is a problem document with a stable code. See Errors.
400401403404409412413422424429500503