Short-Term CC Data Storage

Hyp allows merchants to reuse CVV2/CVC, which is considered sensitive card data, from a previous transaction in a secure, PCI DSS-compliant manner.

Short-term credit card (CC) data storage refers to a session that securely retains CVV2/CVC for a brief 10-minute window after submission via the payment page. This allows the CVV2/CVC to be reused in a subsequent transaction without requiring the customer to re-enter it.

When is short-term storage needed?

Short-term storage supports a payment page flow that protects against network errors occurring between the customer submitting the payment page and the redirect to the merchant's success/failure page.

In the standard payment page flow, where the customer's card is charged immediately, a poorly timed network error may result in Hyp processing the charge without the merchant or customer receiving confirmation. If your customers frequently make purchases in environments with unstable internet connectivity, this can become a significant issue. To prevent this, you can use an alternative flow illustrated below that relies on short-term storage.

How is short-term storage different from tokenization?

Tokenization is designed for long-term storage and repeated use of the credit card number. It does not store CVV2/CVC.

Short-term storage, by contrast, only saves CVV2/CVC for up to 10 minutes, allows its use in a single follow-up transaction, and then discards it.

Short-term storage payment flows

There are two main payment flows that take advantage of short-term storage:

  1. Capture with short-term storage. This is the more common three-step flow that involves the following steps:

    1. A payment page request configured for tokenization only, with the keepCD element set to 1, initiating a short-term storage session.

    2. A transaction inquiry that returns the session ID via the sessionCD element.

    3. A follow-up capture transaction within the 10-minute window that references the session using the sessionCD element and sets useCD to 1.

  2. Two-phase commit with short-term storage. Use this flow if you want to both guard against network errors and allow time between holding funds and charging them. It consists of four steps:

    1. A payment page request configured for tokenization only, with the keepCD element set to 1, initiating a short-term storage session.

    2. A transaction inquiry that returns the session ID via the sessionCD element.

    3. An authorization transaction within the 10-minute window that references the session using the sessionCD element and sets useCD to 1.

    4. A capture transaction to charge the customer's card, occurring within 5 days of authorization, that uses the cgUid value returned by the authorization step.

Implementing capture with short-term storage

First, let's look at how you can implement the shorter three-step flow.

1. Request a payment page for tokenization only

First, make a payment page request with the keepCD element set to 1 to indicate that you want to save the CVV2/CVC in a short-term session. Set mpiValidation to Token to specify that you only want to tokenize the card and not charge it:

You then proceed as usual, extracting the payment page URL from the response and redirecting the customer to it.

Your success page in this flow should differ from the standard payment page flow. Since you initially only tokenize the customer's card, the payment is not yet complete when the customer is redirected to your success page. The success page should either indicate that the customer will be charged soon or display a progress UI until you perform the capture transaction.

After the customer submits the payment page and Hyp redirects them back to your success page, save the txId value from the payment completion redirect.

2. Retrieve the short-term session with a transaction inquiry

With the txId value in hand, make a transaction inquiry to obtain the sessionCD value, which will be required in the next step:

The response should look like this:

Show response

From this response, save the following values:

  • sessionCD: the identifier of the short-term storage session that holds the customer's CVV2/CVC.

  • cardId: the token representing the customer's credit card.

  • cardExpiration: the card's expiration date.

3. Perform the capture transaction

Finally, perform a server-to-server capture transaction that uses the CVV2/CVC stored in the short-term session. Include the following elements:

  • useCD set to 1: indicates that you want to use an existing storage session.

  • sessionCD: the value saved in step 2, specifying which session to use.

  • cardId: the token saved in step 2, identifying the customer's card.

  • cardExpiration: the value saved in step 2, specifying the card's expiration date.

The success response should look like this:

Show response

Implementing a two-phase commit with short-term storage

You can also combine short-term storage with a two-phase commit, where the third step is an authorization request that uses sessionCD, and the fourth step is a capture request that uses cgUid from the authorization step, since sessionCD can only be used once.

1. Request a payment page for tokenization only

Request a payment page for tokenization, following step 1 of the three-step flow described above.

2. Retrieve the short-term session with a transaction inquiry

Make a transaction inquiry to retrieve a short-term session ID, following step 2 of the three-step flow described above.

3. Perform the authorization transaction

Within 10 minutes of a successful redirect from the payment page, perform an authorization request using the CVV2/CVC stored in the short-term session. Include the following elements:

  • useCD set to 1: indicates that you want to use an existing storage session.

  • sessionCD: the value saved in step 2, specifying which session to use.

  • cardId: the token saved in step 2, identifying the customer's card.

  • cardExpiration: the value saved in step 2, specifying the card's expiration date.

The success response should look like this:

Show response

From this response, save the cgUid value that you'll need for the final step.

4. Perform the capture transaction

Within 5 days of authorization, perform a capture transaction that uses the cgUid saved in step 3, as well as the cardId and cardExpiration saved in step 2:

The success response should look like this:

Show response

FAQ

What is sessionCD, and how long is it valid?

sessionCD is an identifier for a short-term storage session that securely retains the CVV number from a previous transaction. It allows reusing the CVV without requiring the customer to enter it multiple times in the same flow.

A sessionCD is valid for 10 minutes, can be used exactly once, and expires immediately after use.

Which Hyp payment flows support short-term storage?

sessionCD and short-term storage are only supported in payment page flows, not in direct server-to-server requests.

Can the same sessionCD be reused for multiple transactions?

No. A sessionCD is valid for one-time use only and expires automatically afterward.

Do I still need to use a token when I use sessionCD?

Yes. cardId is a token for the credit card number and is required when using sessionCD.

Last updated

Was this helpful?