/v1/payment-methods/{payment_method_id}Authentication
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 PATCH \
--url 'https://api.staging.facily.ai/v1/payment-methods/<PAYMENT_METHOD_ID>' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"billing_address": {
"city": "string",
"line1": "string",
"state": "st",
"zip": "string",
"country": "US",
"line2": "string"
},
"card_exp_month": 0,
"card_exp_year": 2000,
"is_active": false,
"is_default": false,
"nickname": "string"
}'Parameters
payment_method_idpath · stringrequiredFormat: uuid
Request body
application/json · Required
billing_addressBillingAddressRequest | nullThe card's billing address, sent to the processor. Facily does not store it.
Show billing_address schema
BillingAddressRequest | nullThe card's billing address, sent to the processor. Facily does not store it.
Variant 1: BillingAddressRequest
citystringrequiredMin length: 1 · Max length: 100
countrystringTwo-letter country code.
Default: "US" · Min length: 2 · Max length: 2
line1stringrequiredMin length: 1 · Max length: 255
line2string | nullMax length: 255
Show line2 schema
string | nullVariant 1: string
stringVariant 2: null
nullstatestringrequiredTwo-letter state code.
Min length: 2 · Max length: 2
zipstringrequiredMin length: 3 · Max length: 10
Variant 2: null
nullcard_exp_monthinteger | nullNew expiry month, 1 to 12. Sent with card_exp_year; a card only.
Show card_exp_month schema
integer | nullNew expiry month, 1 to 12. Sent with card_exp_year; a card only.
Variant 1: integer
integerVariant 2: null
nullcard_exp_yearinteger | nullNew expiry year, four digits. Not in the past.
Minimum: 2000 · Maximum: 2099
Show card_exp_year schema
integer | nullNew expiry year, four digits. Not in the past.
Variant 1: integer
integerVariant 2: null
nullis_activeboolean | nullFalse stops the method being offered or charged.
Show is_active schema
boolean | nullFalse stops the method being offered or charged.
Variant 1: boolean
booleanVariant 2: null
nullis_defaultboolean | nullTrue clears the tenant's previous default.
Show is_default schema
boolean | nullTrue clears the tenant's previous default.
Variant 1: boolean
booleanVariant 2: null
nullnicknamestring | nullStaff-set label. An empty string clears it.
Max length: 100
Show nickname schema
string | nullStaff-set label. An empty string clears it.
Variant 1: string
stringVariant 2: null
nullResponses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": {
"added_via": "string",
"created_at": "2026-10-29T12:00:00Z",
"id": "00000000-0000-4000-8000-000000000001",
"is_active": false,
"is_chargeable": false,
"is_default": false,
"method_type": "string",
"provider": "string",
"updated_at": "2026-10-29T12:00:00Z",
"ach_account_type": "string",
"ach_bank_name": "string",
"bank_holder_type": "string"
},
"meta": {
"request_id": "string"
}
}application/json
dataPaymentMethodResponserequiredShow data schema
ach_account_typestring | nullWhether the ACH account is checking or savings.
Show ach_account_type schema
string | nullWhether the ACH account is checking or savings.
Variant 1: string
stringVariant 2: null
nullach_bank_namestring | nullName of the bank holding the account, for an ACH method.
Show ach_bank_name schema
string | nullName of the bank holding the account, for an ACH method.
Variant 1: string
stringVariant 2: null
nulladded_viastringrequiredHow the method was stored, for example by the tenant in the portal or by staff.
bank_holder_typestring | nullWhether the bank account belongs to a person or a business, as the processor classifies it. Null for a card, and for a bank account stored before Facily recorded it.
Show bank_holder_type schema
string | nullWhether the bank account belongs to a person or a business, as the processor classifies it. Null for a card, and for a bank account stored before Facily recorded it.
Variant 1: string
stringVariant 2: null
nullbin_typestring | nullCREDIT, DEBIT, or PREPAID as the processor reports it. Drives surcharging.
Show bin_type schema
string | nullCREDIT, DEBIT, or PREPAID as the processor reports it. Drives surcharging.
Variant 1: string
stringVariant 2: null
nullcard_brandstring | nullCard network, for example Visa or Mastercard.
Show card_brand schema
string | nullCard network, for example Visa or Mastercard.
Variant 1: string
stringVariant 2: null
nullcard_exp_monthinteger | nullCard expiry month, 1 to 12.
Show card_exp_month schema
integer | nullCard expiry month, 1 to 12.
Variant 1: integer
integerVariant 2: null
nullcard_exp_yearinteger | nullCard expiry year, four digits.
Show card_exp_year schema
integer | nullCard expiry year, four digits.
Variant 1: integer
integerVariant 2: null
nullcreated_atstringrequiredWhen the method was stored.
Format: date-time
idstringrequiredUnique identifier for this stored payment method.
Format: uuid
is_activebooleanrequiredWhether the method may currently be charged.
is_chargeablebooleanrequiredTrue when this method can actually be charged: a live, non-deleted token at the current processor. A migrated legacy row is false.
is_defaultbooleanrequiredTrue for the method charged when no other is specified.
last_fourstring | nullLast four digits of the card or bank account, for identifying it to the tenant. No other digits are ever stored or returned.
Show last_four schema
string | nullLast four digits of the card or bank account, for identifying it to the tenant. No other digits are ever stored or returned.
Variant 1: string
stringVariant 2: null
nullmethod_typestringrequiredThe instrument type, for example card or ACH.
nicknamestring | nullStaff-set label, for telling two cards on file apart.
Show nickname schema
string | nullStaff-set label, for telling two cards on file apart.
Variant 1: string
stringVariant 2: null
nullproviderstringrequiredWho holds the token: stax for a chargeable method, legacy for a method migrated from the previous system whose token has not yet been imported.
updated_atstringrequiredWhen the method was last modified.
Format: date-time
metaMetarequiredEnvelope 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