Corgi BankDocumentation
OpenAPI

Propose a clearing file's settlement reconciliation to the master account movement

POST/cards/clearing/files/{id}/settlements

Verified 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

idstringRequired

Headers

Idempotency-KeystringRequired

Send 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_cashobjectRequired

ExternalCash 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 nullOptional
referencestringRequired
sha256stringRequired
value_datestring · dateRequired

A business date, YYYY-MM-DD

reasonstringRequired

Returns

200 OK

chunksarray of objectsRequired
9 child attributes
authorization_idsarray of stringsRequired
batch_keystringRequired
cash_minorintegerRequired

Interchange less fees less principal: the network finance cash reconciliation

indexintegerRequired
interchange_minorintegerRequired
linesarray of objectsRequired
5 child attributes
amount_minorintegerRequired
authorization_idstringRequired

Example auth_2tVh8nqLxq4GbDe0K1F6S9zRcWm

kindstringRequired

Interchange or scheme_fee; reversal requires ReversesReference.

referencestringRequired
reverses_referencestringOptional
principal_minorintegerRequired
scheme_fee_minorintegerRequired
statement_datestring · dateRequired

A business date, YYYY-MM-DD

content_sha256stringRequired
created_atstring · date-timeRequired
figuresobjectRequired

SettlementFigures reconcile the file's net settlement to its categories.

16 child attributes
attributable_interchange_minorintegerRequired
attributable_scheme_fee_minorintegerRequired
credit_minorintegerRequired
direct_interchange_minorintegerRequired
direct_journal_cash_minorintegerRequired

The master account leg of the direct journal

direct_scheme_fee_minorintegerRequired
external_cash_minorintegerRequired
net_minorintegerRequired

The categories added up: what moves the master account

network_finance_cash_minorintegerRequired

Interchange less fees the network finance cash records move

principal_minorintegerRequired
principal_settlement_cash_minorintegerRequired

Negative: what the principal batches move

reported_net_minorintegerRequired

The file trailer's net settlement

return_credit_minorintegerRequired
return_debit_minorintegerRequired
suspense_credit_minorintegerRequired
suspense_debit_minorintegerRequired
file_idstringRequired

Example achf_2tVh8nqLxq4GbDe0K1F6S9zRcWm

file_sha256stringRequired
headerobjectRequired

Header is a file without its records.

7 child attributes
file_referencestringRequired
formatstringRequired
institution_idstringRequired
networkstringRequired
processing_datestring · dateRequired

A business date, YYYY-MM-DD

settlement_datestring · dateRequired

A business date, YYYY-MM-DD

totalsobjectRequired

Totals are a file's trailer control totals.

8 child attributes
credit_countintegerRequired
credit_minorintegerRequired
debit_countintegerRequired
debit_minorintegerRequired
interchange_minorintegerRequired
net_settlement_minorintegerRequired

Signed: positive is paid to the issuer

scheme_fee_minorintegerRequired
transaction_countintegerRequired
idstringRequired
journalobjectRequired

The direct legs; effective date set at execution

18 child attributes
adjusts_periodstringOptional

A sealed period this journal corrects, YYYY-MM

approved_bystringOptional
backdatedbooleanOptional

Effective_date is before posting_date (read only)

committed_atstring · date-timeOptional
effective_datestring · dateRequired

A business date, YYYY-MM-DD

entriesarray of objectsRequired
4 child attributes
amountintegerRequired

Minor units of the currency (cents for USD)

currency_codestringRequired

ISO 4217 code

directionstringRequired
ledger_account_idstringRequired

Example lacc_2tVh8nqLxq4GbDe0K1F6S9zRcWm

fx_legsarray of objectsOptional

FXLegs 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_codestringRequired
equivalent_ledger_account_idstringRequired

Example lacc_2tVh8nqLxq4GbDe0K1F6S9zRcWm

native_amountintegerRequired
position_ledger_account_idstringRequired

Example lacc_2tVh8nqLxq4GbDe0K1F6S9zRcWm

rate_sheet_idstringRequired
usd_equivalent_amountintegerRequired
usd_per_foreign_majorstringRequired
idstringOptional
kindstringRequired
posted_bystringOptional
posting_datestring · dateOptional

A business date, YYYY-MM-DD

protected_command_idstringOptional
reasonstringOptional

Required on a backdated journal

release_hold_idstringOptional

Example hold_2tVh8nqLxq4GbDe0K1F6S9zRcWm

require_availablebooleanOptional
reversal_ofstringOptional
source_refstringRequired
source_servicestringRequired
ordinalintegerRequired
proposed_bystringRequired
requestobjectRequired

SettlementRequest proposes a file's settlement reconciliation.

2 child attributes
external_cashobjectRequired

ExternalCash 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 nullOptional
referencestringRequired
sha256stringRequired
value_datestring · dateRequired

A business date, YYYY-MM-DD

reasonstringRequired
resultobject or nullOptional

SettlementResult is what applying a settlement posted.

8 child attributes
actorstringRequired
batch_journal_idsarray of stringsRequired
completed_atstring · date-timeRequired
journal_effective_datestring · dateOptional

A business date, YYYY-MM-DD

journal_idstringOptional

Example jrnl_2tVh8nqLxq4GbDe0K1F6S9zRcWm

network_finance_cash_idsarray of stringsRequired
network_finance_statement_idsarray of stringsRequired
return_credited_exception_idsarray of stringsRequired
reviewobject or nullOptional

Review is a retained independent decision.

5 child attributes
actorstringRequired
content_sha256stringRequired
created_atstring · date-timeRequired
decisionstringRequired
reasonstringRequired
sourcesarray of objectsRequired
10 child attributes
amount_minorintegerRequired
attributablebooleanRequired

Interchange and fees accrue through network finance against the clearing receipt

authorization_idstringOptional

Example auth_2tVh8nqLxq4GbDe0K1F6S9zRcWm

categorystringRequired
exception_idstringOptional
interchange_minorintegerRequired
record_idstringRequired
resolution_idstringOptional
scheme_fee_minorintegerRequired
sequenceintegerRequired

Errors

Every error is a problem document with a stable code. See Errors.

400401403404409412413422424429500503

to move to open esc to close