Skip to main content

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.

Securely convert users’ bank card information into a token, so there is no need to enter the card number again for subsequent payments.

​
Core flow

1. Merchant backend → Call Generate API → Get tokenSessionId
2. Frontend → Use @waffo/payment-sdk to submit card information → Card data is transmitted with encryption
3. Processing result → Get tokenId (3DS verification may be required)
4. Subsequent payments → Pass tokenId in order/create to replace the card number

​
Card binding flow

1

Merchant backend calls the Generate API

Call POST /api/v1/tokenization/generate, passing parameters such as tokenRequestId, merchantUserId, and tokenType: "CARD". On success, it returns tokenSessionId.See Generate API for details.
2

Frontend submits card information

Use the tokenizationSubmit method of @waffo/payment-sdk to encrypt the card data and submit it to the Waffo server:
import WaffoSDK from '@waffo/payment-sdk';

const sdk = new WaffoSDK('your-client-api-key', {
  env: 'prod',
  locale: 'en'
});

const result = await sdk.tokenizationSubmit('tokenSessionId', {
  tokenData: {
    pan: '4111111111111111',
    name: 'John Doe',
    expiry: '12/2025',    // MM/YYYY
    cvv: '123'            // 可选
  },
  billingAddress: {        // 可选
    countryCode: 'USA',
    region: 'CA',
    city: 'San Francisco',
    postalCode: '94102',
    address: '123 Main St'
  }
});
The SDK automatically encrypts card data. The merchant server never touches the plaintext card number, so PCI DSS certification is not required.
3

Handle the card binding result

if (result.success) {
  const { tokenRequestId, validateUrl } = result.data;

  if (validateUrl) {
    // 需要 3DS 验证，重定向用户
    window.location.href = validateUrl;
  } else {
    // 绑卡成功，等待 Webhook 获取 tokenId
  }
}
After card binding is completed, Waffo sends a notification to the merchant backend via notifyUrl, containing the final tokenId. The merchant must store this tokenId and use it for subsequent payments.

​
Alternative: PCI-DSS merchants submit directly

If the merchant is PCI-DSS certified, they can submit sensitive information such as the card number directly from the backend through the tokenData field of the Generate API, without using the frontend SDK. In this case, the API returns tokenId directly.

​
Pay with a token

After obtaining tokenId, pass it when creating an order to replace the card number: 
const response = await waffo.order().create({
  paymentRequestId: '...',
  merchantOrderId: 'ORDER_001',
  orderCurrency: 'HKD',
  orderAmount: '100.00',
  tokenId: 'tok_xxxxxxxxxxxx',  // 使用 Token 代替卡号
  notifyUrl: 'https://your-site.com/webhook',
  // ... 其他参数
});
Supports one-time payments (ONE_TIME_PAYMENT) and subscription payments (SUBSCRIPTION).

​
Token management

ActionAPIDescription
InquiryPOST /api/v1/tokenization/inquiryRetrieve the list of tokens a user has bound
RemovePOST /api/v1/tokenization/removeDelete a bound token

​
Security mechanisms

  • The frontend SDK automatically encrypts card data; the merchant server never touches the plaintext card number
  • All API requests and responses use SHA256WithRSA signature verification
  • Supports 3DS verification to enhance payment security
  • Non-PCI-DSS merchants must use the frontend SDK and cannot pass card numbers directly from the backend