Skip to content
aerandil.com
GitHub

Search Payment dispute

POST
/v1/object-types/hospitality.payment_dispute/search
curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.payment_dispute/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "cursor": "example", "filters": [ { "property": "id", "type": "eq", "value": "example" } ], "limit": 1, "order": "asc", "property_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope": { "level": "tenant" }, "sort_by": "created_at" }'

Search for instances. Filters eq, contains, gte and lte AND-compose; or / not are additive follow-ups. Pages with an opaque cursor; the +1 fetch returns has_more without a second round-trip. Ordered by sort_by (default created_at) in order (default ascending), id breaking ties; rows with no value for a property key sort last.

A chargeback or pre-dispute inquiry raised against a settled payment. Mirrored from the processor, which mirrors the card network — the kernel never decides a dispute’s state, it records one. The money moves at opened_at (withdrawn) and again at closed_at if the case is won; between those the funds are held by the network and the payment cannot be refunded outside the dispute process.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
branch

Optional open-branch id. Search composes that branch’s copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.

string format: uuid
cursor

Opaque cursor from a prior response’s next_cursor. Pass back verbatim; do not introspect.

string
filters

Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by limit.

Array
One of:
object
property
required
Allowed value: id
type
required
Allowed value: eq
value
required
string
limit

Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).

integer
>= 1 <= 500
order

Direction of sort_by: asc (oldest / smallest first) or desc. A cursor is bound to the sort_by and order it was minted under; another pair is refused (422).

string
default: asc
Allowed values: asc desc
property_id

The house a desk stands in: keeps this property’s rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house’s — the meaning property_id has on the event tail.

string format: uuid
scope
One of: discriminator: level
object
level
required
string
Allowed value: tenant
Allowed values: tenant
sort_by

What the page is ordered by: the row’s created_at or updated_at, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).

string
default: created_at
Allowed values: created_at updated_at id psp_dispute_reference status reason opened_at evidence_due_by evidence_submitted_at submission_count funds_withdrawn_at funds_reinstated_at closed_at last_observed_at dispute_fee_recovery dispute_fee_recovery_detail evidence_packet_version evidence_file_count evidence_refusal evidence_refused_at dispute_fee_attempts dispute_fee_attempt_open_at dispute_fee_last_attempt_at dispute_fee_written_off_at evidence_sending_at recovery_reversal_reference hotel_reinstatement hotel_reinstated_at reinstatement_transfer_reference hotel_reinstatement_code hotel_reinstatement_detail card_brand network_reason_code visa_ce3_status escalated_at inquiry_submission_count inquiry_evidence_submitted_at dispute_fee_review_reference dispute_fee_reviewed_at dispute_fee_reviewed_by dispute_fee_review_note hotel_reinstatement_settlement hotel_reinstatement_settled_by hotel_reinstatement_note waiver_decided_at waiver_refusal waiver_refusal_condition waiver_radar_risk_level waiver_chargebacks_in_year waiver_charges_in_year waiver_ratio_charge_floor waiver_cap_cases waiver_cap_case_floor dispute_fee_waived_at

Responses

Section titled “Responses”

200

Section titled “200”

Search results, ordered by (sort_by, id) in the requested order (ascending by default).

Media typeapplication/json
object
data
required
Array<object>
object
created_at
required
string format: date-time
id
required
string format: uuid
object_type
required
Allowed value: hospitality.payment_dispute
properties
required
object
amount
required
Payment dispute amount

Disputed amount

object
amount
required
string format: decimal
currency
required
string format: iso-4217
card_brand
The disputed card's brand as the processor reports it on the case (Stripe `payment_method_details.card.brand`) — what the evidence's page limit is read by when the payment names no stored card
string
charge_still_refundable
Whether the disputed payment can still be refunded. False for most open chargebacks: refunding outside the dispute process is blocked, and doing it anyway pays the cardholder twice.
boolean
closed_at
Closed at
string format: date-time
dispute_fee
Payment dispute dispute fee

What the processor charged for the case, net of any fee it returned — Stripe’s dispute fee, read off the dispute’s balance transactions (the countered fee comes back on a win; the received fee never does). On a hotel’s own account it is passed to the hotel at cost when the case is lost — its own transfer reversal beside the disputed amount, and what the transfer cannot carry debited from the hotel’s Stripe balance; dispute_fee_recovered says what was. On the platform’s, it stays the platform’s.

object
amount
required
string format: decimal
currency
required
string format: iso-4217
dispute_fee_attempt_open_at
Set while a retry is open — written before the processor is asked, cleared when its outcome is recorded; an open retry is asked again under the same key
string format: date-time
dispute_fee_attempts
How many retries of an owed dispute fee the card rail has opened (the debit at the chargeback's close is not counted)
integer
dispute_fee_last_attempt_at
When the card rail last retried the owed fee
string format: date-time
dispute_fee_owed
Payment dispute dispute fee owed

What of the dispute fee could not be taken yet — present only while some is owed

object
amount
required
string format: decimal
currency
required
string format: iso-4217
dispute_fee_recovered
Payment dispute dispute fee recovered

What of the dispute fee the hotel was charged: off its transfer and debited from its Stripe balance

object
amount
required
string format: decimal
currency
required
string format: iso-4217
dispute_fee_recovery
recovered, owed, other_currency (never converted by guesswork), written_off (the platform carries it after the last retry), needs_review (a retry whose outcome could not be read back from the processor: parked for a person, never retried blind), or returned (the case was won after it was lost: the fee is no longer the hotel's, and what it paid goes back with the disputed amount — see `hotel_reinstatement`), or waived (move 12: the case was certified for the dispute-fee waiver when its evidence was submitted, so the platform did not pass the network's fees through — `dispute_fee_waived`; never a payment to the hotel)
string
Allowed values: recovered owed other_currency written_off needs_review returned waived
dispute_fee_recovery_detail
Stripe's words for why the rest was not taken
string
dispute_fee_review_note
What the person who settled the parked fee found
string
dispute_fee_review_reference
The processor's debit a person found when settling a fee the card rail parked for review (Stripe `py_…`)
string
dispute_fee_reviewed_at
When a person settled the fee the card rail had parked for review
string format: date-time
dispute_fee_reviewed_by
Who settled the parked fee (the principal)
string
dispute_fee_waived
Payment dispute dispute fee waived

What of the network’s fees the platform did not pass to the hotel on a certified case it lost — both fees, received and countered. Never paid to the hotel: the platform declined to recover it

object
amount
required
string format: decimal
currency
required
string format: iso-4217
dispute_fee_waived_at
When the certified case was lost and its fees waived — the rolling year of the cap is counted on it
string format: date-time
dispute_fee_written_off
Payment dispute dispute fee written off

What of the dispute fee was still owed after the last retry and is carried by the platform

object
amount
required
string format: decimal
currency
required
string format: iso-4217
dispute_fee_written_off_at
When the owed fee was written off
string format: date-time
escalated_at
When the processor reported the inquiry escalated to a chargeback after the house had answered it — the inquiry's submission no longer counts against the chargeback's one
string format: date-time
evidence_due_by
Evidence due by — the issuer's deadline, typically 7 to 21 days. Missing it loses the case by default.
string format: date-time
evidence_file_count
How many files the submission attached
integer
evidence_files
Payment dispute evidence files

The files the submission attached, one per evidence type, as the processor’s file ids (Stripe file_…, uploaded with purpose dispute_evidence)

Array<object>
object
evidence_type
required
string
Allowed values: receipt service_documentation cancellation_policy customer_signature duplicate_charge_documentation customer_communication uncategorized_file
file_id
required
string
evidence_packet_version
Which assembly of the evidence packet was submitted (`dispute_evidence_packet.packet_version`)
integer
evidence_past_due
Whether the last submission reached the processor after the deadline — its delivery to the issuer is then not guaranteed (Stripe's `evidence_details.past_due`)
boolean
evidence_refusal
The processor's words for the last submission it refused — cleared by a submission it took
string
evidence_refused_at
When the processor refused the last submission
string format: date-time
evidence_sending_at
Set while an evidence packet's dispute update is on its way to the processor — written before it is sent, cleared when the processor's answer is recorded. Set without `evidence_submitted_at`, the processor may already hold the evidence: submitting again finishes that packet (the same files, the same key) and records its answer
string format: date-time
evidence_submitted_at
Evidence submitted at
string format: date-time
funds_reinstated_at
Funds reinstated at — set only when the case is won, and the one field that says the money actually came back rather than the paperwork merely closing.
string format: date-time
funds_withdrawn_at
Funds withdrawn at
string format: date-time
has_evidence
Whether the processor holds evidence for the case (Stripe's `evidence_details.has_evidence`: staged or submitted)
boolean
hotel_reinstated
Payment dispute hotel reinstated

What goes back to the hotel after a late win — the disputed amount the loss pulled back plus the dispute fee passed on to it

object
amount
required
string format: decimal
currency
required
string format: iso-4217
hotel_reinstated_at
When the transfer giving the hotel its money back was made — for a late win settled by hand, when the operator recorded it
string format: date-time
hotel_reinstated_fee
Payment dispute hotel reinstated fee

Of hotel_reinstated, the dispute fee the hotel had been charged

object
amount
required
string format: decimal
currency
required
string format: iso-4217
hotel_reinstated_less_platform_fee
Payment dispute hotel reinstated less platform fee

What was netted out of hotel_reinstated: the platform’s application fee the processor refunded to the hotel with the loss’s reversal (read off the processor’s fee refunds, never the ledger). The hotel already had it back, so the late win returns the reversal net of it and the hotel ends where it was before the dispute — the charge less the platform’s fee

object
amount
required
string format: decimal
currency
required
string format: iso-4217
hotel_reinstatement
After a late win (the case lost, then won): transferred (the hotel was given back the amount pulled from it and the fee it was charged, in one transfer) or pending_operator (the processor refused the transfer, or the fee's outcome could not be read back: the operator moves the money, and the card rail does not ask again) or settled_by_operator (the operator recorded what they did about it — `hotel_reinstatement_settlement`)
string
Allowed values: transferred pending_operator settled_by_operator
hotel_reinstatement_code
The processor's error code for a transfer it refused (Stripe's `error.code`), when the late win is left for the operator
string
hotel_reinstatement_detail
The processor's words for a transfer it refused, when the late win is left for the operator
string
hotel_reinstatement_note
The operator's words on how a late win left for them was settled — required for a write-off
string
hotel_reinstatement_settled_by
Who recorded the settlement of a late win left for the operator (the principal)
string
hotel_reinstatement_settlement
When a late win the card rail could not give back was settled by the operator (`hotel_reinstatement = settled_by_operator`): transferred_by_hand (they paid the hotel what the case owed, outside the rail) or written_off (some or none of it went back; the rest is not owed, for the reason in the note)
string
Allowed values: transferred_by_hand written_off
hotel_reinstatement_written_off
Payment dispute hotel reinstatement written off

Of what a late win left for the operator owed the hotel, what the operator wrote off rather than paid — hotel_reinstated is what did go back

object
amount
required
string format: decimal
currency
required
string format: iso-4217
id
required
Dispute record id
string
inquiry_evidence_submitted_at
When the house's evidence answered the inquiry, kept when the case escalated and its evidence clock started again
string format: date-time
inquiry_submission_count
The processor's submission count when the inquiry escalated; the chargeback's own submission is counted above it
integer
last_observed_at
required
When the processor last said this was the case's state. Webhook delivery is not ordered, so this is the watermark a mirror is checked against: an older view of the case is dropped rather than allowed to regress a decided one.
string format: date-time
network_reason_code
The card network's own reason code for the case (Stripe `payment_method_details.card.network_reason_code`; Visa `10.4` is card-absent fraud, the code Compelling Evidence 3.0 answers)
string
opened_at
required
Opened at
string format: date-time
platform_dispute_cost
Payment dispute platform dispute cost

The net of every platform balance transaction for the case — the network’s withdrawal of the amount and its fee, a reinstatement on a win, what the card rail recovered from the hotel (the amount’s reversal, the fee’s reversal or debit), money returned to the hotel after a late win — negated, so a cost is positive and a case fully passed through is zero. Written by record_platform_dispute_cost from the case’s platform lines. The received fee Stripe never returns is what a won case leaves here.

object
amount
required
string format: decimal
currency
required
string format: iso-4217
psp_dispute_reference
The processor's own id for the case — Stripe `du_…`, Adyen dispute `pspReference`. The join key for every later event about this dispute, and the only handle that survives into a representment.
string
reason
required
Reason
string
Allowed values: bank_cannot_process check_returned credit_not_processed customer_initiated debit_not_authorized duplicate fraudulent general incorrect_account_details insufficient_funds noncompliant product_not_received product_unacceptable subscription_canceled unrecognized
recovery_reversal_reference
The processor's transfer reversal that pulled the lost case's disputed amount back off the hotel's transfer (Stripe `trr_…`, tagged `aerandil_dispute`)
string
reinstatement_transfer_reference
The processor's transfer that gave the hotel its money back (Stripe `tr_…`, tagged `aerandil_late_win`) — or, settled by hand, the operator's own transfer or payout (`tr_…` / `po_…`)
string
status
required
Status
string
Allowed values: inquiry_needs_response inquiry_under_review inquiry_closed needs_response under_review won lost prevented
submission_count
How many times evidence has been submitted
integer
visa_ce3_required_actions
What the processor says the case still lacks to qualify for Visa Compelling Evidence 3.0 (Stripe's `required_actions`, verbatim)
Array<string>
Allowed values: missing_customer_identifiers missing_disputed_transaction_description missing_merchandise_or_services missing_prior_undisputed_transaction_description missing_prior_undisputed_transactions
visa_ce3_status
The processor's Visa Compelling Evidence 3.0 status for the case (Stripe `evidence_details.enhanced_eligibility.visa_compelling_evidence_3.status`): requires_action, qualified (the processor's own prior transactions already qualify — the packet leaves them alone), or not_qualified (after a submission: sent as standard evidence)
string
Allowed values: requires_action qualified not_qualified
waiver_cap_case_floor
The cap's floor in cases: under it a case is covered whatever the account's fees and its own, from its first live month
integer
waiver_cap_cases
How many of the account's cases had taken the cap when this one was certified: waived in the rolling year, or certified and still open
integer
waiver_cap_limit
Payment dispute waiver cap limit

The account’s waiver cap when the case was certified: 25% of the platform fees it paid over the rolling year, net of fees refunded. A case is covered while its own two fees fit under it beside what is taken (waiver_cap_used + 2 × the fee received ≤ the cap), or while fewer cases than the floor of five (waiver_cap_case_floor) have taken it, whatever the fees

object
amount
required
string format: decimal
currency
required
string format: iso-4217
waiver_cap_used
Payment dispute waiver cap used

What of the account’s waiver cap was taken when the case was certified: the fees waived on its cases lost in the rolling year, plus the fees withdrawn so far on its certified cases still open — in the currency of the case’s fee

object
amount
required
string format: decimal
currency
required
string format: iso-4217
waiver_certified
Whether the case was certified for the dispute-fee waiver when its evidence was submitted: if it is lost, neither of the network's fees is passed to the hotel. Decided from facts the kernel holds — the packet went without gaps and on time, the reason is one the packet defends, the card was not keyed by hand, Radar rated the payment normal and the desk did not proceed past an elevated rating, the account's chargebacks are under 0.5% of its charges, and the cap has headroom. Cleared when an inquiry escalates (the chargeback is certified at its own submission)
boolean
waiver_chargebacks_in_year
The account's chargebacks opened in the rolling year the certification counted (this case included; inquiries are not chargebacks)
integer
waiver_charges_in_year
The account's charges in the rolling year the certification counted — the platform fees Stripe collected on them (`platform_earning` lines)
integer
waiver_decided_at
When the waiver was decided — the submission the certification was stamped with
string format: date-time
waiver_pledged
Payment dispute waiver pledged

What a certified case holds of the account’s waiver cap while it is open: both of the network’s fees as priced at certification — twice the fee Stripe took when the case was received, or twice the last received fee seen at the account when the case carried none. Absent on a case not covered

object
amount
required
string format: decimal
currency
required
string format: iso-4217
waiver_radar_risk_level
Stripe Radar's rating of the disputed payment at authorisation, as the certification read it (`outcome.risk_level`, verbatim: normal, elevated, highest, not_assessed, unknown) — Stripe's own word, read off the disputed intent's latest charge at certification; never the kernel's assessment
string
waiver_ratio_charge_floor
The charges the rolling year must hold before the chargeback ratio is weighed (1,000): under it, as `waiver_charges_in_year` shows, the ratio was not weighed and cannot be the condition missed
integer
waiver_refusal
Why the case is not covered, in words: the first condition it did not meet
string
waiver_refusal_condition
Which condition the case did not meet first (`WAIVER_REFUSALS`)
string
Allowed values: evidence_gaps submitted_late reason_not_defended hand_keyed card_unknown radar_not_normal radar_unknown radar_unread elevated_rating_overridden no_merchant_account dispute_ratio cap_exhausted
provenance

Per-property source attribution and pins. An entry under properties means the property’s current value came from that source (on the source’s own clock, source_updated_at); an entry under pins is a human override protecting the property from sourced writes.

object
pins
object
key
additional properties
object
pinned_at
string format: date-time
pinned_by
object
reason
required
string
properties
object
key
additional properties
object
external_id
string
recorded_at
required
string format: date-time
source
required
string
source_updated_at
string format: date-time
stream
string
scope
required
One of: discriminator: level
object
level
required
string
Allowed value: tenant
Allowed values: tenant
tenant_id
required
string format: uuid
updated_at
required
string format: date-time
version
required
integer
>= 1
has_more
required
boolean
next_cursor

Cursor for the next page; omitted when the result set is exhausted.

string
Example
{
  "data": [
    {
      "object_type": "hospitality.payment_dispute",
      "properties": {
        "dispute_fee_recovery": "recovered",
        "evidence_files": [
          {
            "evidence_type": "receipt"
          }
        ],
        "hotel_reinstatement": "transferred",
        "hotel_reinstatement_settlement": "transferred_by_hand",
        "reason": "bank_cannot_process",
        "status": "inquiry_needs_response",
        "visa_ce3_required_actions": [
          "missing_customer_identifiers"
        ],
        "visa_ce3_status": "requires_action",
        "waiver_refusal_condition": "evidence_gaps"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Section titled “422”

Validation error — unknown property or filter type mismatch.