/v1/tenants/{tenant_id}/payment-methodsAuthentication
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/tenants/<TENANT_ID>/payment-methods' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"method_type": "card",
"token": "string",
"ach_authorization": {
"captured_at": "2026-10-29T12:00:00Z",
"method": "staff_signed_form",
"version": "string"
},
"is_default": false,
"nickname": "string"
}'Parameters
tenant_idpath · stringrequiredFormat: uuid
Request body
application/json · Required
ach_authorizationAchAuthorizationRequest | nullRequired when method_type is ach; ignored for a card.
Show ach_authorization schema
AchAuthorizationRequest | nullRequired when method_type is ach; ignored for a card.
Variant 1: AchAuthorizationRequest
captured_atstringrequiredWhen the tenant authorized the debit.
Format: date-time
methodstringrequiredHow the authorization was captured: a signed form held by staff, the tenant's consent by phone to staff, or the tenant's own click-through (an integration running the tenant's own web form). The address of the request that stores it is recorded by the server.
Values: "staff_signed_form", "staff_phone", "tenant_web"
versionstringrequiredVersion of the disclosure text the tenant agreed to.
Max length: 50
Variant 2: null
nullis_defaultbooleanMake this the method charged when no other is specified.
Default: false
method_typestringrequiredWhat the token is. Must match what the processor says it is.
Values: "card", "ach"
nicknamestring | nullStaff-set label.
Max length: 100
Show nickname schema
string | nullStaff-set label.
Variant 1: string
stringVariant 2: null
nulltokenstringrequiredThe processor's payment method id.
Min length: 1 · Max length: 255
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
201Successful 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