/v1/tenants/{tenant_id}/paymentsAuthentication
Bearer API key or Facily session, subject to permissions and facility scope.
Authentication and scopeRequest example
Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.
curl --request GET \
--url 'https://api.staging.facily.ai/v1/tenants/<TENANT_ID>/payments' \
--header "Authorization: Bearer $FACILY_API_KEY"Try a request
Staging · read-onlyExplore your organization with a read-only request to staging.
Parameters
tenant_idpath · stringrequiredFormat: uuid
cursorquery · string | nulllimitquery · integerDefault: 50 · Minimum: 1 · Maximum: 200
pagequery · integer | null1-based page number, for a numbered pager. Mutually exclusive with `cursor`.
Minimum: 1
sortquery · string | nullValues: "paid_at", "created_at", "amount", "status"
orderquery · stringDefault: "desc" · Values: "asc", "desc"
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": [
{
"amount": "<VALUE_MATCHING_PATTERN>",
"created_at": "2026-10-29T12:00:00Z",
"facility_id": "00000000-0000-4000-8000-000000000001",
"id": "00000000-0000-4000-8000-000000000001",
"method_type": "string",
"payment_number": "string",
"processed_externally": false,
"refund_amount": "<VALUE_MATCHING_PATTERN>",
"source": "string",
"status": "string",
"entry_mode": "string",
"failed_at": "2026-10-29T12:00:00Z"
}
],
"meta": {
"request_id": "string"
},
"pagination": {
"has_more": false,
"limit": 0,
"cursor": "string",
"total_count": 0
},
"metrics": {
"cards": {},
"computed_at": "2026-10-29T12:00:00Z",
"is_stale": false,
"scope": "facility"
}
}application/json
dataPaymentResponse[]requiredShow data schema
amountstringrequiredGross amount received.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
created_atstringrequiredWhen the payment record was created.
Format: date-time
entry_modestring | nullstored, keyed, terminal, or external. Null for cash, check and money order.
Show entry_mode schema
string | nullstored, keyed, terminal, or external. Null for cash, check and money order.
Variant 1: string
stringVariant 2: null
nullfacility_idstringrequiredThe facility the payment was taken at.
Format: uuid
failed_atstring | nullWhen the payment failed, if it did.
Format: date-time
Show failed_at schema
string | nullWhen the payment failed, if it did.
Variant 1: string
stringVariant 2: null
nullfailure_reasonstring | nullWhy the payment failed, in terms suitable for showing to staff.
Show failure_reason schema
string | nullWhy the payment failed, in terms suitable for showing to staff.
Variant 1: string
stringVariant 2: null
nullidstringrequiredUnique identifier for this payment.
Format: uuid
ledger_kindstring | nullThe kind of ledger the payment is booked to: lease, counter (a walk-in sale) or lead_deposit. Null when it is not known: a payment booked to no ledger that stated no split.
Values: "lease", "counter", "lead_deposit"
Show ledger_kind schema
string | nullThe kind of ledger the payment is booked to: lease, counter (a walk-in sale) or lead_deposit. Null when it is not known: a payment booked to no ledger that stated no split.
Variant 1: string
stringValues: "lease", "counter", "lead_deposit"
Variant 2: null
nullmethod_typestringrequiredHow the money arrived: cash, check, money_order, card or ach.
paid_atstring | nullWhen the payment succeeded. Null until it does.
Format: date-time
Show paid_at schema
string | nullWhen the payment succeeded. Null until it does.
Variant 1: string
stringVariant 2: null
nullpayment_methodPaymentMethodCompactResponse | nullThe stored payment instrument used, where the payment came from one.
Show payment_method schema
PaymentMethodCompactResponse | nullThe stored payment instrument used, where the payment came from one.
Variant 1: PaymentMethodCompactResponse
card_brandstring | nullShow card_brand schema
string | nullVariant 1: string
Variant 2: null
idstringrequiredFormat: uuid
last_fourstring | nullShow last_four schema
string | nullVariant 1: string
Variant 2: null
method_typestringrequiredVariant 2: null
nullpayment_numberstringrequiredOperator-facing payment reference, unique within the facility.
processed_externallybooleanrequiredTrue when the money was captured outside Facily, on a terminal or gateway the platform does not control, and recorded here afterwards.
processor_account_idstring | nullThe merchant account this payment was charged through. Null for cash, check, money order, and payments recorded from an external terminal.
Format: uuid
Show processor_account_id schema
string | nullThe merchant account this payment was charged through. Null for cash, check, money order, and payments recorded from an external terminal.
Variant 1: string
stringVariant 2: null
nullreference_numberstring | nullThe check number or the money-order serial, without a leading '#'. Null for cash, card and ACH, and for a check recorded before Facily kept the number. Never a processor id.
Show reference_number schema
string | nullThe check number or the money-order serial, without a leading '#'. Null for cash, card and ACH, and for a check recorded before Facily kept the number. Never a processor id.
Variant 1: string
stringVariant 2: null
nullrefund_amountstringrequiredTotal refunded against this payment so far. Equal to amount when fully refunded.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
settled_atstring | nullWhen the processor confirmed funds. Null until settlement, and for cash, check and money order.
Format: date-time
Show settled_at schema
string | nullWhen the processor confirmed funds. Null until settlement, and for cash, check and money order.
Variant 1: string
stringVariant 2: null
nullsourcestringrequiredWhat initiated the payment, for example autopay, the tenant portal, or a staff member.
statusstringrequiredCurrent state, for example succeeded, pending, failed, refunded, or voided.
surcharge_amountstringProcessor card surcharge charged on top of amount; never part of the ledger.
Default: "0.00" · Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
tenantTenantCompactResponse | nullThe tenant the payment was received from. Null for a payment with no tenant: a walk-in sale or a lead's reservation deposit.
Show tenant schema
TenantCompactResponse | nullThe tenant the payment was received from. Null for a payment with no tenant: a walk-in sale or a lead's reservation deposit.
Variant 1: TenantCompactResponse
emailstring | nullPrimary email address.
Show email schema
string | nullPrimary email address.
Variant 1: string
Variant 2: null
first_namestringrequiredGiven name.
idstringrequiredUnique identifier for the tenant.
Format: uuid
last_namestringrequiredFamily name.
phonestring | nullPrimary telephone number.
Show phone schema
string | nullPrimary telephone number.
Variant 1: string
Variant 2: null
tenant_numberstringrequiredOperator-facing tenant reference, unique within the facility.
Variant 2: null
nullmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequiredmetricsEmbeddedMetrics | nullShow metrics schema
EmbeddedMetrics | nullVariant 1: EmbeddedMetrics
cardsobjectrequiredcomputed_atstring | nullrequiredFormat: date-time
Show computed_at schema
string | nullVariant 1: string
stringVariant 2: null
nullis_stalebooleanrequiredscopestringrequiredValues: "facility", "portfolio"
Variant 2: null
nullpaginationPaginationBlockrequiredPagination metadata for list responses.
Show pagination schema
cursorstring | nullShow cursor schema
string | nullVariant 1: string
stringVariant 2: null
nullhas_morebooleanrequiredlimitintegerrequiredtotal_countinteger | nullShow total_count schema
integer | nullVariant 1: integer
integerVariant 2: null
null400Validation error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired401Unauthenticated
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired403Permission denied
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired404Not found
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired409Business logic error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired503Temporary failure
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired