Match a bank deposit to a customer payment receipt
accounting:writeAtomically links an inbound bank transaction to an order_payments receipt
by setting bank_transactions.matched_order_payment_id and flipping
reconciliation_status to 'matched'.
No GL postings occur. The GL entry (DR Bank / CR AR) was posted when the payment receipt was recorded. This operation records only the reconciliation link for the bank statement.
Guards enforced:
- Transaction must be inbound (
direction='in'or NULL); outbound transactions use the AP-side matcher instead. - Transaction must not already be matched to a customer payment.
- Payment status must be
posted,partial_refund, orsucceeded. - Entity isolation: bank transaction and order payment must belong to the same entity as the API key.
Amount warning: If the absolute difference between the bank transaction
amount and the payment amount exceeds $0.05, amount_warning is populated
in the response (non-blocking, for operator awareness).
A.2 Multi-invoice payments: Payments where order_id IS NULL (applied
across multiple invoices) are fully supported as match targets.
Idempotency: Matching an already-matched transaction to the same payment
is a no-op returning the same matched: true response.
Authorizations
API key issued per entity via Settings > Developers > API Keys.
Each key carries scopes (e.g. orders:read, products:write).
Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.
Path Parameters
Body
Response
Matched successfully

