/v1/payments/{payment_id}/voidAuthentication
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 POST \
--url 'https://api.staging.facily.ai/v1/payments/<PAYMENT_ID>/void' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"reason": "string",
"override_soft_closed": false
}'Parameters
payment_idpath · stringrequiredFormat: uuid
Request body
application/json · Required
override_soft_closedbooleanDefault: false
reasonstringrequiredMax length: 200
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": {
"allocations": [
{
"amount": "<VALUE_MATCHING_PATTERN>",
"id": "00000000-0000-4000-8000-000000000001",
"ledger_entry_id": "00000000-0000-4000-8000-000000000001",
"ledger_id": "00000000-0000-4000-8000-000000000001",
"lease": {
"id": "00000000-0000-4000-8000-000000000001",
"lease_number": "string",
"next_billing_date": "2026-10-29",
"rate": "<VALUE_MATCHING_PATTERN>",
"start_date": "2026-10-29",
"status": "string",
"tenant_id": "00000000-0000-4000-8000-000000000001",
"tenant_name": "string",
"unit_number": "string",
"insurance_plan": {
"coverage_amount": "<VALUE_MATCHING_PATTERN>",
"id": "00000000-0000-4000-8000-000000000001",
"monthly_premium": "<VALUE_MATCHING_PATTERN>",
"name": "string"
}
}
}
],
"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",
"disputes": [
{
"amount": "<VALUE_MATCHING_PATTERN>",
"created_at": "2026-10-29T12:00:00Z",
"facility_id": "00000000-0000-4000-8000-000000000001",
"id": "00000000-0000-4000-8000-000000000001",
"last_synced_at": "2026-10-29T12:00:00Z",
"opened_at": "2026-10-29T12:00:00Z",
"processor_dispute_id": "string",
"provider": "string",
"response_open": false,
"state": "open",
"status": "string",
"evidence": [
{
"created_at": "2026-10-29T12:00:00Z",
"dispute_id": "00000000-0000-4000-8000-000000000001",
"file_size_bytes": 0,
"id": "00000000-0000-4000-8000-000000000001",
"mime_type": "string",
"name": "string",
"document_id": "00000000-0000-4000-8000-000000000001",
"submitted_at": "2026-10-29T12:00:00Z"
}
]
}
]
},
"meta": {
"request_id": "string"
}
}application/json
dataPaymentDetailResponserequiredFull payment detail including allocations.
Show data schema
allocationsPaymentAllocationResponse[]requiredHow this payment was applied across ledgers. One payment may settle charges on several leases, and this shows the split.
Show allocations schema
amountstringrequiredPattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
idstringrequiredFormat: uuid
leaseLeaseCompactResponse | nullShow lease schema
LeaseCompactResponse | nullVariant 1: LeaseCompactResponse
idstringrequiredUnique identifier for the lease.
Format: uuid
insurance_planInsurancePlanCompactResponse | nullThe protection plan this lease is enrolled on, or null when the tenant carries their own policy or none.
lease_numberstringrequiredOperator-facing lease reference, unique within the facility.
next_billing_datestringrequiredBusiness date rent is next charged.
Format: date
ratestringrequiredCurrent monthly rent charged under this lease.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
start_datestringrequiredBusiness date the lease began.
Format: date
statusstringrequiredLifecycle state of the lease.
tenant_idstringrequiredThe tenant renting under this lease.
Format: uuid
tenant_namestringrequiredThe tenant's display name, denormalized so a listing needs no second call.
unit_numberstringrequiredLabel of the unit this lease occupies.
Variant 2: null
nullledger_entry_idstringrequiredFormat: uuid
ledger_idstringrequiredFormat: uuid
amountstringrequiredGross amount received.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
created_atstringrequiredWhen the payment record was created.
Format: date-time
disputesPaymentDisputeResponse[]Chargebacks and inquiries raised against this payment, oldest first. An open one is a hold: refunding a disputed payment can mean giving the money back twice.
Show disputes schema
amountstringrequiredThe amount the cardholder disputed, as the processor states it. The chargeback actually booked is this capped by what the payment still had left to give, so the two can differ.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
created_atstringrequiredWhen Facily first recorded the dispute.
Format: date-time
evidenceDisputeEvidenceResponse[] | nullThe evidence Facily sent, oldest first. Only on a single dispute; null in a list.
Show evidence schema
DisputeEvidenceResponse[] | nullThe evidence Facily sent, oldest first. Only on a single dispute; null in a list.
Variant 1: DisputeEvidenceResponse[]
created_atstringWhen it was sent to the processor.
Format: date-time
dispute_idstringFormat: uuid
document_idstring | nullThe Facily document it was sent from. Null once that document is removed.
Format: uuid
file_size_bytesintegeridstringFormat: uuid
mime_typestringnamestringsubmitted_atstring | nullWhen it was submitted for review. Submitted evidence cannot be removed.
Format: date-time
Variant 2: null
nullfacility_idstringrequiredThe facility whose payment is disputed.
Format: uuid
idstringrequiredUnique identifier for this dispute.
Format: uuid
last_synced_atstringrequiredWhen Facily last re-read this dispute from the processor.
Format: date-time
opened_atstringrequiredWhen the dispute was raised, as the processor dates it.
Format: date-time
payment_idstring | nullThe disputed payment.
Format: uuid
Show payment_id schema
string | nullThe disputed payment.
Variant 1: string
stringVariant 2: null
nullpayment_numberstring | nullThe disputed payment's operator-facing reference.
Show payment_number schema
string | nullThe disputed payment's operator-facing reference.
Variant 1: string
stringVariant 2: null
nullprocessor_dispute_idstringrequiredThe processor's own id for the dispute.
processor_transaction_idstring | nullThe disputed transaction at the processor, where the processor names one.
Show processor_transaction_id schema
string | nullThe disputed transaction at the processor, where the processor names one.
Variant 1: string
stringVariant 2: null
nullproviderstringrequiredThe processor the dispute came from, for example stax.
reasonstring | nullThe card network's reason code, for example FRAUD.
Show reason schema
string | nullThe card network's reason code, for example FRAUD.
Variant 1: string
stringVariant 2: null
nullrefund_idstring | nullThe chargeback refund a lost or accepted dispute produced. Null for an open dispute, for one resolved in the operator's favour, and for one whose payment had nothing left to give.
Format: uuid
Show refund_id schema
string | nullThe chargeback refund a lost or accepted dispute produced. Null for an open dispute, for one resolved in the operator's favour, and for one whose payment had nothing left to give.
Variant 1: string
stringVariant 2: null
nullresolved_atstring | nullWhen the dispute closed. Null while it is open.
Format: date-time
Show resolved_at schema
string | nullWhen the dispute closed. Null while it is open.
Variant 1: string
stringVariant 2: null
nullrespond_bystring | nullThe processor's evidence deadline, where it gives one.
Format: date-time
Show respond_by schema
string | nullThe processor's evidence deadline, where it gives one.
Variant 1: string
stringVariant 2: null
nullresponse_openbooleanrequiredTrue while evidence can be added, removed or submitted: open and before respond_by.
statestringrequiredWhich family the status falls in. An unrecognised status is reported as open.
Values: "open", "resolved"
statusstringrequiredThe processor's own status, verbatim: INQUIRY, OPEN, PENDING, EVIDENCE_UPLOADED, UPLOAD_FAILED, PREARBITRATION, WON, LOST or ACCEPTED. A value outside that set is possible and is treated as open.
tenant_idstring | nullThe tenant whose payment is disputed.
Format: uuid
Show tenant_id schema
string | nullThe tenant whose payment is disputed.
Variant 1: string
stringVariant 2: null
nulltenant_namestring | nullThat tenant's display name, for the queue row.
Show tenant_name schema
string | nullThat tenant's display name, for the queue row.
Variant 1: string
stringVariant 2: null
nullentry_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.
notesstring | nullFree-text notes recorded against the payment.
Show notes schema
string | nullFree-text notes recorded against the payment.
Variant 1: string
stringVariant 2: null
nullpaid_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*$
refundsPaymentRefundResponse[]Refunds issued against this payment, oldest first. Empty when none have been.
Show refunds schema
amountstringrequiredAmount returned, before any surcharge the processor gives back.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
completed_atstring | nullWhen the money actually went back out.
Format: date-time
Show completed_at schema
string | nullWhen the money actually went back out.
Variant 1: string
stringVariant 2: null
nullcreated_atstringrequiredWhen the refund was requested.
Format: date-time
effective_datestring | nullAccounting date the refund's ledger entries carry.
Format: date
Show effective_date schema
string | nullAccounting date the refund's ledger entries carry.
Variant 1: string
stringVariant 2: null
nullexternal_referencestring | nullCheck number or external reference, where one applies.
Show external_reference schema
string | nullCheck number or external reference, where one applies.
Variant 1: string
stringVariant 2: null
nullfailed_atstring | nullWhen the refund failed, if it did.
Format: date-time
Show failed_at schema
string | nullWhen the refund failed, if it did.
Variant 1: string
stringVariant 2: null
nullfailure_reasonstring | nullWhy the refund failed, in terms suitable for staff.
Show failure_reason schema
string | nullWhy the refund failed, in terms suitable for staff.
Variant 1: string
stringVariant 2: null
nullidstringrequiredUnique identifier for this refund.
Format: uuid
processor_refund_idstring | nullThe processor's own id for the returned funds.
Show processor_refund_id schema
string | nullThe processor's own id for the returned funds.
Variant 1: string
stringVariant 2: null
nullreasonstringrequiredWhy the refund was issued, in the operator's own words.
refund_tostringrequiredWhere the money went: check, external, original_method, terminal, or chargeback.
statusstringrequiredpending while the processor is deciding, then completed or failed.
surcharge_amountstringrequiredCard surcharge returned on top of amount. Never part of the ledger.
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_idstringrequired400Validation 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