> ## Documentation Index > Fetch the complete documentation index at: https://waffo.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Tokenization Generate ## OpenAPI ````yaml /api-reference/tokenization-api.json post /api/v1/tokenization/generate openapi: 3.1.0 info: title: OpenAPI definition version: v0 servers: - url: http://localhost:8080/cardcenter description: Generated server url security: [] paths: /api/v1/tokenization/generate: post: tags: - Waffo Tokenization API summary: Tokenization Generate operationId: generateToken requestBody: content: application/json: schema: $ref: '#/components/schemas/TokenGenerateRequest' required: true responses: '200': description: OK content: '*/*': schema: $ref: '#/components/schemas/ResponseTokenGenerateData' callbacks: tokenizationNotification: '{$request.body#/notifyUrl}': post: summary: Tokenization update notification description: >- Webhook invoked by Waffo when the token status changes or token data is updated. Merchant is expected to respond with {"message":"success"}; failed/unknown triggers retries for up to 24 hours. requestBody: content: application/json: schema: $ref: '#/components/schemas/TokenizationNotificationPayload' required: true responses: '200': description: Merchant acknowledgement content: '*/*': schema: $ref: '#/components/schemas/MerchantNotificationResponse' method: post type: path path: '{$request.body#/notifyUrl}' components: schemas: TokenGenerateRequest: type: object properties: tokenRequestId: type: string description: >- Tokenization request ID sent from Merchant. It will also be used for idempotent check. For example: use uuid to generate a unique serial no. maxLength: 64 minLength: 0 merchantUserId: type: string description: The merchant's userId must be unique for each user of merchants. maxLength: 64 minLength: 0 tokenType: type: string description: 'Types of requested tokenization: CARD.' maxLength: 32 minLength: 0 merchantInfo: $ref: '#/components/schemas/MerchantInfo' description: Merchant info. notifyUrl: type: string description: >- The callback address to notify the merchant after the Tokenization is completed or failed. maxLength: 256 minLength: 0 tokenData: $ref: '#/components/schemas/TokenPlainData' description: >- If your organization possesses the necessary PCI-DSS certification to store and process raw cardholder data, you may pass the sensitive card details (including pan, expiry, cvv, and name) directly within the tokenData object when calling this endpoint. billingAddress: $ref: '#/components/schemas/BillingAddress' description: The cardholder's billing address. required: - merchantInfo - merchantUserId - tokenRequestId - tokenType ResponseTokenGenerateData: type: object description: Standard API response envelope. properties: code: type: string description: >- Result code. "0" indicates success; any other value indicates failure. msg: type: string description: Human-readable message corresponding to the result code. msgParams: type: object additionalProperties: {} description: >- Key-value parameters associated with the error message, used for templated errors. data: $ref: '#/components/schemas/TokenGenerateData' description: Response payload. Empty when the request fails. success: type: boolean fail: type: boolean TokenizationNotificationPayload: type: object description: >- Webhook payload POSTed to merchant's notifyUrl when token status or data changes. properties: eventType: type: string description: >- Event type of the notification. Fixed value: TOKENIZATION_NOTIFICATION. example: TOKENIZATION_NOTIFICATION result: $ref: '#/components/schemas/TokenInquiryData' description: Notification result object containing the latest tokenization data. MerchantNotificationResponse: type: object description: >- Merchant's acknowledgement to the tokenization notification webhook. If failed/unknown is received, Waffo will retry the notification for up to 24 hours. properties: message: type: string description: 'Processing result. Allowed values: success, failed, unknown.' enum: - success - failed - unknown example: success MerchantInfo: type: object properties: merchantId: type: string description: Merchant id assigned by Waffo. maxLength: 32 minLength: 0 subMerchantId: type: string description: Sub merchant id assigned by Waffo. maxLength: 64 minLength: 0 required: - merchantId TokenPlainData: type: object properties: pan: type: string description: >- Primary Account Number (Card Number). The length must be between 14 and 19 digits. Please remove any spaces or dashes. (Note: Only available for PCI-DSS compliant merchants.) maxLength: 19 minLength: 14 expiry: type: string description: >- Expiration Date. Format must be MM/YYYY (e.g., 09/2027). Ensure the month is two digits (01-12) and the year is four digits. Note: While MM/YY input is also supported on this endpoint, the system will continue to return expiration dates as MM/YYYY in both token queries and callback notifications. maxLength: 7 minLength: 5 name: type: string description: >- Cardholder Name. The full name as it appears on the card. Length must be between 2 and 100 characters. maxLength: 100 minLength: 2 cvv: type: string description: >- Card Security Code. The 3 or 4-digit security code (CVV2/CVC2/CID). Optional, but highly recommended for verification purposes. maxLength: 4 minLength: 3 BillingAddress: type: object properties: countryCode: type: string description: >- The three-letter ISO 3166-1 alpha-3 code representing the country of the billing address (e.g., USA for the United States). maxLength: 3 minLength: 0 region: type: string description: >- The state, province, or region within the country (e.g., CA for California). maxLength: 40 minLength: 0 city: type: string description: The city or town of the billing address (e.g., Cupertino). maxLength: 50 minLength: 0 postalCode: type: string description: >- The ZIP code or postal code associated with the address (e.g., 95014). maxLength: 20 minLength: 0 address: type: string description: >- The primary street address or delivery line (e.g., One Apple Park Way). maxLength: 300 minLength: 0 TokenGenerateData: type: object properties: tokenRequestId: type: string description: >- Tokenization request ID sent from Merchant. It will also be used for idempotent check. tokenSessionId: type: string description: >- The token session id is generated by the Waffo side, which is associated with the merchant and the merchant user ID, and is used for authorizing the merchant's user to invoke the Waffo JSSDK for card tokenization. merchantUserId: type: string description: The merchant's userId must be unique for each user of merchants. tokenId: type: string description: >- The tokenization id of card info. The merchant needs to securely store this field, and subsequently, when initiating user payments or backend deductions, this token can be used to replace the user's card information for payment. Only returned when the merchant submits the full raw cardholder data in the request. TokenInquiryData: type: object properties: tokenRequestId: type: string description: >- Tokenization request ID sent from Merchant. It will also be used for idempotent check. If the token status change is invoked by Waffo, this field will not be present. tokenId: type: string description: >- The tokenization id of card info. The merchant needs to securely store this field, and subsequently, when initiating user payments or backend deductions, this token can be used to replace the user's card information for payment. tokenType: type: string description: 'Types of requested tokenization: CARD.' tokenStatus: type: string description: >- Token status: UNVERIFIED (Card information submitted from the frontend, but the card has not been verified); VERIFIED (The card has been verified); EXPIRED (Token has expired); SUSPENDED (Usage has been suspended). merchantUserId: type: string description: The merchant's userId must be unique for each user of merchants. tokenData: $ref: '#/components/schemas/CardTokenData' description: The tokenization object of card info. billingAddress: $ref: '#/components/schemas/BillingAddress' description: The cardholder's billing address. merchantInfo: $ref: '#/components/schemas/MerchantInfo' description: Merchant info. CardTokenData: type: object properties: maskedCardInfo: type: string description: >- The partially masked primary account number (PAN) of the card. This format typically shows the first 6 and the last 4 digits for security while still identifying the card. cardHolderName: type: string description: The full name of the cardholder as it appears on the card. cardExpiry: type: string description: The expiration date of the card, in MM/YYYY format. cardBin: type: string description: >- The Bank Identification Number (BIN) or Issuer Identification Number (IIN). This is the first six digits of the card number, used to identify the institution that issued the card. cardScheme: type: string description: >- The card network that processes the transaction. Such as: VISA, MASTERCARD, JCB, AMEX, DISCOVER, UNIONPAY, DINERS. cardType: type: string description: >- The type of card, specifying if it is a CREDIT_CARD, DEBIT_CARD, or PREPAID_CARD. cardIssuerName: type: string description: >- The official name of the bank or financial institution that issued the card. cardIssueCountryCode: type: string description: >- The three-letter ISO 3166-1 alpha-3 country code of the country where the card was issued (e.g., USA for the United States). ````