Tokenization

Tokenization is the process of converting a credit card number into a unique identifier ("token") that cannot be mapped back to the original credit card number without a key stored on Hyp's servers.

Tokens are a safe and PCI DSS-compliant way for you, as a merchant, to save card data without requiring the user to enter it again.

Hyp's API creates and returns card tokens every time a customer enters their credit card details via the payment page and proceeds to pay. A token is returned to the merchant in the payment completion redirect as the cardToken parameter.

The structure of a token

A token that Hyp creates uses the Luhn algorithm and always has the following properties:

1. It is a 16-digit number.

2. Its last four digits match the original credit card number.

3. It is never the same across merchants: the same credit card number is converted to a different token for different merchants.

A token maps to the credit card number only. It does not include the card's expiration date, CVV, the cardholder's social security number, or any other information.

Token use cases

Tokens are required to implement the following payment scenarios:

• Saved credit card. To enable customers to reuse previously saved card details, you save a token and expiration date following the first purchase, and then include these in payment page settings when the customer buys again. This is sometimes implemented with a two-terminal setup: terminal A, with a required CVV check, is used to collect credit card data during the first purchase, and terminal B, which doesn't require CVV entry, is used for low-friction subsequent purchases using a saved card.

• Recurring payments. The second and subsequent payments in subscription-based services are implemented as server-to-server payment requests that contain a pre-saved token and expiration date. See Implementing recurring payments for a walkthrough on collecting a token following the initial payment and using it in subsequent payments.

• Two-phase commits. The authorization request that's a part of a two-phase commit also requires using a card token and expiration date, unless it's performed using the payment page.

To enable all these use cases, you, as a merchant, need to save both the token (the cardToken URL parameter) and the card expiration (cardExp) values from the payment completion redirect. These values are then used in payment requests as cardId and cardExpiration parameters, respectively.

Some terminals also require the cardholder's Israeli ID number (תעודת זהות). In this case, you must save the ID number along with the token and expiration date. You receive the ID from the payment completion redirect as the personalId URL parameter and then use it in payment requests as the id parameter. Note that the Israeli ID number is considered sensitive personal data under privacy regulations such as the GDPR and the Israeli Privacy Law. As a merchant, you are responsible for ensuring the secure storage and handling of this information.

FAQ

What are the benefits of using a token?

• Security and PCI DSS compliance: the merchant doesn't need to store card details, which are sensitive information.

• Simplicity: the same card can be charged again without asking the customer every time.

Are CVV, expiration date, and customer ID parts of a token?

No, the expiration date, CVV, and the customer's ID are not parts of a token.

Can I reuse a credit card token between different merchants?

No, by default a token cannot be reused by another merchant, a third-party entity, or Hyp itself to charge the customer's card. If someone gets hold of a token created for your customer, they cannot normally map it back into a credit card number.

That said, there is a terminal setting that allows you to create tokens that can be used by multiple merchants. This is a highly dangerous setting to enable and should only be used in very specific, niche cases.