Tokens (Reusable Identifiers)

On this page:

Overview

On completion of a payment transaction type, your customers’ card details are converted into a unique cardIdentifier by the Opayo JavaScript library. This "token" is removed from our servers after:

  • A successful transaction is registered, or
  • 400 seconds.

With Opayo's Token feature enabled, you can ask us to save the cardIdentifier as a reusable token. The card details remain completely secure on our system and you can use the token when you process the returning customer's purchases. Returning customers need only:

  1. Sign in to your website.
  2. Select a card to pay with.
  3. Proceed to checkout without needing to re-enter their card details.

You can also implement single-click checkout flows using tokens without compromising your PCI level.

Enable the Token Functionality

Please call our team to enable the Opayo token system:

  • From within the United Kingdom: 0191 313 0299
  • From outside the United Kingdom: +44 191 313 0299

    Save the Card Details

    Important: If you want to store cards for future use, you will need to follow the Credential on File rules, detailed here.

    To save the card details as a token for future purchases during the initial transaction registration, in the card object, set the save value to ‘true’ . For example:

    curl https://pi-test.sagepay.com/api/v1/transactions
    \ -H "Authorization: Basic aEpZeHN3N0hMYmo0MGNCOHVkRVM4Q0RS…jEyejRqNVVzNXU="
    \ -H "Content-type: application/json"
    \ -X POST
    \ -d '{
        "transactionType": "Payment",
        "paymentMethod": {
            "card": {
                "merchantSessionKey": "",
                "cardIdentifier": "",
                "save": true
            }
        },
        "vendorTxCode": "demotransaction-",
        "amount": 10000,
        "currency": "GBP",
        "description": "Demo transaction",
        "apply3DSecure": "UseMSPSetting",
        "customerFirstName": "Sam",
        "customerLastName": "Jones",
        "billingAddress": {
            "address1": "407 St. John Street",
            "city": "London",
            "postalCode": "EC1V 4AB",
            "country": "GB"
        },
        "credentialType": {
            "cofUsage": "First",
            "initiatedType": "CIT",
            "mitType": "Unscheduled"
        },
        "entryMethod": "Ecommerce"
    }'
    
    Successful Transaction
    

      A Successful Response

      You will receive all the data you need to store the card in the card object as a token when:

      • The token functionality is enabled on your account.
      • The transaction is successful.

      In the following example response, the reusable flag has been successfully set to true.  You can now reuse the cardIdentifier (the token) for this customer’s future transactions.

      {
          "statusCode": "0000",
          "statusDetail": "The Authorisation was Successful.",
          "transactionId": "C534972A-EC77-6346-4D42-62424786CEDC",
          "transactionType": "Payment",
          "retrievalReference": 12393934,
          "bankResponseCode": "00",
          "bankAuthorisationCode": "999777",
          "paymentMethod": {
              "card": {
                  "cardType": "Visa",
                  "lastFourDigits": "0006",
                  "expiryDate": "1120",
                  "cardIdentifier": "E836B9F8-0F85-4BE6-817B-B90144139196",
                  "reusable": true
              }
          },
          "status": "Ok",
          "3DSecure": {
              "status": "NotChecked"
          }
      }

      Reusing the Token

      When successfully created and stored, a token (stored in the reusableCardIdentifier) can be used for future purchases made by the customer.

      Opayo stores all your customer’s card details against the cardIdentifier except the CVV. The CVV is sensitive authentication data and cannot be stored after authorisation even when encrypted. Your returning customer must resubmit their card’s CVV for each purchase. How you capture that depends on the integration method you choose.
       

      Note: Your customer must be 'in-session' in order to submit a CVV value. If you don't want to establish a session with your customer (for example, you wish to submit a MIT transaction), you should post the applyAvsCvcCheck with the value Disable.

      Capture the CVV with Drop-in Checkout

      Follow these steps to capture your returning customer’s CVV when using a token in the Drop-In Checkout:

      1. Create a merchant session key. (Refer to the Authentication and Credentials section.)
      2. Include our JavaScript library (sagepay.js) on the page.
      3. Create a container where the drop-in iFrame will display. For help, please check our getting started guide.
      4. Call sagepayCheckout with the merchantSessionKey and reusableCardIdentifier values as in the following example:
        <script>
        sagepayCheckout({ merchantSessionKey : '657B1783-3A76-4A3E-96F0-578D894DF02D', reusableCardIdentifier : 'CAFECA44-41C9-4072-AC03-542227D38D7E' }).form();
        </script>
      5. When the customer enters their CVV and submits the form, the code is validated and stored against the reusableCardIdentifier.

      When the request is successful you will receive an empty (no content) HTTP 204 response.

      Capture the CVV with Own Form

      Follow these steps to capture your returning customer’s CVV when using a reusable Card Identifier in your Own Form:

      1. Create a merchant session key. (Refer to the Authentication and Credentials section.)
      2. Include our JavaScript library (sagepay.js) on the page.
      3. Include the securityCode field in your form.
        For example:
        <input id="cvv" data-card-details="security-code">
        Important: Do not to set a name attribute on this field to ensure that the securityCode is not submitted to your server.
      4. Call activateReusableCardIdentifier when you load the page.

      Example form

      <!DOCTYPE html>
      <html lang="en">
      <body>
      <form method="post">
      <label for="cvv">CVV:</label>
      <div>
      <input id="cvv" data-card-details="security-code">
      </div>
      <input type="hidden" name="activated">
      <div>
      <button type="submit">Pay Now</button>
      </div>
      </form>
      <script src="https://pi-test.sagepay.com/api/v1/js/sagepay.js"></script>
      <script>
      document.querySelector('[type=submit]').addEventListener('click', function(e) { e.preventDefault(); sagepayOwnForm({ merchantSessionKey: 'C2C6A75C-AE42-41C5-847B-B9204FB7471F' }).activateReusableCardIdentifier({ reusableCardIdentifier: '5727B453-BA1C-AB52-A36E-0037332EA1D0', securityCode: document.querySelector('[data-card-details="security-code"]').value, onActivated: function(result) { if (result.success === true) { document.querySelector('[name="activated"]').value = "true"; document.querySelector('form').submit(); } else { console.log(JSON.stringify(result)); } } }); }, false);
      </script>
      </body>
      </html>
      

      When the server has processed the request successfully you will receive an empty (no content) HTTP 204 response.

      Take Payments Using Tokens

      To use a token for a payment, you must include the cardIdentifier in the card object and set its reusable flag to true.

      Important: As in the following example, the merchantSessionKey value must correspond to the merchantSessionKey used to submit the CVV for the specified cardIdentifier.
      Important: If you wish to reuse a card token, you must include the appropriate Credential on File fields.
      curl https://pi-test.sagepay.com/api/v1/transactions \ -H "Authorization: Basic aEpZeHN3N0hMYmo0MGNCOHVkRVM4Q0RSRkxodUo4RzU0TzZyRHBVWHZFNmhZRHJyaWE6bzJpSFNyRnliWU1acG1XT1FNdWhzWFA1MlY0ZkJ0cHVTRHNocktEU1dzQlkxT2lONmh3ZDlLYjEyejRqNVVzNXU=" \ -H "Content-type: application/json" \ -X POST \ -d '{
          "transactionType": "Payment",
          "paymentMethod": {
              "card": {
                  "merchantSessionKey": "<msk>",
                  "cardIdentifier": "<card-identifier>",
                  "reusable": true
              }
          },
          "vendorTxCode": "demotransaction-",
          "amount": 10000,
          "currency": "GBP",
          "description": "Demo Payment",
          "apply3DSecure": "UseMSPSetting",
          "customerFirstName": "Sam",
          "customerLastName": "Jones",
          "billingAddress": {
              "address1": "407 St. John Street",
              "city": "London",
              "postalCode": "EC1V 4AB",
              "country": "GB"
          },
          "credentialType": {
              "cofUsage": "Subsequent",
              "initiatedType": "MIT",
              "mitType": "Unscheduled"
          },
          "entryMethod": "Ecommerce"
          }'
      Note: When AVS/CV2 checks are not required for a payment, then you do not need to pass a merchant session key value when you perform a token transaction, as in the following example:
      curl https://pi-test.sagepay.com/api/v1/transactions \  -H "Authorization: Basic aEpZeHN3N0hM...0ZkJ0cHVTRHNocktEU1dzQlkxT2lONmh3ZDlLYjEyejRqNVVzNXU=" \  -H "Content-type: application/json" \ -X POST \ -d '{          
          "transactionType": "Payment",
          "paymentMethod": {
                "card": {
                    "cardIdentifier": "<card-identifier>",
                    "reusable": true
                }
            },
            "vendorTxCode": "demotransaction-<unique-suffix>",
            "amount": 10000,
            "currency": "GBP",
            "description": "Demo Payment",
            "apply3DSecure": "UseMSPSetting",
            "customerFirstName": "Sam",
            "customerLastName": "Jones",
            "billingAddress": {
                "address1": "407 St. John Street",
                "city": "London",
                "postalCode": "EC1V 4AB",
                "country": "GB"
            },
            "entryMethod": "Ecommerce",
            "credentialType": 
            {  
                "cofUsage": "Subsequent",
                "initiatedType": "MIT",
                "mitType": "Unscheduled" 
      },
        }'