Card Tokenization API Overview

This endpoint is used to tokenize (securely save) a customer's card details for future transactions.
Tokenization allows you to charge the card later without needing to handle sensitive card data again. The
result of a successful tokenization is a token (or identifier) that represents the card in the Facilero platform.

1. Create Token

Endpoint

Live

POST https://live.facilero.com/api/v1/payments/card/tokenize

Sandbox

POST https://sandbox.facilero.com/api/v1/payments/card/tokenize

Request Headers

Content-Type: application/json
Authorization: Bearer <AUTH_TOKEN>

Request Body DTO

Field	Type	Required	Description
`requestId`	String	Yes	Unique identifier for this tokenization request.
`merchantId`	Long	Yes	Merchant ID. The token will be associated with this merchant for billing and ownership tracking.
`socialSecurityNumber`	String	No	Customer’s SSN for enhanced KYC (nullable).
`card`	Object (Card)	Yes	Card details to vault. See Card-Sale API’s Card Object (`number`, `expMonth`, `expYear`, `cvv`).
`billingDetails`	Object (BillingDetails)	Yes	Customer billing/KYC info. Mirrors Card-Sale API’s BillingDetails fields.
`metadata`	Map<String, String>	No	Optional free-form key/value map for your internal reference.
`expirationDate`	String (YYYY-MM-DD)	No	ISO-8601 date. Optional token expiry. If omitted, token will expire 5 years from creation.

Example Request Body

{
  "requestId":             "req-token-123",
  "merchantId":            644947533589431519,
  "socialSecurityNumber":  null,
  "card": {
    "number":   "4111111111111111",
    "expMonth": "12",
    "expYear":  "2028",
    "cvv":      "123"
  },
  "billingDetails": {
    "externalUserId": "cust-789",
    "firstName":      "Jane",
    "lastName":       "Doe",
    "address1":       "123 Main St",
    "city":           "Dublin",
    "state":          "Leinster",
    "country":        "IE",
    "postalCode":     "D01X0F5",
    "phone":          "+353851234567",
    "email":          "[email protected]",
    "dateOfBirth":    "1990-05-20"
  },
  "metadata": {
    "customerId":    "cust-789"
  },
  "expirationDate":       "2028-07-14"
}

Response Body DTO

Field	Type	Description
`token`	String	Secure reference for the vaulted card (e.g. `tok_abc123xyz`).
`cardMask`	String	Masked PAN for display/logging (e.g. `411111******1111`).
`expirationMonth`	String	Card expiration month (MM).
`expirationYear`	String	Card expiration year (YYYY).
`cardBrand`	String (nullable)	Card scheme brand (e.g. `VISA`, `MASTERCARD`).
`cardType`	String (nullable)	BIN-derived card type: `DEBIT` or `CREDIT`.
`issuingBank`	String (nullable)	Name of the issuing bank as returned by BIN lookup.
`cardCountry`	String (nullable)	ISO-2 country code of the card’s BIN (e.g. `IE`).
`expirationDate`	String (YYYY-MM-DD)	Date when this token expires (5-year default if not set).
`metadata`	Map<String, String>	(nullable) Echo of your free-form metadata map.

Note: Tokenization is a synchronous card-vaulting operation — no 3DS authentication, no callbacks, no redirects. The token is returned immediately in the response. 3DS authentication only applies when charging a saved card.

Example Response Body

{
  "token":            "tok_abc123xyz",
  "cardMask":         "411111******1111",
  "expirationMonth":  "12",
  "expirationYear":   "2028",
  "cardBrand":        "VISA",
  "cardType":         "CREDIT",
  "issuingBank":      "Bank of Dublin",
  "cardCountry":      "IE",
  "expirationDate":   "2028-07-14",
  "metadata":         { "customerId": "cust-789" }
}

See the Card Payments docs for detailed definitions of theCard, BillingDetails, Order, and Device objects.

Sandbox Testing

Test Cards

All test cards tokenize successfully — card behavior only differs at charge time:

Card Number	Tokenize Behavior	Charge Behavior
`4111111111111111`	Success	Approved
`5500000000000004`	Success	Approved
`4000000000003220`	Success	`CUSTOMER_VERIFICATION` + mock 3DS `challengeUrl`
`4000000000000002`	Success	`FAILED` with decline code

Token Expiration

Default TTL: 90 days (configurable per environment). If expirationDate is provided, the shorter of default and requested TTL is used
Expired or inactive tokens return a decline on charge attempts

Next Steps

Charge a Saved Card -- use the token to process a one-click payment
Set Up Recurring Payments -- create a subscription plan using the token