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.
`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",
  "socialSecurityNumber":  null,
  "card": {
    "number":   "4111111111111111",
    "expMonth": "12",
    "expYear":  "2025",
    "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.
`cardMask`	String	Masked PAN for display/logging (e.g. `411111******1111`).
`expMonth`	String	Card expiration month (MM).
`expYear`	String	Card expiration year (YYYY).
`status`	String	Token status: `ACTIVE` or `INACTIVE`.
`issuingBankCountry`	String	ISO-2 country code of the issuing bank (e.g. `IE`).
`binCardCategory`	String	BIN-derived category (e.g. `CLASSIC`, `GOLD`).
`cardPaymentBrand`	String	Card scheme brand (e.g. `VISA`, `MASTERCARD`).
`binCardType`	String	BIN-derived card type: `DEBIT` or `CREDIT`.
`issuingBankName`	String	Name of the issuing bank as returned by BIN lookup.
`binCardCountryCode`	String	ISO-2 country code of the card’s BIN (e.g. `IE`).
`createdAt`	String	ISO-8601 timestamp when the token was created.
`expirationDate`	String (YYYY-MM-DD)	ISO-8601 date. Date when this token will expire (5-year default if not set).
`redirectUrl`	String	Nullable URL to redirect the customer for a 3DS challenge if additional authentication is required.
`billingDetails`	Object (BillingDetails)	(Optional in Create) Original billing info you provided—returned for reference.
`metadata`	Map<String,String>	(Optional) Echo of your free-form metadata map.

Example Response Body

{
  "token":                "tok_abc123xyz",
  "cardMask":             "411111******1111",
  "expMonth":             "12",
  "expYear":              "2025",
  "status":               "ACTIVE",
  "issuingBankCountry":   "IE",
  "binCardCategory":      "CLASSIC",
  "cardPaymentBrand":     "VISA",
  "binCardType":          "CREDIT",
  "issuingBankName":      "Bank of Dublin",
  "binCardCountryCode":   "IE",
  "createdAt":            "2025-07-14T10:00:00Z",
  "expirationDate":       "2028-07-14",
  "redirectUrl":          null
}

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