Retain customer receipt allocations against actual posted card sources

POST/cards/spend/expenses

Verified bank-bound customer PERSON identity with customer scope, session/device and online account organization membership required. Writes require authentication within five minutes; API keys, staff and service impersonation refused. Existing maker/approver/admin roles and amount limits apply. Expense review requires distinct users AND person customer IDs. Pending/approved allocations reserve exact bank-source and receipt totals; duplicate bytes cannot be relabeled. Actual unreversed committed card journals are revalidated. Pre-export coding corrections preserve source/receipt/amount. Immutable customer-expense-json-1 exports contain balanced customer-book entries, exact review/source proofs and unique expense membership. Preparation/download never claims provider delivery/import, and never posts customer expense codes to bank GLs. See services/cards/spend/README.md.

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

allocationsarray of objectsRequired

4 child attributes

amountintegerRequired

cost_centerstringRequired

external_account_codestringRequired

memostringRequired

authorization_idstringRequired

Example auth_2tVh8nqLxq4GbDe0K1F6S9zRcWm

coding_evidenceobjectRequired

2 child attributes

referencestringRequired

sha256stringRequired

reasonstringRequired

receiptobjectRequired

Receipt identity is scoped to the organization and the exact processor merchant. A source document can support several partial bank payments, but only up to its declared total. Evidence is retained customer-supplied documentation, not OCR proof.

6 child attributes

currency_codestringRequired

evidenceobjectRequired

2 child attributes

referencestringRequired

sha256stringRequired

external_referencestringRequired

issued_datestring · dateRequired

A business date, YYYY-MM-DD

merchant_idstringRequired

total_amountintegerRequired

replaces_expense_idstringOptional

settlement_account_codestringRequired

Returns

200 OK

amountintegerRequired

content_sha256stringRequired

created_atstring · date-timeRequired

export_idstringOptional

idstringRequired

replaced_by_expense_idstringOptional

requestobjectRequired

7 child attributes

allocationsarray of objectsRequired

4 child attributes

amountintegerRequired

cost_centerstringRequired

external_account_codestringRequired

memostringRequired

authorization_idstringRequired

Example auth_2tVh8nqLxq4GbDe0K1F6S9zRcWm

coding_evidenceobjectRequired

2 child attributes

referencestringRequired

sha256stringRequired

reasonstringRequired

receiptobjectRequired

6 child attributes

currency_codestringRequired

evidenceobjectRequired

2 child attributes

referencestringRequired

sha256stringRequired

external_referencestringRequired

issued_datestring · dateRequired

A business date, YYYY-MM-DD

merchant_idstringRequired

total_amountintegerRequired

replaces_expense_idstringOptional

settlement_account_codestringRequired

reviewobject or nullOptional

6 child attributes

approvebooleanRequired

atstring · date-timeRequired

authorityobjectRequired

Authority is the observed current organization membership and separately bank- verified person identity. Neither the request body nor a receipt supplies it.

12 child attributes

account_idstringRequired

Example acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm

device_sha256stringRequired

membership_changed_bystringRequired

membership_updated_atstring · date-timeRequired

observed_atstring · date-timeRequired

organization_customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

payment_limit_amountintegerRequired

person_customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

rolestringRequired

session_sha256stringRequired

step_up_atstring · date-timeRequired

user_idstringRequired

Example user_2tVh8nqLxq4GbDe0K1F6S9zRcWm

content_sha256stringRequired

evidenceobjectRequired

2 child attributes

referencestringRequired

sha256stringRequired

reasonstringRequired

sourceobjectRequired

15 child attributes

account_idstringRequired

Example acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm

amountintegerRequired

authorization_idstringRequired

Example auth_2tVh8nqLxq4GbDe0K1F6S9zRcWm

card_idstringRequired

Example card_2tVh8nqLxq4GbDe0K1F6S9zRcWm

card_kindstringRequired

currency_codestringRequired

journalobjectRequired

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

journal_keystringRequired

journal_sha256stringRequired

kindstringRequired

Purchase or refund, derived from actual bank source

merchant_idstringRequired

merchant_namestringRequired

network_referencestringRequired

organization_customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

original_authorization_idstringOptional

Example auth_2tVh8nqLxq4GbDe0K1F6S9zRcWm

submitted_byobjectRequired

Authority is the observed current organization membership and separately bank- verified person identity. Neither the request body nor a receipt supplies it.

12 child attributes

account_idstringRequired

Example acct_2tVh8nqLxq4GbDe0K1F6S9zRcWm

device_sha256stringRequired

membership_changed_bystringRequired

membership_updated_atstring · date-timeRequired

observed_atstring · date-timeRequired

organization_customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

payment_limit_amountintegerRequired

person_customer_idstringRequired

Example cust_2tVh8nqLxq4GbDe0K1F6S9zRcWm

rolestringRequired

session_sha256stringRequired

step_up_atstring · date-timeRequired

user_idstringRequired

Example user_2tVh8nqLxq4GbDe0K1F6S9zRcWm

Errors

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

400401403404409412413422424429500503