Read Payment card

GET

/v1/object-types/hospitality.payment_card/objects/{id}

const url = 'https://api.aerandil.com/v1/object-types/hospitality.payment_card/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.aerandil.com/v1/object-types/hospitality.payment_card/objects/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Read an existing instance.

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

Parameters

Path Parameters

required

string format: uuid

Object id (UUID v7, server-generated at create time).

Query Parameters

branch

string format: uuid

Read through an open branch’s copy-on-first-write overlay view instead of the canonical (main) plane. Does not compose with as_of (422). The branch must exist under the caller’s tenant.

Responses

200

Object found.

application/json

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

Example

{
  "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"
  }
}

Headers

ETag

string

/^"\d+"$/

Quoted strong validator (RFC 7232 §2.3) carrying the object’s monotonic version. Informational on the read path — object mutation goes through typed actions on /v1/actions/{action}/apply, not raw CRUD.

404

No object with that id (or soft-deleted).