Skip to content
aerandil.com
GitHub

Search Payment request

POST
/v1/object-types/hospitality.payment_request/search
curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.payment_request/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.

The house asking a guest for money against one booking, with a pay link (Mews’s payment request): an amount, a reason (deposit, prepayment, fee, a missing or declined card), a kind (payment takes the money, preauthorization places a hold captured later) and a required expires_at. pending until the guest pays on the card rail’s hosted page (completed, with the payment it produced), the house withdraws it (cancelled, only from pending) or the night audit finds it past expires_at (expired). A completed payment lands on the booking’s own account through record_deposit_payment, so the deposit engine’s status ladder moves; a completed preauthorization is the authorise path’s pending payment. Money that moves after a request was cancelled or expired is still recorded — the request completes late — because a ledger that refuses a settled payment disagrees with the processor.

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 reason kind status expires_at requested_at note pay_url psp_link_reference completed_at cancelled_at cancellation_reason expired_at guest_notified_at guest_notice_note refusal_notice_at refusal_notice_note reauthorised_at reauthorisation_count reauthorisation_refused_at reauthorisation_refusal reuse_terms authentication_for stuck_psp_reference authentication_detail authentication_due_by authentication_reminders authentication_reminders_sent authentication_next_chase_at authentication_overdue_at authentication_page_declined_at authentication_page_decline authentication_resent_at authentication_page_overpaid_at authentication_page_overpaid_reference authentication_page_refund_reference authentication_page_overpaid_detail

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_request
properties
required
object
amount
required
Payment request amount

What the guest is asked to pay (or to have held)

object
amount
required
string format: decimal
currency
required
string format: iso-4217
authentication_detail
The issuer's or the processor's words for the demand
string
authentication_due_by
The house's deadline for the guest to confirm (`set_sca_chase`); past it, the house is told
string format: date-time
authentication_for
What the off-session attempt the issuer wants confirmed was for
string
Allowed values: no_show_fee post_stay_collection hold_replacement hold_top_up cancellation_fee
authentication_next_chase_at
When the card rail next looks at the chase — the next reminder, else the deadline; cleared once the deadline has passed
string format: date-time
authentication_overdue_at
When the deadline passed with the guest not done and the house was told
string format: date-time
authentication_page_decline
The processor's words for the decline on the page — the chase stays pending
string
authentication_page_declined_at
When the guest's card was last declined on the page
string format: date-time
authentication_page_overpaid_at
When the chase's page was paid after what it asked for had been taken another way — the page's payment has no ledger home
string format: date-time
authentication_page_overpaid_detail
Why the page's payment had no home, and whether it was given back or is left for a person
string
authentication_page_overpaid_reference
The processor's intent the overpaid page took
string
authentication_page_refund_reference
The processor's refund that gave the overpaid page's money back
string
authentication_reminders
How many reminders the house sends before the deadline
integer
authentication_reminders_sent
How many reminders have been taken so far
integer
authentication_resent_at
When the desk last re-sent the chase's page (one re-send per ten minutes)
string format: date-time
authentication_stay_ref
The departed stay whose late charges the guest is asked to confirm
string format: uuid
cancellation_reason
Why the house withdrew it
string
cancelled_at
When the house withdrew it
string format: date-time
completed_at
When the processor settled it
string format: date-time
completed_late
True when the money arrived after the request was cancelled or had expired — recorded, and worth the desk's look
boolean
expired_at
When the night audit expired it
string format: date-time
expires_at
required
When the request lapses; the night audit closing on or after this instant's date expires it while it is still pending
string format: date-time
guest_notice_note
Why the pay link was not sent to the guest, when it was not
string
guest_notice_ref
The outbound message that carries the pay link to the guest
string format: uuid
guest_notified_at
When the pay link was queued for the guest
string format: date-time
id
required
Payment request id
string
kind
required
`payment` takes the money; `preauthorization` holds it for capture later
string
Allowed values: payment preauthorization
note
What the guest reads beside the amount (the pay page's line item)
string
page_fee_ceiling
Payment request page fee ceiling

The application_fee_amount the card rail set on the hosted page when it minted it, in the request’s currency: the account’s dearest card class online, because a Payment Link’s fee is fixed before any card exists. When the page completes the rail reads the card it was paid with and refunds the difference to that card’s own class to the hotel, recording the outcome on the payment (record_page_fee). Absent when the page settles to the platform’s own account (no fee) or was minted before the ceiling.

object
amount
required
string format: decimal
currency
required
string format: iso-4217
pay_url
The card rail's hosted page the guest pays on — absent until the rail has minted it
string
payment_id
The payment the completed request produced
string format: uuid
psp_link_reference
The processor's handle on the hosted page (a Stripe Payment Link id), so the rail can switch it off when the request ends
string
reason
required
Why the house is asking
string
Allowed values: deposit prepayment fee payment_card_missing payment_card_declined authentication_required
reauthorisation_count
How many times the hold has been re-placed
integer
reauthorisation_refusal
Why the hold could not be re-placed (no stored card, a decline) — it lapses at the issuer, and the desk takes a new guarantee
string
reauthorisation_refused_at
When the card rail last tried to re-place the hold and could not
string format: date-time
reauthorised_at
When the card rail last re-placed the hold before the issuer lapsed it
string format: date-time
refusal_notice_at
When the guest was queued a message that their card was not accepted
string format: date-time
refusal_notice_note
Why the guest was not told their card was not accepted, when they were not
string
refusal_notice_ref
The outbound message that tells the guest their card was not accepted
string format: uuid
refusal_signal_ref
The network's answer that refused the hold the guest's card placed on the pay page
string format: uuid
requested_at
required
When the house asked
string format: date-time
reuse_terms
The card terms the pay page showed the guest — what they agreed to when the page saved their card for later charges by the house
string
status
required
pending → completed / cancelled / expired
string
Allowed values: pending completed cancelled expired
stuck_psp_reference
The processor's intent the issuer refused to complete without the cardholder (a Stripe PaymentIntent left `requires_payment_method`); cancelled once the page is paid
string
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_request",
      "properties": {
        "authentication_for": "no_show_fee",
        "kind": "payment",
        "reason": "deposit",
        "status": "pending"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Section titled “422”

Validation error — unknown property or filter type mismatch.