Tokenizing a Card

`POST /v1/payments/card/tokenize`

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 Exirom platform.

Request Body Parameters:

When tokenizing a card, provide the following fields in the JSON request body:

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.

For example

{
  "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"
}

Request Body Fields Description

Field	Type	Description
`requestId`	String	Unique identifier for the request (e.g., token reference).
`socialSecurityNumber`	String	Customer’s Social Security Number. Maybe`null` if not provided.
`card.number`	String	Full card number of the customer.
`card.expMonth`	String	Expiration month of the card (MM format).
`card.expYear`	String	Expiration year of the card (YYYY format).
`card.cvv`	String	Card security code (CVV/CVC).
`billingDetails.externalUserId`	String	External identifier for the user in the merchant’s system.
`billingDetails.firstName`	String	Customer’s first name.
`billingDetails.lastName`	String	Customer’s last name.
`billingDetails.address1`	String	Street address of the customer.
`billingDetails.city`	String	City of the billing address.
`billingDetails.state`	String	State or province of the billing address.
`billingDetails.country`	String	Country code (ISO 3166-1 alpha-2) for the billing address.
`billingDetails.postalCode`	String	Postal or ZIP code of the billing address.
`billingDetails.phone`	String	Customer’s phone number including country code.
`billingDetails.email`	String	Customer’s email address.
`billingDetails.dateOfBirth`	String	Customer’s date of birth (YYYY-MM-DD format).
`metadata.customerId`	String	Merchant-defined customer identifier stored as metadata.
`expirationDate`	String	Date when the token or card will expire (YYYY-MM-DD format).

Response

On success, this endpoint returns a token object containing a reference to the card. The exact structure can
include:

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.

Keep the cardToken secure; it is what you will use to perform charges or create recurring payments
without handling raw card numbers again.

{
  "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 theInitiating Card Payment API docs for detailed definitions of the Card, BillingDetails, Order, and Device objects.