Skip to content
aerandil.com
GitHub

Search Merchant account

POST
/v1/object-types/hospitality.merchant_account/search
curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.merchant_account/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 property’s own account at the payment processor, opened under the platform’s (Stripe Connect). While one is active, the property’s card payments settle to it — the hotel is the merchant the guest’s statement names, its payouts go to its own bank — and the platform’s fee is taken from each payment. A property with no open account takes card payments on the platform’s own account. Verification is the processor’s: the account is onboarding until the hotel has submitted its details, then active or restricted as the processor decides.

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 status provider provider_account_ref country disabled_reason fee_conversion_bps opened_at state_observed_at closed_at external_account_disabled_reason external_account_observed_at rejected_at onboarding_link_nonce_hash onboarding_link_expires_at payout_interval payout_delay_days payout_anchor payout_schedule_changed_at payout_interval_before payout_delay_days_before payout_anchor_before cards_exported_at cards_exported_count

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.merchant_account
properties
required
object
cards_exported_at
When the platform operator last pulled this account's stored cards for the hotel's next processor (the Leaving policy's card export)
string format: date-time
cards_exported_count
How many stored cards that export carried — the cards that name this account, are active and are on the processor
integer
charges_enabled
required
Whether the processor lets the account take card payments
boolean
closed_at
When the account was closed
string format: date-time
country
required
Country the hotel trades in (ISO 3166-1 alpha-2) — fixed at opening, because the processor fixes it too
string
details_submitted
required
Whether the hotel has finished the processor's onboarding form
boolean
disabled_reason
The processor's reason the account cannot take charges, when it gives one
string
external_account_disabled
Whether the processor has disabled the bank account it pays out to (after a failed payout); no payout lands until the hotel replaces it
boolean
external_account_disabled_ids
The processor's ids of the default bank accounts it has disabled (`ba_…`, one per currency at most); `external_account_disabled` is whether there are any
Array<string>
external_account_disabled_reason
The processor's status for that bank account (`errored`, `verification_failed`) when it is disabled
string
external_account_observed_at
When the bank account's state was read — the watermark an out-of-order webhook is checked against
string format: date-time
fee_conversion_bps
required
The processor's currency-conversion fee in basis points (Stripe: 2%), counted in the estimate of the processor's fee on a charge in a currency other than the schedule's
integer
fee_schedule
required
Merchant account fee schedule

The platform’s fee on each card payment settled to this account, by the card’s class: one row for each of domestic_standard, domestic_premium, regional and international, online and card-present — the basis points and fixed fee the hotel pays (bps, fixed) beside the processor’s own published rate for that class (processor_bps, processor_fixed), which is what the platform’s estimate of the processor’s fee uses. Taken when the money is captured, on the amount captured, rounded down. The fixed fees’ currency is the schedule’s: a charge in another currency carries no fixed fee.

Array<object>
object
bps
required
integer
card_present
required
boolean
fee_class
required
string
Allowed values: domestic_standard domestic_premium regional international
fixed
required
object
amount
required
string format: decimal
currency
required
string format: iso-4217
processor_bps
required
integer
processor_fixed
required
object
amount
required
string format: decimal
currency
required
string format: iso-4217
id
required
Merchant account id
string
onboarding_link_expires_at
When the hotel's current onboarding refresh link stops working
string format: date-time
onboarding_link_nonce_hash
SHA-256 of the one-use secret in the hotel's current onboarding refresh link — the link that mints a fresh Stripe onboarding link without a sign-in
string
opened_at
required
When the account was opened
string format: date-time
payout_anchor
The day a weekly payout goes (`monday` … `sunday`) or a monthly one (its day of the month, `1` … `31`); absent for daily and manual payouts
string
payout_anchor_before
The weekly or monthly anchor before the last change, if it had one
string
payout_delay_days
How many days the processor holds a payment before it can be paid out (Stripe's `delay_days`; calendar or business days by the account's country)
integer
payout_delay_days_before
The payout delay before the last change, if it had one
integer
payout_interval
How often the processor pays the balance out, in its own words (Stripe: `daily`, `weekly`, `monthly`, or `manual` — paid out only on request)
string
payout_interval_before
The payout interval before the last change, if it had one
string
payout_schedule_changed_at
When the processor last changed this account's payout schedule (the first schedule read is a report, not a change)
string format: date-time
payouts_enabled
required
Whether the processor will pay the account's balance out to the hotel's bank
boolean
provider
required
Processor that holds the account (`stripe`)
string
provider_account_ref
required
The processor's id for the account (Stripe `acct_…`). An identifier, not a credential: nothing can be done with it without the platform's own key.
string
rejected_at
When the processor accepted the platform's rejection of a closed account — the end of its life there, which the processor admits only at a zero balance
string format: date-time
requirements_due
What the processor still needs from the hotel, in its own vocabulary (`external_account`, `individual.verification.document`, …). Empty when nothing is owed.
Array<string>
state_observed_at
When the processor's view below was taken — the watermark an out-of-order webhook is checked against
string format: date-time
status
required
Lifecycle status, derived from the processor's verification
string
Allowed values: onboarding active restricted closed
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.merchant_account",
      "properties": {
        "fee_schedule": [
          {
            "fee_class": "domestic_standard"
          }
        ],
        "status": "onboarding"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Section titled “422”

Validation error — unknown property or filter type mismatch.