/v1/tenants/{tenant_id}/payment-methods/terminalAuthentication
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/terminal' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"terminal_id": "00000000-0000-4000-8000-000000000001",
"is_default": false,
"nickname": "string"
}'Parameters
tenant_idpath · stringrequiredFormat: uuid
Request body
application/json · Required
is_defaultbooleanMake this the method charged when no other is specified.
Default: false
nicknamestring | nullStaff-set label.
Max length: 100
Show nickname schema
string | nullStaff-set label.
Variant 1: string
stringVariant 2: null
nullterminal_idstringrequiredThe device that should ask for the card.
Format: uuid
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