Search Payment

POST

/v1/object-types/hospitality.payment/search

const url = 'https://api.aerandil.com/v1/object-types/hospitality.payment/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"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"}'
};

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/object-types/hospitality.payment/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 payment applied to a folio. Settles charges. Refunds are recorded as a separate negative-amount Payment row linked to the original settled payment via payment_refunds_payment and carrying payment_kind = refund per proposal 0019. The original settled Payment row stays immutable — status = settled is the evidence that money was captured, and partial-refund / multiple-refund state is derived from the linked refund legs rather than by rewriting the source row.

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.payment:read

Request Body^required

application/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 method received_at reference status decision_provider decision_provider_case_id liability_shift_basis authentication_outcome sca_exemption_claimed review_state authorisation_expires_at auth_correlation_id payment_method_token captured_at voided_at void_reason void_note psp_capture_reference psp_void_reference acquirer_reference_number payment_kind refund_requested_at refund_resolved_at refund_reason refund_note refund_correlation_id psp_refund_reference refund_trace_reference refund_trace_reference_type refund_failure_reason external_ref hold_decision hold_decided_at hold_kept_until hold_outcome hold_outcome_detail hold_purpose fee_class fee_true_up fee_true_up_reference fee_true_up_detail fraud_warning_reference fraud_warning_at fraud_warning_type fraud_warning_observed_at fraud_warning_response fraud_warning_stay_phase fraud_warning_detail

Responses

200

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

application/json

object

data

required

Array<object>

object

created_at

required

string format: date-time

required

string format: uuid

object_type

required

Allowed value: hospitality.payment

properties

required

object

acquirer_reference_number

23-digit ARN (Acquirer Reference Number) assigned post-clearing. The cross-network join key for chargeback investigation; load-bearing at dispute time. Often unavailable at capture time (lands hours later via PSP reconciliation report); populated as a follow-up enrichment when present. Mastercard Banknet Reference and Visa Transaction Identifier (TID, DE 62.2) network references are deferred to a structured sub-object per proposal 0018 §10.2.

string

amount

required

Payment amount

Amount

object

amount

required

string format: decimal

currency

required

string format: iso-4217

auth_correlation_id

Host's PSP authorisation reference (Stripe payment_intent_id, Adyen pspReference, Worldpay transactionReference). Per-payment join key for reconciling PSP-side records with the Aerandil audit trail.

string

authentication_outcome

EMV 3DS 2.2 authentication result on this authorisation. `pending_decoupled` covers the EMVCo 2.2 decoupled async flow (up to 7 days for the result to land).

string

Allowed values: frictionless challenge_passed challenge_failed attempted pending_decoupled not_applicable

authorisation_expires_at

Scheme's authorisation-validity window (Visa 30 days for MCC 3501-7011 lodging, Mastercard 7 days final auth / 30 days pre-auth, Amex 7 days). Set by the host at authorisation time per their PSP integration; `authorisation_expiry_beyond_scheme_window` soft-warns at > 30 days.

string format: date-time

captured_at

Wall-clock timestamp when the capture transitioned `status = pending → settled` via `capture_authorised_charge`. Distinct from `received_at` (set at authorisation time). Null for rows that reached `settled` via the direct-settle `apply_payment` path or historical rows pre-dating proposal 0018.

string format: date-time

card_present

Whether the payment was priced as card-present (a terminal) rather than online

boolean

decision_provider

Fraud-decision vendor (denormalised from the gating assessment's vendor_id; cohort key for chargeback-rate analytics per fraud-vendor)

string

decision_provider_case_id

Vendor's case / decision identifier (Stripe Radar evaluation id, Adyen case ref, Riskified decision id, Forter forterDecisionId, Signifyd case id, Sift event id, Kount tran id). The chargeback-dispute exhibit pointer.

string

external_ref

Source-system key for connector-landed payments

string

fee_class

The card's class the platform's fee was priced by — `domestic_standard`, `domestic_premium`, `regional` or `international`, read from the card's issuing country against the account's

string

Allowed values: domestic_standard domestic_premium regional international

fee_true_up

How the page's fee came out

Set by record_page_fee on a payment a hosted page took: refunded (the difference to the card’s own class was refunded), not_due (nothing to give back), refused (the processor refused the refund; the hotel paid the ceiling, fee_true_up_detail says why, and the operator’s variance shows it). Absent on every other payment.

string

Allowed values: refunded not_due refused

fee_true_up_detail

The processor's words for a refused fee refund

string

fee_true_up_reference

The processor's refund of the platform's fee

The processor’s id for the application-fee refund the page’s true-up made (Stripe fr_…).

string

fraud_warning_actionable

Whether the processor still calls the warning actionable — not yet disputed and not refunded in full

boolean

fraud_warning_at

When the issuer's early fraud warning was raised

Set when an issuer flags this payment as suspected fraud (an early fraud warning: Visa’s TC40, Mastercard’s SAFE report). About 40% of Visa and Mastercard warnings become fraud disputes when the charge is not refunded, and Visa’s VAMP counts the warning itself whatever happens next. Absent on a payment no issuer has flagged.

string format: date-time

fraud_warning_detail

Why the card rail responded as it did, in words

string

fraud_warning_observed_at

The processor's time of the latest report about the warning on file — the watermark an out-of-order report is checked against

string format: date-time

fraud_warning_reference

The processor's id for the issuer's early fraud warning

Stripe’s issfr_… for the early fraud warning an issuer raised on this payment’s charge — the join key for every later report about the same warning.

string

fraud_warning_response

What the card rail did about the warning

Decided once, from the stay, when the warning first arrives: hold_voided (an uncaptured hold released before capture — the cardholder cannot dispute it), refunded (a captured line after the stay at or under the house’s ceiling, refunded in full), desk_review (a deposit before arrival, a stay in house, a line above the ceiling, or a release or refund the ledger refused — a person decides), not_actionable (already disputed or refunded, or nothing left to act on).

string

Allowed values: hold_voided refunded desk_review not_actionable

fraud_warning_stay_phase

Where the booking stood when the warning arrived

string

Allowed values: before_arrival in_house ended no_booking

fraud_warning_type

The kind of fraud the issuer labelled

string

Allowed values: card_never_received fraudulent_card_application made_with_counterfeit_card made_with_lost_card made_with_stolen_card misc unauthorized_use_of_card

hold_decided_at

When check-out decided this hold

string format: date-time

hold_decision

What check-out decided for this hold

Set on a pending card hold when its stay checks out: release (the card rail voids it), capture (the bill still owed money — the rail takes that from the hold, which lets the rest go), or keep (the house’s post-stay window is on; the hold stays for charges found after departure until hold_kept_until). Absent on a hold no departure has decided.

string

Allowed values: release capture keep

hold_kept_until

Until when a kept hold is kept for post-stay charges

string format: date-time

hold_outcome

What became of a decided hold at the processor: released, captured, lapsed, or unresolved (still pending; the desk settles it)

string

Allowed values: released captured lapsed unresolved

hold_outcome_detail

The processor's words when a hold's outcome is unresolved

string

hold_purpose

Why this hold was placed

Set on a card hold when it is placed: booking (the guarantee before arrival — the pay page’s hold, or a desk hold on the booking’s own account), check_in (the desk’s hold on the stay’s folio), top_up, re_placement (the card rail renewing a booking hold before the issuer lapses it), incidentals, no_show, post_stay, or other. A hold carried from the booking onto the stay at check-in keeps booking. Absent on a payment taken in one step.

string

Allowed values: booking check_in top_up re_placement incidentals no_show post_stay other

required

Payment id

string

liability_shift_basis

Why a chargeback would shift away from the merchant. Per-decision, not per-vendor.

string

Allowed values: three_ds2_authenticated provider_guarantee none

method

required

Method

string

Allowed values: cash credit_card debit_card bank_transfer voucher loyalty_points direct_billing mobile_wallet ota_collected other

net_to_hotel

Payment net to hotel

What the transfer to the hotel carried less the application fee the platform took back, net of any transfer reversal or fee refund a refund made — the platform’s balance transactions for the payment, folded by record_processor_fee. Equals the hotel’s own payout line for the charge (amount less fee). Chargeback movements are the case’s (platform_dispute_cost), not counted here.

object

amount

required

string format: decimal

currency

required

string format: iso-4217

payment_kind

Ledger-leg discriminator. `payment` is the original payment authorisation / settlement; `deposit` is a pre-arrival payment taken by `record_deposit_payment` (a refund settling against it is recorded on the booking as deposit returned); `refund` is a negative-amount leg created by `refund_payment` and linked to the original via `payment_refunds_payment`. Unset legacy rows are interpreted as `payment` by handler-level coherence rules. The companion `void_authorisation` action (proposal 0018) is gated to `payment_kind = payment` rows by the `void_requires_payment_kind_payment` validator so refund legs resolve through `resolve_payment_refund` instead.

string

Allowed values: payment deposit refund

payment_method_token

PSP-issued opaque token referencing the cardholder data in the operator's PSP / vault. Must NOT be a Luhn-passing 13-19-digit sequence — `payment_token_no_pan_shape` hard validator enforces PCI-DSS 4.0 (PAN never enters Aerandil).

string

platform_fee

Payment platform fee

The platform’s fee on this card payment as the account’s fee schedule priced it for the card’s class (fee_class, card_present) — the processor’s application_fee_amount, set when the money was taken, on what was taken. Absent on a payment that settled to the platform’s own account.

object

amount

required

string format: decimal

currency

required

string format: iso-4217

platform_fee_refunded

Payment platform fee refunded

What of the platform’s fee the card rail refunded to the hotel when the hosted page this payment came from completed: the link fixed its fee at the account’s dearest card class (payment_request.page_fee_ceiling), and the difference to the class of the card the guest paid with went back as an application-fee refund. platform_fee is what the platform kept. Zero when nothing was due or the refund was refused (fee_true_up). In the payment’s currency.

object

amount

required

string format: decimal

currency

required

string format: iso-4217

processor_fee

Payment processor fee

Stripe’s actual processing fee on the payment’s charge, read off the platform’s balance transaction for it (its fee; a partial capture’s reversal line counted in) by record_processor_fee. On a destination charge the fee is the platform’s, recouped through the application fee — processor_fee beside processor_fee_estimate is the variance the pricing decision reports per account per month; the hotel is never trued up. In the platform’s balance currency.

object

amount

required

string format: decimal

currency

required

string format: iso-4217

processor_fee_estimate

Payment processor fee estimate

The processor’s published rate for the card’s class on what was taken (its conversion fee added when the charge’s currency is not the schedule’s) — the estimate processor_fee is read back against. In the charge’s currency.

object

amount

required

string format: decimal

currency

required

string format: iso-4217

psp_capture_reference

PSP-issued reference to the capture leg, distinct from the auth's `auth_correlation_id`. Stripe `latest_charge.id`; Adyen `/captures` response `pspReference` (a new pspRef distinct from the auth pspRef); Checkout.com `action_id`; Cybersource capture `id`. Per-payment join key for reconciliation with PSP-side records.

string

psp_refund_reference

PSP-issued refund reference: Stripe `refund.id`, Adyen refund response `pspReference` (a new pspRef distinct from the capture pspRef), Checkout.com refund `action_id`, Worldpay refund event link / reference, Braintree refund transaction id, Cybersource credit id, Mews `RefundId`. Per-leg join key for reconciliation with PSP-side refund records; may be unavailable at request time and populated later by `resolve_payment_refund`.

string

psp_void_reference

PSP-issued reference to the void / cancel / reversal leg. Stripe PaymentIntent state-transition event id; Adyen `/cancels` or `/reversals` response `pspReference`; Checkout.com `action_id`.

string

received_at

required

Received at

string format: date-time

reference

Reference

string

refund_correlation_id

Host-side idempotency / reconciliation key for the refund request. Required by `refund_payment` because two legitimate same-amount partial refunds with the same reason can occur against one payment — amount + reason alone cannot key the idempotency cache. If the PSP refund reference is already known synchronously, the host may reuse it here; otherwise the host generates a stable correlation id and stores the later `psp_refund_reference` on resolution.

string

refund_failure_reason

PSP / network reason for a failed or voided refund leg (e.g. `declined`, `insufficient_funds`, closed account, processor settlement decline, operator cancellation). Required at the handler level when `resolve_payment_refund(refund_status = failed)`; optional otherwise. Free-form because PSPs do not converge on a closed taxonomy of refund-failure codes — Stripe, Adyen, Braintree, and Cybersource each expose their own error vocabulary that the host typically pastes through verbatim.

string

refund_note

Free-form human-readable colour on a refund leg, complementing the closed `refund_reason` enum. Required when `refund_reason = other`; optional otherwise. Capped at 1024 characters at the handler level.

string

refund_reason

Closed reason taxonomy on a refund leg. Stripe / Adyen canonical three (`duplicate`, `fraudulent`, `requested_by_customer`) plus nine Aerandil-domain hospitality reasons (`reservation_cancelled`, `deposit_return`, `service_recovery`, `overcharge_correction`, `no_show_policy_exception`, `package_component_refund`, `membership_cancellation`, `chargeback_prevention`, `other`), and `chargeback_lost` — the leg `record_payment_dispute` writes when a chargeback is lost, which `refund_payment` never accepts. Required at the handler level for `refund_payment`; optional on the property because third-party importers may write refund rows without one. `other` requires `refund_note` per the `refund_other_requires_note` validator.

string

Allowed values: duplicate fraudulent requested_by_customer reservation_cancelled deposit_return service_recovery overcharge_correction no_show_policy_exception package_component_refund membership_cancellation chargeback_prevention other chargeback_lost

refund_requested_at

Timestamp when the host recorded the refund request / PSP accepted the refund request. For refund rows, the required `received_at` mirrors this timestamp so legacy ledger queries that group by `received_at` continue to work without per-leg date logic.

string format: date-time

refund_resolved_at

Timestamp when the refund leg reached a terminal outcome (`status = refunded`, `failed`, or `voided`). Null while the leg is `pending`. Populated by `resolve_payment_refund`, or by `refund_payment` when `refund_initial_status = refunded` for a synchronously-confirmed refund.

string format: date-time

refund_trace_reference

Downstream trace reference the cardholder can take to their bank when the refund is not visible on the card. Stripe documents ARN / STAN / RRN for this purpose; often lands days after the refund request via PSP reconciliation. Typed by `refund_trace_reference_type` so the operator knows which network reference to quote — Visa ARN, network STAN, network RRN, or a PSP-internal trace handle.

string

refund_trace_reference_type

Type tag on `refund_trace_reference`. `arn` (23-digit Acquirer Reference Number); `stan` (System Trace Audit Number); `rrn` (Retrieval Reference Number); `psp_generated` (PSP-internal handle when the network reference is not yet exposed); `unavailable` (same-day reversals and pre-clearing refunds may have no traceable network reference at all). Kept separate from 0018's `acquirer_reference_number` because refund reversals can lack an ARN while still having STAN / RRN evidence; `refund_trace_reference_type_coherence` enforces the reference / type pairing.

string

Allowed values: arn stan rrn psp_generated unavailable

review_state

Post-network review-hold state. `not_required` for direct-capture flows; `held` for manual_capture_after_review with a held_for_review outcome; `approved` / `declined` / `expired` are terminal states transitioned atomically by the `capture_authorised_charge` and `void_authorisation` companion actions (proposals 0017 §6.2 and 0018 §6).

string

Allowed values: not_required held approved declined expired

sca_exemption_claimed

PSD2 SCA exemption claimed by the host at authorisation time. The PSP is the source of truth on whether the exemption was actually granted; Aerandil records the claim plus the amount-ceiling sanity validators.

string

Allowed values: none low_value tra mit trusted_beneficiary secure_corporate

status

required

Status

string

Allowed values: pending settled refunded voided failed

void_note

Free-form human-readable colour on a voided payment, complementing the closed `void_reason` enum. Mirrors Adyen's open `reference` field pattern. Capped at 1024 characters at the handler level.

string

void_reason

Closed reason taxonomy on a voided payment. Stripe-aligned canonical four (`duplicate`, `fraudulent`, `requested_by_customer`, `abandoned`) plus Aerandil-domain hospitality four (`review_declined`, `authorisation_expired`, `reservation_cancelled`, `guest_disputed_pre_arrival`). Required at the handler level for `void_authorisation`; optional on the property because third-party importers may write voided rows without one. PSP-side capture-failure events (Adyen `CAPTURE_FAILED`, Checkout.com capture-declined) are deliberately excluded — see proposal 0018 §1 and §10.1.

string

Allowed values: duplicate fraudulent requested_by_customer abandoned review_declined authorisation_expired reservation_cancelled guest_disputed_pre_arrival released_at_departure

voided_at

Wall-clock timestamp when the void transitioned `status = pending → voided` via `void_authorisation`. Populated by the void handler; null otherwise.

string format: date-time

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",
      "properties": {
        "authentication_outcome": "frictionless",
        "fee_class": "domestic_standard",
        "fee_true_up": "refunded",
        "fraud_warning_response": "hold_voided",
        "fraud_warning_stay_phase": "before_arrival",
        "fraud_warning_type": "card_never_received",
        "hold_decision": "release",
        "hold_outcome": "released",
        "hold_purpose": "booking",
        "liability_shift_basis": "three_ds2_authenticated",
        "method": "cash",
        "payment_kind": "payment",
        "refund_reason": "duplicate",
        "refund_trace_reference_type": "arn",
        "review_state": "not_required",
        "sca_exemption_claimed": "none",
        "status": "pending",
        "void_reason": "duplicate"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Validation error — unknown property or filter type mismatch.

Search Payment

Authorizations

Request Bodyrequired

Responses

200

Example

422

Request Body^required