Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsVoid Payment
Search the full API reference Esc to close

Void Payment

Payments · REST API reference

Get support
POST/v1/payments/{payment_id}/void

Authentication

Bearer API key or Facily session, subject to permissions and facility scope.

Authentication and scope

Request 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
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
}'
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Parameters

payment_idpath · stringrequired

Format: uuid

Request body

application/json · Required

override_soft_closedboolean

Default: false

reasonstringrequired

Max length: 200

Responses

Expand a status to inspect its schema. Generated examples show structure and synthetic values.

200Successful Response
JSON · generated example
{
  "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

dataPaymentDetailResponserequired

Full payment detail including allocations.

Show data schema
allocationsPaymentAllocationResponse[]required

How this payment was applied across ledgers. One payment may settle charges on several leases, and this shows the split.

Show allocations schema
amountstringrequired

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

idstringrequired

Format: uuid

leaseLeaseCompactResponse | null
Show lease schema
LeaseCompactResponse | null
Variant 1: LeaseCompactResponse
idstringrequired

Unique identifier for the lease.

Format: uuid

insurance_planInsurancePlanCompactResponse | null

The protection plan this lease is enrolled on, or null when the tenant carries their own policy or none.

lease_numberstringrequired

Operator-facing lease reference, unique within the facility.

next_billing_datestringrequired

Business date rent is next charged.

Format: date

ratestringrequired

Current monthly rent charged under this lease.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

start_datestringrequired

Business date the lease began.

Format: date

statusstringrequired

Lifecycle state of the lease.

tenant_idstringrequired

The tenant renting under this lease.

Format: uuid

tenant_namestringrequired

The tenant's display name, denormalized so a listing needs no second call.

unit_numberstringrequired

Label of the unit this lease occupies.

Variant 2: null
null
ledger_entry_idstringrequired

Format: uuid

ledger_idstringrequired

Format: uuid

amountstringrequired

Gross amount received.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

created_atstringrequired

When 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
amountstringrequired

The 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_atstringrequired

When Facily first recorded the dispute.

Format: date-time

evidenceDisputeEvidenceResponse[] | null

The evidence Facily sent, oldest first. Only on a single dispute; null in a list.

Show evidence schema
DisputeEvidenceResponse[] | null

The evidence Facily sent, oldest first. Only on a single dispute; null in a list.

Variant 1: DisputeEvidenceResponse[]
created_atstring

When it was sent to the processor.

Format: date-time

dispute_idstring

Format: uuid

document_idstring | null

The Facily document it was sent from. Null once that document is removed.

Format: uuid

file_size_bytesinteger
idstring

Format: uuid

mime_typestring
namestring
submitted_atstring | null

When it was submitted for review. Submitted evidence cannot be removed.

Format: date-time

Variant 2: null
null
facility_idstringrequired

The facility whose payment is disputed.

Format: uuid

idstringrequired

Unique identifier for this dispute.

Format: uuid

last_synced_atstringrequired

When Facily last re-read this dispute from the processor.

Format: date-time

opened_atstringrequired

When the dispute was raised, as the processor dates it.

Format: date-time

payment_idstring | null

The disputed payment.

Format: uuid

Show payment_id schema
string | null

The disputed payment.

Variant 1: string
string
Variant 2: null
null
payment_numberstring | null

The disputed payment's operator-facing reference.

Show payment_number schema
string | null

The disputed payment's operator-facing reference.

Variant 1: string
string
Variant 2: null
null
processor_dispute_idstringrequired

The processor's own id for the dispute.

processor_transaction_idstring | null

The disputed transaction at the processor, where the processor names one.

Show processor_transaction_id schema
string | null

The disputed transaction at the processor, where the processor names one.

Variant 1: string
string
Variant 2: null
null
providerstringrequired

The processor the dispute came from, for example stax.

reasonstring | null

The card network's reason code, for example FRAUD.

Show reason schema
string | null

The card network's reason code, for example FRAUD.

Variant 1: string
string
Variant 2: null
null
refund_idstring | null

The 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 | null

The 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
string
Variant 2: null
null
resolved_atstring | null

When the dispute closed. Null while it is open.

Format: date-time

Show resolved_at schema
string | null

When the dispute closed. Null while it is open.

Variant 1: string
string
Variant 2: null
null
respond_bystring | null

The processor's evidence deadline, where it gives one.

Format: date-time

Show respond_by schema
string | null

The processor's evidence deadline, where it gives one.

Variant 1: string
string
Variant 2: null
null
response_openbooleanrequired

True while evidence can be added, removed or submitted: open and before respond_by.

statestringrequired

Which family the status falls in. An unrecognised status is reported as open.

Values: "open", "resolved"

statusstringrequired

The 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 | null

The tenant whose payment is disputed.

Format: uuid

Show tenant_id schema
string | null

The tenant whose payment is disputed.

Variant 1: string
string
Variant 2: null
null
tenant_namestring | null

That tenant's display name, for the queue row.

Show tenant_name schema
string | null

That tenant's display name, for the queue row.

Variant 1: string
string
Variant 2: null
null
entry_modestring | null

stored, keyed, terminal, or external. Null for cash, check and money order.

Show entry_mode schema
string | null

stored, keyed, terminal, or external. Null for cash, check and money order.

Variant 1: string
string
Variant 2: null
null
facility_idstringrequired

The facility the payment was taken at.

Format: uuid

failed_atstring | null

When the payment failed, if it did.

Format: date-time

Show failed_at schema
string | null

When the payment failed, if it did.

Variant 1: string
string
Variant 2: null
null
failure_reasonstring | null

Why the payment failed, in terms suitable for showing to staff.

Show failure_reason schema
string | null

Why the payment failed, in terms suitable for showing to staff.

Variant 1: string
string
Variant 2: null
null
idstringrequired

Unique identifier for this payment.

Format: uuid

ledger_kindstring | null

The 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 | null

The 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
string

Values: "lease", "counter", "lead_deposit"

Variant 2: null
null
method_typestringrequired

How the money arrived: cash, check, money_order, card or ach.

notesstring | null

Free-text notes recorded against the payment.

Show notes schema
string | null

Free-text notes recorded against the payment.

Variant 1: string
string
Variant 2: null
null
paid_atstring | null

When the payment succeeded. Null until it does.

Format: date-time

Show paid_at schema
string | null

When the payment succeeded. Null until it does.

Variant 1: string
string
Variant 2: null
null
payment_methodPaymentMethodCompactResponse | null

The stored payment instrument used, where the payment came from one.

Show payment_method schema
PaymentMethodCompactResponse | null

The stored payment instrument used, where the payment came from one.

Variant 1: PaymentMethodCompactResponse
card_brandstring | null
Show card_brand schema
string | null
Variant 1: string
Variant 2: null
idstringrequired

Format: uuid

last_fourstring | null
Show last_four schema
string | null
Variant 1: string
Variant 2: null
method_typestringrequired
Variant 2: null
null
payment_numberstringrequired

Operator-facing payment reference, unique within the facility.

processed_externallybooleanrequired

True when the money was captured outside Facily, on a terminal or gateway the platform does not control, and recorded here afterwards.

processor_account_idstring | null

The 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 | null

The merchant account this payment was charged through. Null for cash, check, money order, and payments recorded from an external terminal.

Variant 1: string
string
Variant 2: null
null
reference_numberstring | null

The 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 | null

The 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
string
Variant 2: null
null
refund_amountstringrequired

Total 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
amountstringrequired

Amount returned, before any surcharge the processor gives back.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

completed_atstring | null

When the money actually went back out.

Format: date-time

Show completed_at schema
string | null

When the money actually went back out.

Variant 1: string
string
Variant 2: null
null
created_atstringrequired

When the refund was requested.

Format: date-time

effective_datestring | null

Accounting date the refund's ledger entries carry.

Format: date

Show effective_date schema
string | null

Accounting date the refund's ledger entries carry.

Variant 1: string
string
Variant 2: null
null
external_referencestring | null

Check number or external reference, where one applies.

Show external_reference schema
string | null

Check number or external reference, where one applies.

Variant 1: string
string
Variant 2: null
null
failed_atstring | null

When the refund failed, if it did.

Format: date-time

Show failed_at schema
string | null

When the refund failed, if it did.

Variant 1: string
string
Variant 2: null
null
failure_reasonstring | null

Why the refund failed, in terms suitable for staff.

Show failure_reason schema
string | null

Why the refund failed, in terms suitable for staff.

Variant 1: string
string
Variant 2: null
null
idstringrequired

Unique identifier for this refund.

Format: uuid

processor_refund_idstring | null

The processor's own id for the returned funds.

Show processor_refund_id schema
string | null

The processor's own id for the returned funds.

Variant 1: string
string
Variant 2: null
null
reasonstringrequired

Why the refund was issued, in the operator's own words.

refund_tostringrequired

Where the money went: check, external, original_method, terminal, or chargeback.

statusstringrequired

pending while the processor is deciding, then completed or failed.

surcharge_amountstringrequired

Card surcharge returned on top of amount. Never part of the ledger.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

settled_atstring | null

When the processor confirmed funds. Null until settlement, and for cash, check and money order.

Format: date-time

Show settled_at schema
string | null

When the processor confirmed funds. Null until settlement, and for cash, check and money order.

Variant 1: string
string
Variant 2: null
null
sourcestringrequired

What initiated the payment, for example autopay, the tenant portal, or a staff member.

statusstringrequired

Current state, for example succeeded, pending, failed, refunded, or voided.

surcharge_amountstring

Processor card surcharge charged on top of amount; never part of the ledger.

Default: "0.00" · Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

tenantTenantCompactResponse | null

The 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 | null

The 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 | null

Primary email address.

Show email schema
string | null

Primary email address.

Variant 1: string
Variant 2: null
first_namestringrequired

Given name.

idstringrequired

Unique identifier for the tenant.

Format: uuid

last_namestringrequired

Family name.

phonestring | null

Primary telephone number.

Show phone schema
string | null

Primary telephone number.

Variant 1: string
Variant 2: null
tenant_numberstringrequired

Operator-facing tenant reference, unique within the facility.

Variant 2: null
null
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
400Validation error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
401Unauthenticated
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
403Permission denied
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
404Not found
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
409Business logic error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
503Temporary failure
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
Continue exploringAll payments operations
Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

Void Payment | Facily Developers