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. cardInfo: Collect and submit complete card details from a PCI-compliant environment.
2. merchantCustId: Provide a stable customer identifier to associate the card token with the customer.
3. returnUrl: Provide a browser return URL for card binding flows that require 3DS authentication.

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 upon registration, obtained from the Onerway merchant dashboard.
appId	String	20	Yes	Yes	Merchant application ID assigned by Onerway for website identification.
merchantCustId	String	50	Conditional	Yes	Unique customer identifier in merchant system.
cardInfo	String	/	Conditional	Yes	Card payment information in JSON string format. See TxnCardInfo for complete structure.
email	String	256	Yes	Yes	Customer email address for transaction notifications and receipts.
country	String	64	Yes	Yes	Customer country code for risk assessment and compliance. See ISO 3166 for complete list.
transactionIp	String	64	Yes	Yes	Customer's IP address for fraud detection and risk assessment.
returnUrl	String	256	Yes	Yes	Browser return URL after 3DS authentication.
sign	String	/	Yes	No	Digital signature string for request verification and security. 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	Transaction identifier generated by Onerway.
tokenId	String	Tokenized card identifier for future payments.
status	String	Tokenization status. S - successful tokenization R - 3DS authentication required F - tokenization failure
redirectUrl	String	3DS authentication redirect URL.
sign	String	Response signature. See Signature interface.

Card Tokenization Integration Process

Card tokenization can complete immediately or require 3DS authentication, depending on card, issuer, and risk controls:

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 either a final binding result or a 3DS redirect
• If status=S, the merchant stores the returned tokenId for future tokenized payments
• If status=R, the merchant redirects the cardholder to redirectUrl and handles the browser return on returnUrl
• The browser return to returnUrl is not by itself final confirmation; confirm the final binding status before storing or using the token

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. Handle 3DS Redirects: Redirect to redirectUrl when status=R and prepare the returnUrl page for both successful and failed authentication outcomes
8. Secure Logging: Ensure that sensitive card details are never logged in your systems

API Usage Examples

Request

{
  "appId": "<APP_ID>",
  "cardInfo": "{\"cardNumber\":\"4000000000002701\",\"cvv\":\"123\",\"month\":\"05\",\"year\":\"2026\",\"holderName\":\"CARD HOLDER\"}", 
  "country": "US",
  "email": "customer@example.com",
  "merchantCustId": "customer_12345",
  "merchantNo": "<MERCHANT_NO>",
  "returnUrl": "https://merchant.example.com/card-binding/return", // Browser return URL after 3DS
  "sign": "<SIGNATURE>",
  "transactionIp": "123.22.43.1"
}

Response - successful binding

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "<TRANSACTION_ID>",
    "tokenId": "<TOKEN_ID>", // Store only after final success
    "status": "S", // S indicates successful tokenization
    "sign": "<RESPONSE_SIGNATURE>"
  }
}

Response - 3DS required

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "<TRANSACTION_ID>",
    "status": "R", // Redirect required for 3DS authentication
    "redirectUrl": "https://sandbox-gw-dmz.onerway.com/3dsSecure/direct/<SESSION_ID>", // 3DS authentication URL
    "sign": "<RESPONSE_SIGNATURE>"
  }
}

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. 3DS Handling: Redirect the customer when redirectUrl is returned and use returnUrl only as a browser return point
9. Multiple Environment Support: Implement separate workflows for sandbox and production environments
10. 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
• returnUrl page prepared for 3DS browser returns
• 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