Digital Payments – Network Tokenization

What Is Network Tokenization?

The reason behind network tokenization is to shift the processing of stored cards from card numbers (PAN) to tokens. Card details are replaced by the token and a cryptogram.

The tokens are generated by the card networks (Visa and MasterCard) when an end-user signs up for a service using a stored card. Tokens are global within the network, where Merchants, PSPs and issuers can connect to them. The merchant and PSP are provided with the token attached to a card, while the issuer is able to update the card information attached to the token. The result is a token which lives after a card expires, since the card information connected to it is updated seamlessly by the issuer.

This will improve the user experience for the end-user, as they no longer have to take action when their card reaches the expiry date. As the card connected to the token will be valid at all times, this will reduce churn and improve approval rates for merchants and PSPs as well, especially for subscription and one-click services.

How It Works

This functionality is available through both our payment order implementations and card implementation for recurring transactions, one-click and unscheduled purchases. We strongly recommend paymentOrder to ensure that you get access to capabilities coming in later deliveries, such as card art, shared tokens and notifications. It is only available with Swedbank Pay as acquirer for the time being.

When you choose to add this functionality, we activate Network Tokenization for your merchant account and initiate onboarding towards VISA and Mastercard. Once we get onboarding confirmation from Visa and Mastercard, Network Tokenization will be enabled and used for future card storage and stored card processing. Cards that have previously been stored with card details only, will be network tokenized next time they are charged.

Once the setup is completed, the transactions themselves run as normal unscheduled, one-click or recurring purchases. The difference is that Network Tokenization replaces the card number behind the token.

Do you want to give it a go? Test cards and a guide is in the test data section.

Recommendations To You As A Merchant

If you are displaying the last four digits of your customers stored cards, we highly recommend refreshing these numbers when a card has been updated or replaced by the issuer. This would help the customer to understand that a new and valid card is stored. It is also recommended that you add information that the card has been updated automatically by the issuer. Retrieving the updated card information is done using payerOwnedTokens, and should be done when the end-user logs in, goes to “My cards” or at a similar point that makes sense in your portal.

The GET request to retrieve updated card information should look similar to this.

GET Tokens Request

1
2
3
4

GET /psp/paymentorders/payerownedtokens/<payerReference> HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0      // Version optional for 3.0 and 2.0 

GET Tokens Response

1
2
3

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.x/2.0
api-supported-versions: 3.x/2.0

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

{
  "payerOwnedTokens": {
        "id": "/psp/paymentorders/payerownedtokens/{payerReference}",
        "payerReference": "{payerReference}",
        "tokens": [
            {
                "token": "{token}",
                "tokenType": "Unscheduled",
                "instrument": "CreditCard",
                "instrumentDisplayName": "492500******0004",
                "correlationId": "e2f06785-805d-4605-bf40-426a725d313d",
                "instrumentParameters": {
                    "expiryDate": "12/2025",
                    "cardBrand": "Visa",
                    "lastFourPan": "0004",
                    "lastFourDPan": "8188",
                    "issuerName": "BankName"
                },
                "operations": [
                    {
                        "method": "PATCH",
                        "href": "https://api.internaltest.payex.com/psp/paymentorders/unscheduledtokens/e2f06785-805d-4605-bf40-426a725d313d",
                        "rel": "delete-unscheduledtokens",
                        "contentType": "application/json"
                    }
                ]
            }
        ]
    },
    "operations": [
        {
            "method": "PATCH",
            "href": "https://api.internaltest.payex.com/psp/paymentorders/payerOwnedPaymentTokens/{payerReference}",
            "rel": "delete-payerownedtokens",
            "contentType": "application/json"
        }
    ]
}

Field	Type	Description
`instrumentParameters`	`integer`	A list of additional information connected to the token. Depending on the payment method, it can e.g. be `expiryDate`, `cardBrand`, `email`, `msisdn` or `zipCode`.
`expiryDate`	`string`	The expiry date of the card currently connected to the network token.
`cardBrand`	`string`	The brand of the card currently connected to the network token.
`lastFourPan`	`string`	The last four digits of the PAN connected to the network token.
`lastFourDpan`	`string`	The last four digits of the DPAN (Network Token).
`issuerName`	`string`	The name of the issuer.

We advise you to implement automatic deletion of tokens when end-users choose to end the service with the you. This is to avoid unnecessary cost on your end, as you are invoiced monthly for each active token.
Please note that the new field maskedDpan is present when using Network Tokenization. DPAN is the network token representing the card and thus, maskedDpan is a masked version of the network token. It will only appear if the card is tokenized by Visa or Mastercard. The end-user will not normally know what maskedDpan is or that it’s being used, but you as a merchant need to keep track of it. See the Paid resource for cards.