Token

Overview

Tokenization is a key player in keeping sensitive payment info safe. Replacing the actual card details with unique symbols called tokens. These tokens hold all the important payment details without risking security, while the data secured in a token vault.

You can handle payments without ever touching the sensitive card data. This keeps you on the right side of payment industry rules (PCI compliance) and simplifies your security checks (SAQ-A).

What is a Token?

Think of a token as a stand-in for your saved payment details. Once you've got one, you can use it for future purchases instead of entering your card info every time. Tokens look a lot like regular card numbers and can pass basic card checks, so they fit right into existing payment systems.

When creating tokens, the system tries to make them look like invalid card numbers. This adds an extra layer of protection, just in case someone stumbles upon a token they shouldn't have.

Create a Token

To tokenize a payment source, you need to initiate a session. Once you have presented the payment fields and the user has submitted their payment information, you can use that sessionId to generate a token by calling on the Create Token endpoint.

Create Token

curl --request POST 'https://test-lighthouse.prahsys.com/api/rest/version/82/merchant/{{merchantId}}/token' \
     --header 'Content-Type: application/json' \
     --data '{
         "session": {
             "id": "{{session.id}}"
         }
     }'

Using a Token

After generating a token, you can use it for future payments. For example, if you were to authorize a new order for a payment, for the sourceOfFunds you would use the generated token from the previous successful order for the customer.

Looking at the response, you can see that the sourceOfFunds object contains the token that was used for the payment and the card details associated with that payment.

The type tells you what payment source was used. If you were to authorize the payment with a Hosted Checkout, then the payment sourceOfFunds.type would be CARD. For this case, because we are using a token to authorize the payment it is set to SCHEME_TOKEN because we authorized the payment with a token.

Source of Funds

{
  {
    //... other fields
    "sourceOfFunds": {
      "token": "{{tokenId}}",
      "type": "SCHEME_TOKEN",
      "provided": {
        "card": {
          "brand": "VISA",
          "expiry": {
            "month": "1",
            "year": "24"
          },
          "fundingMethod": "CREDIT",
          "number": "554321xxxxxx0001"
        }
      }
    }
  }
}

Authorize Payment Request with token

curl --request PUT '/merchant/{{merchantId}}/order/{{orderId}}/transaction/{{transactionId}}' \
     --header 'Content-Type: application/json' \
     --data '{
        "apiOperation": "AUTHORIZE",
        "order": {
           "amount": "100.00",
           "currency": "USD"
        },
        "sourceOfFunds": {
           "type": "SCHEME_TOKEN",
           "token": "{{tokenId}}" <--- Pass the saved token ID here
        }
     }'

Token or Store Card on File

When creating a session for an order, you can set a property called saveCardForCredentialOnFile to PAYER_INITIATED_PAYMENTS that will present a consent checkbox to the payer upon checkout. If the payer consents, the card details will be stored in the vault and this payment source will be presented the next time you present the payment fields.

This is different from Tokenizing the payment source after a user has submitted their payment information. When you tokenize a payment source, you are personally keeping a unique token id attached to that payment source.

saveCardForCredentialOnFile is a way to expedite payment processing for the payer, while tokenization is a way to keep the payment source secure for later use.

FAQ

Can I Use a Token for Different Merchants?

No, tokens are tied to the merchant that created them. If you want to use a token for a different merchant, you'll need to create a new token with the new merchant's ID.

Can I Use a Token More Than Once?

Yes, you can use a token for multiple transactions. Tokens are reusable until they are deleted.

Do Tokens Expire?

Tokens don't expire, but they can be deleted. If you don't want to use a token anymore, you can delete it from the system by using the Delete Token endpoint.

Should I Store the Token?

Yes, you should store the token if you plan to use it for future transactions. It is useful if you are setting up a subscription, payment plan, or any other recurring payment.

Can I Use a Token for different orders?

Yes, you can use a token for different orders. Tokens are reusable until they are deleted.