Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Saving Card Tokens

Tokenization means turning a credit card number into a unique identifier called a "token." This token is safe to store because it can't be turned back into the original card number without a secret key that's kept securely on Hyp's servers.

A token is always a 19-digit number where the last four digits match the original card. For security, tokens are unique to each merchant — the same card will result in different tokens for different businesses.

Using tokens is a great, PCI DSS-compliant way to save card data so your customers don't have to re-enter it every time you charge them. This always works when they pay with a credit or debit card. In two-phase commits, this also works with digital wallets like Apple Pay or Google Pay.

Keep in mind that a token only represents the card number. It doesn't include the card's expiration date, CVV, or any other customer details.

Hyp's API creates a token whenever a customer enters their card details on your payment page. However, the token isn't handed to you automatically; you'll need to make a separate API call to go and get it.

Token use cases

You'll need tokens to handle these kinds of payment scenarios:

  • Recurring payments. Subscription-style services use tokens for every payment after the first one. You'll send a server-to-server request that includes the saved token and expiration date.

  • Two-phase commits. If you need to check your inventory before charging your customer, you split the transaction into two steps: authorization and capture. This flow also involves using tokens.

To make this work, you need to save both the token and the card's expiration date. You'll grab these by making a getToken request using the Id parameter you get from the payment completion redirect. When you're ready to charge the card later, you'll need to pass these values.

Getting a token

Even though a token is created in the background when a customer pays, it isn't included in the payment completion redirect. You'll need to ask for it specifically.

Step 1: Save parameters from the payment completion redirect

When a customer finishes paying, they'll be sent back to your website. The redirect URL will have an Id parameter — this is the unique ID for that transaction on our end. You'll need to grab this Id so you can use it to fetch the token.

If your terminal is set up to require an Israeli ID, you'll also see a UserId parameter in that redirect. Make sure to save this too. Just a heads-up: Israeli ID numbers are considered sensitive personal data under privacy laws like the GDPR, so be sure to handle and store them securely.

Whether your terminal requires an Israeli ID depends on your acquirer. If you'd like to make the Israeli ID optional and avoid saving UserId, please contact your acquirer.

Step 2: Request the token

To get the token, make a GET request to https://pay.hyp.co.il/p/ with these parameters:

  • action: Set this to getToken.

  • Masof: Your terminal number.

  • PassP: Your API password.

  • TransId: The transaction ID (the Id you got from the payment page redirect).

  • allowFalse: This is optional. If you set it to True, we'll give you a token even if the original transaction didn't go through (for example, if the card was just verified or the payment was canceled).

Here's an example request:

Step 3: Save values from the response

We'll send back a URL-encoded string. You need to parse it to find the Token and Tokef values.

A successful response looks like this:

The response includes these key parameters:

  • CCode: The status code. If it's 0, everything went fine.

  • Token: The 19-digit card token. Save this value securely.

  • Tokef: The card's expiration date in YYMM format. Save this along with the token, because you'll need both for future charges.

If CCode isn't 0, something went wrong. Here are the most common error codes:

  • 901: No permission. Your terminal isn't authorized to use tokenization.

  • 902: Authentication failure. Double-check that your PassP is correct.

  • 910: Invalid transaction for tokenization. This means the transaction wasn't successful and you forgot to include allowFalse=True in your request.

Once you've grabbed the token and the expiration date, you're all set to start charging the card. To see how to put these tokens to work, check out our guides on recurring payments and two-phase commits.

Last updated

Was this helpful?