Record payment dispute
const url = 'https://api.aerandil.com/v1/actions/hospitality.action.record_payment_dispute/apply';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"branch":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","params":{"amount":{"amount":"example","currency":"example"},"card_brand":"example","charge_still_refundable":true,"closed_at":"2026-04-15T12:00:00Z","dispute_fee":{"amount":"example","currency":"example"},"evidence_due_by":"2026-04-15T12:00:00Z","evidence_past_due":true,"evidence_submitted_at":"2026-04-15T12:00:00Z","funds_reinstated_at":"2026-04-15T12:00:00Z","funds_withdrawn_at":"2026-04-15T12:00:00Z","has_evidence":true,"network_reason_code":"example","observed_at":"2026-04-15T12:00:00Z","opened_at":"2026-04-15T12:00:00Z","psp_dispute_reference":"example","reason":"bank_cannot_process","status":"inquiry_needs_response","submission_count":1,"visa_ce3_required_actions":["missing_customer_identifiers"],"visa_ce3_status":"requires_action"},"return_modified":false,"target":{"id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","object_type":"hospitality.payment"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.aerandil.com/v1/actions/hospitality.action.record_payment_dispute/apply \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "params": { "amount": { "amount": "example", "currency": "example" }, "card_brand": "example", "charge_still_refundable": true, "closed_at": "2026-04-15T12:00:00Z", "dispute_fee": { "amount": "example", "currency": "example" }, "evidence_due_by": "2026-04-15T12:00:00Z", "evidence_past_due": true, "evidence_submitted_at": "2026-04-15T12:00:00Z", "funds_reinstated_at": "2026-04-15T12:00:00Z", "funds_withdrawn_at": "2026-04-15T12:00:00Z", "has_evidence": true, "network_reason_code": "example", "observed_at": "2026-04-15T12:00:00Z", "opened_at": "2026-04-15T12:00:00Z", "psp_dispute_reference": "example", "reason": "bank_cannot_process", "status": "inquiry_needs_response", "submission_count": 1, "visa_ce3_required_actions": [ "missing_customer_identifiers" ], "visa_ce3_status": "requires_action" }, "return_modified": false, "target": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "object_type": "hospitality.payment" } }'Mirror a chargeback’s current state from the processor onto the payment it contests. Upserts on psp_dispute_reference: the first call mints the dispute and links it, later calls advance it, so every processor event about one case routes here and replay is a no-op. The kernel does not own this state machine. The card network decides a dispute and the processor reports it, so there is deliberately no guard on which transition is legal — lost to won really happens (Stripe’s “late win”, where an issuer moves money outside the normal lifecycle months later), and refusing it would leave the kernel insisting on a balance the bank disagrees with. What is guarded is staleness. Webhook delivery is not ordered, so observed_at is checked against the case’s last_observed_at and an older view is dropped rather than allowed to regress a decided case. Money is already gone by the time the first call lands: the network debits the disputed amount plus a non-refundable fee when the case opens. funds_reinstated_at is the only field that says it came back. A lost case reaches the ledger. On the move into lost the payment is reversed on its bill: a settled refund leg (refund_reason = chargeback_lost, capped at what the payment still has unrefunded) lands beside the original, on its folio (or the open rebate folio of a sealed one, or the booking), and the folio’s balance moves by it — the money the guest took back is owed again. Once per case. The network’s fee (dispute_fee, net of what a win returned) is recorded on the case, never on the guest’s bill: it is the merchant’s cost, and on a hotel’s own account the card rail passes it to the hotel at cost. A late win (lost to won) fails the leg and puts the balance back. An inquiry escalated to a chargeback (an inquiry state to needs_response) takes evidence again: the case records escalated_at, moves the inquiry’s evidence_submitted_at to inquiry_evidence_submitted_at and keeps the processor’s count then as inquiry_submission_count (the chargeback’s own submission is counted above it), and a packet submitted for the inquiry is kept as superseded_by_escalation. The CE 3.0 facts (card_brand, network_reason_code, visa_ce3_status, visa_ce3_required_actions) are mirrored when the view carries them.
Effects: create hospitality.payment_dispute; modify hospitality.payment_dispute; link hospitality.link.dispute_for_payment; create hospitality.payment; modify hospitality.payment; link hospitality.link.folio_has_payment; link hospitality.link.payment_refunds_payment; link hospitality.link.payment_for_reservation; modify hospitality.folio; modify hospitality.reservation; modify hospitality.dispute_evidence_packet.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
Apply against an open branch’s overlay view instead of the canonical (main) plane. The action’s writes land in the branch’s copy-on-first-write overlay, its events in the branch’s own stream, and the invocation is journaled for merge-by-replay. Branch writes are action-only, so this is the write-side entry point to a branch (POST /v1/branches forks one).
object
object
object
When true, the response carries modified_objects and modified_links projections — the engine reads the event log inside the same transaction so the projection observes the handler’s own writes.
object
Responses
Section titled “Responses”Action applied. modified_objects and modified_links populated when return_modified: true was supplied.
Envelope returned by the Aerandil action engine. correlation_id ties every event emitted by this invocation; modified_objects and modified_links project the events the handler emitted (per the action’s declared effects); warnings carries any non-blocking soft-validator observations.
object
Per-invocation correlation id; matches events.correlation_id for every event this action appended.
Links established or removed by this invocation. Empty when the caller did not request return_modified.
object
Objects created, modified, or soft-deleted by this invocation. Empty when the caller did not request return_modified.
object
Non-blocking soft-validator observations emitted during this invocation (e.g. comp-authority over-limit, recipe pour-cost over sell-price). Absent when no warnings were emitted.
object
Human-readable summary, suitable for logging or operator-UI surfacing.
Object type the warning was raised against.
Property the warning anchors to, when a single field is the locus. Absent for multi-field rules.
Stable kebab-case rule identifier (e.g. comp-authority-over-limit).
Example
{ "modified_links": [ { "kind": "linked", "link_type": "hospitality.link.dispute_for_payment" } ], "modified_objects": [ { "kind": "created", "object_type": "hospitality.payment_dispute" } ]}Conflict — concurrent modification or unique constraint violation.
Validation error — parameter validation or business-rule violation.