Search Payment card

POST

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

const url = 'https://api.aerandil.com/v1/object-types/hospitality.payment_card/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_card/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 tokenised card the property may draw on later — the card-on-file record behind a no-show fee, a post-departure incidental, or a check-in guarantee. Holds the PSP’s token and the fragments that identify the card to a human (scheme, last four, expiry); never a PAN. Binds to the person who holds it, or — for an OTA virtual card, which has no cardholder — to the reservation it was minted for; a pay page’s card whose payer is not the booking’s guest binds to that booking alone.

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.payment_card: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 provider provider_card_ref provider_customer_ref network_fingerprint brand last4 expiry_month expiry_year funding issuing_country capture_kind card_format wallet status stored_at last_used_at retain_until activation_date activation_at activation_charge_status activation_charge_attempts activation_charge_requested_at activation_charged_at activation_charge_refusal source cardholder_name

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_card

properties

required

object

activation_at

The instant the house's day reaches `activation_date` (its local midnight) — what the charge automation compares with the clock

string format: date-time

activation_charge_amount

Payment card activation charge amount

What the activation charge asked the card for

object

amount

required

string format: decimal

currency

required

string format: iso-4217

activation_charge_attempts

How many times the activation charge has been asked for

integer

activation_charge_refusal

Why the activation charge did not happen — the desk's to resolve

string

activation_charge_requested_at

When the activation charge was last asked for

string format: date-time

activation_charge_status

Where the activation charge stands: `requested` (the card rail has it), `charged` (the payment is on the booking's account) or `refused` (no charge, and why in `activation_charge_refusal`)

string

Allowed values: requested charged refused

activation_charged_at

When the processor took the activation charge

string format: date-time

activation_date

For a `virtual` card, the first day the channel lets the house charge it, in the house's calendar

string format: date

activation_payment_id

The payment the activation charge posted to the booking's account

string format: uuid

brand

required

Card scheme

string

Allowed values: visa mastercard amex discover diners jcb unionpay cartes_bancaires eftpos_au interac maestro unknown

capture_kind

required

How the card's details reached the PSP. Decides card-present interchange, who carries chargeback liability, and whether the cardholder's presence satisfied SCA — not a provenance note.

string

Allowed values: terminal keyed_by_staff guest_device imported

card_format

required

Whether the number belongs to a person (`physical`) or to one booking (`virtual` — an OTA-issued single-stay card).

string

Allowed values: physical virtual

cardholder_name

The payer's name as the hosted page took it, on a page's card whose payer is not the booking's guest — such a card has no cardholder person and binds to the booking alone

string

expiry_month

required

Expiry month, 1-12

integer

expiry_year

required

Expiry year, four digits

integer

funded_amount

Payment card funded amount

What the channel loaded the virtual card with — the most the house may charge it

object

amount

required

string format: decimal

currency

required

string format: iso-4217

funding

What the card draws on, as the scheme reports it. The host maps this onto `Payment.method` at posting time rather than the card carrying the ledger's word for it.

string

Allowed values: credit debit prepaid unknown

required

Card record id

string

issuing_country

Card's issuing country (ISO 3166-1 alpha-2). Drives interchange and the domestic/cross-border SCA question.

string

last4

required

Last four glyphs of the card number — the maximum fragment stored, never the full number. For a wallet card this is the device account number, not the funding card's.

string

last_used_at

When a payment was last drawn on this card. Drives the desk's ordering of a guest's cards, and the dormancy half of the retention argument.

string format: date-time

merchant_account_ref

The merchant account — the merchant of record — the card's stored-credential agreement is with: the one whose PSP Customer the card hangs off and the only one that may draw on it (2026-10-22). Absent for a card kept on the platform's own account and for a channel's virtual card.

string format: uuid

network_fingerprint

PSP-issued stable identifier for the underlying card number — the same physical card presented by two guests carries the same value. Not derivable back to a PAN, but it *is* a cross-profile card identity, so it carries the token marking: a fraud cohort is a legitimate use, a curiosity is not.

string

off_session_consent

required

True when the cardholder authenticated with the stated intent that the property may charge this card later. The SCA precondition for a no-show fee or a post-departure incidental: a card saved without it may simply be declined at the moment the guest is unreachable, so the fact is recorded at capture rather than assumed at charge time.

boolean

provider

required

PSP that holds the card (`stripe`, `adyen`). Free-form for the same reason `decision_provider` is: the set of processors is the operator's, not ours.

string

provider_card_ref

The PSP's token for this card (Stripe PaymentMethod id, Adyen recurringDetailReference). The only thing that can actually move money, and the reason this object exists — `payment_token_no_pan_shape` refuses anything Luhn-shaped here exactly as it does on `Payment.payment_method_token`.

string

provider_customer_ref

The PSP-side customer the card is attached to (Stripe Customer id). Required by the processor before a card can be charged off-session; distinct from `hospitality.person`, which is ours.

string

retain_until

required

Storage-limitation clock the pruner honours — the same discipline `guest_id_document` carries. A card kept past the purpose that justified keeping it is a finding in any PCI or GDPR review.

string format: date

source

Where the card's off-session consent was given, when narrower than its cardholder's: `guest_device_page` — on a booking's pay page, whose terms cover the bookings the card is bound to and not the cardholder's others. Unset for a card the desk, an import or a channel stored.

string

Allowed values: guest_device_page

status

required

Usability: `active`, `expired`, or `removed`. Never deleted — a card that backed a settled payment is chargeback evidence.

string

Allowed values: active expired removed

stored_at

required

When the card was recorded

string format: date-time

wallet

The wallet the card was presented through, when it was. Unset means presented directly.

string

Allowed values: apple_pay google_pay samsung_pay link click_to_pay other

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_card",
      "properties": {
        "activation_charge_status": "requested",
        "brand": "visa",
        "capture_kind": "terminal",
        "card_format": "physical",
        "funding": "credit",
        "source": "guest_device_page",
        "status": "active",
        "wallet": "apple_pay"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Validation error — unknown property or filter type mismatch.

Search Payment card

Authorizations

Request Bodyrequired

Responses

200

Example

422

Request Body^required