Card Tokenization

PCI Compliance Requirement

Card tokenization requires PCI DSS compliance as it involves handling sensitive card data directly. Merchants must:

1. Maintain a valid PCI DSS certification (minimum SAQ D or SAQ A-EP level)
2. Securely collect and transmit cardholder data using TLS 1.2 or higher
3. Never store sensitive authentication data (e.g., CVV codes) after transaction authorization
4. Implement proper encryption and security measures for data in transit and at rest
5. Perform regular security testing and vulnerability scanning
6. Maintain strict access controls to cardholder data environments

If you do not have PCI certification, please use the SDK Payment or SDK Binding options instead.

API Request Parameters

POST

Key Parameters for Tokenization

When integrating tokenization, you need to set these key parameters:

1. subProductType: Must be set to TOKEN for all tokenization transactions.

Note

• All JSON fields must be stringified before submission
• Nested objects must be serialized to JSON string format
• JSON fields must not contain unescaped special characters
• Arrays in JSON should be properly formatted
• Example of JSON string field:

{
    "object": "{\"obj-key1\":\"v1\",\"obj-key2\":\"v2\"}",
    "complex": "{\"k1\":\"v1\",\"array\":\"[{\\\"obj-key3\\\":\\\"v3\\\",\\\"obj-key4\\\":\\\"v4\\\"}]\"}"
}

Parameter	Type	Length	Required	Signed	Description
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway, obtained from Onerway dashboard
appId	String	20	Yes	Yes	Merchant application ID. Created by Onerway when merchant registers a website
merchantCustId	String	50	Conditional	Yes	Unique customer identifier in merchant system.
cardInfo	String	/	Conditional	Yes	Card payment information in JSON string format. See TxnCardInfo
email	String	256	Yes	Yes	Customer email address
country	String	64	Yes	Yes	Customer country code. See ISO 3166
transactionIp	String	64	Yes	Yes	Customer's IP address for the transaction
sign	String	/	Yes	No	Digital signature string for request verification. Please refer to Signature for signature generation method.

CardInfo

Name	Type	Length	Required	Description
holderName	String	48	Yes	Cardholder name
cardNumber	String	128	Yes	Card number
month	String	64	Yes	Expiry month
year	String	64	Yes	Expiry year
cvv	String	64	Yes	Card CVV

Card Information Security

When handling card information:

• Collect card details directly from customers in a secure form
• Implement client-side validation to check card number format, expiry date, and CVV
• Transmit data with strong encryption (TLS 1.2+)
• Never log or store the full card number or CVV
• Consider implementing card number masking in your UI (e.g., showing only the last 4 digits)
• Implement proper access controls and audit logging for tokenization requests

Response

Name	Type	Description
respCode	String	Response code from Onerway
respMsg	String	Response message from Onerway
data	Object	Response data. Refer to object data

data

Field	Type	Description
transactionId	String	The transaction identifier generated by Onerway payment system.
tokenId	String	The tokenized card identifier that can be used for future tokenized payments. Store this value securely for future payment transactions.
status	String	Card tokenization status. S - indicates successful tokenization, F - indicates tokenization failure.
sign	String	The signature string. See the Signature interface.

Card Tokenization Integration Process

The Card Tokenization integration process is simpler than payment processes as it does not require 3DS verification:

In this process:

• Customer enters card information on the merchant's website/application (custom UI)
• Merchant system securely collects and transmits the card data to Onerway
• Onerway processes the tokenization request and returns a tokenId
• The merchant stores this tokenId for future tokenized payments
• No 3DS verification is required for card tokenization
• No webhook notifications are sent for tokenization requests

Important Notes

When implementing Card Tokenization, merchants must:

1. Design a Secure Card Collection UI: Create a user-friendly interface that securely collects card details
2. Implement Secure Transmission: Use TLS 1.2+ encryption and proper security measures
3. Store TokenId Securely: Safely store the returned tokenId for future use
4. Maintain PCI Compliance: Ensure your systems meet PCI DSS requirements
5. Handle Error Cases: Properly handle and display error messages to customers
6. Implement Client-side Validation: Validate card format, expiry date, and other details before submission
7. Secure Logging: Ensure that sensitive card details are never logged in your systems

API Usage Examples

Request

{
  "appId": "1727880846378401792",
  "cardInfo": "{\"cardNumber\":\"4000000000002701\",\"cvv\":\"123\",\"month\":\"05\",\"year\":\"2026\",\"holderName\":\"CL BRW2\"}", 
  "country": "US",
  "email": "abel.wang@onerway.com",
  "merchantCustId": "37137177",
  "merchantNo": "800209",
  "sign": "77e39fd043f7d7be12edf94fbccdcd923196643f58ad7031c80dc48e198c8088",
  "transactionIp": "123.22.43.1"
}

Response

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1919700729300656128",
        "tokenId": "da424ce8811fbfc8871e0acc4f1d82ef7ee8526faed88cf4a4fb84a8c4e4d82d", 
        "status": "S", // S indicates successful tokenization
        "sign": "eedd2e39f5d4fb66649bc7b8d2dbd6a5ca27a129a53a439d8e510c04bad01358"
    }
}

Common Error Scenarios and Solutions

Error Code	Description	Solution
13002	Invalid card number	Verify the card number format and checksum
30008	Invalid CVV2(Visa only) / CVC2(Mastercard only)	Ensure the CVV is the correct length (3-4 digits)
60054	Expired card or expiration date missing	Check that the expiry date is in the future

Error Handling Best Practices

• Present user-friendly error messages to customers
• Implement appropriate retry mechanisms with exponential backoff
• Log detailed error information (excluding sensitive card data) for troubleshooting
• Monitor error rates to detect potential system issues

Using Tokenized Cards

After successful tokenization, the returned tokenId can be used for future transactions without requiring the customer to re-enter their card details. To use the token for payment, refer to the Token Payment documentation.

Token Security

While tokenization reduces PCI scope for subsequent transactions, merchants must still implement proper security measures to protect the tokenId, as it can be used for future transactions. Implement proper access controls, encryption, and secure storage practices.

Implementation Best Practices

1. PCI Compliance: Maintain and regularly update your PCI DSS certification
2. Secure Transmission: Always use TLS 1.2+ encryption and implement proper security measures
3. UI Design: Create a user-friendly card collection form that clearly indicates required fields
4. Error Handling: Implement robust error handling and provide clear messages to customers
5. Token Storage: Store tokenIds securely in your database, properly associated with customer profiles
6. Token Lifecycle: Implement proper token lifecycle management, including token expiration handling
7. Validation: Perform basic card number validation on the client side before submission
8. Multiple Environment Support: Implement separate workflows for sandbox and production environments
9. Logging and Monitoring: Implement comprehensive logging and monitoring (excluding sensitive data)

When to Use Direct Tokenization

Choose direct tokenization when:

• You have full PCI DSS certification
• You need complete control over the UI/UX
• You want to customize every aspect of the card collection flow
• You need to integrate with custom backend systems

Merchant Integration Checklist

Before going live with Card Tokenization integration, ensure you have:

• Valid PCI DSS certification (minimum SAQ D or SAQ A-EP level)
• Secure card data collection form with proper client-side validation
• TLS 1.2+ encryption for all data transmission
• Proper error handling mechanisms with user-friendly messages
• Secure tokenId storage system with appropriate access controls
• Token lifecycle management policies and procedures
• Comprehensive logging and monitoring (excluding sensitive data)
• Thorough testing in sandbox environment
• Security vulnerability assessment and penetration testing