Network Tokens

Token Provisioning

Card schemes provide CardNetworkTokenization services by certified provider. A full PAN will be tokenized by a certified NTS (Network Token Service). The NTS keep the card details secure and provides services to decrypt the token / cryptogram for processing. A token works equal to the PAN, can only be detokenized by the token provider before the card details are used for processing.

The Tokenization API currently supports network tokenization through MasterCard and Visa.

The network tokenization solution uses the payment brand's, and potentially other, token providers to tokenize card information in a way that allows the token to be used in payment transactions without the need to de-tokenize it before initiating payment processing. This same token is then used in any subsequent actions related to initial payment including clearing, settlement, refunds and dispute processing.

Process Flow

1. Your server initializes a new Network Token provisioning by sending Create Network Token request to SmartPay API.
2. Your server forwards the tokenId to your client for initialization of the SmartPay Network Tokenization SDK.
3. The customer securely submits their payment information via the initialized Credit Card collection form which communicates to the Network Tokenization service for token provisioning and provides a JavaScript callback once finished.
4. Your client triggers your server to verify whether the token provisioning was successful, based on the JavaScript callback, by calling the Get Network Token API and verifies its status.

Initiate Token Provisioning

Network token provisioning process starts with Crate Token API request with the following structure.

info

Sample below shows Token Creation request for following credit card collection and provisioning. Please refer to our Network Tokens page for full explanation of this API method.

Request

Path:

POST {Base URL}/network-tokens

Header:

Content-Type: application/json
Accept-Language: en-US

{
    "integrationFlow": "payment-form",
    "accountReferenceId": "7a854cb5-48c6-4a9c-955d-4eec5145bc6e",
    "accountCategory": "EWalletUser",
    "currencyCode": "EUR",
    "billingAddress": {
        "addressLine1": "259 Destiny View.",
        "addressLine2": "909 Deshaun Prairie",
        "city": "Independence",
        "countryCode": "DE",
        "number": "44",
        "postCode": "40233",
        "homePhone": "759146905"
    },
    "shippingAddress": {
        "addressLine1": "759 London Path.",
        "city": "South Bryanastad",
        "countryCode": "DE",
        "number": "44",
        "postCode": "400606",
        "homePhone": "76374"
    },
    "consumer": {
        "dateOfBirth": "1986-03-11",
        "title": "Mr",
        "mobilePhone": "838792",
        "culture": "de-DE",
        "firstName": "Kenyatta",
        "lastName": "Sawayn",
        "emailAddress": "Brooks.Crooks76@gmail.com"
  }
}

tip

The Create Token response includes the 36-character GUID of the tokenId.

Response

{
    "tokenId": "687ee565-aea1-4d63-97dc-b9b02f0c9075",
    "createdAt": "2023-03-20T15:39:30.969Z",
    "updatedAt": "2023-03-20T15:39:30.969Z",
    "authorizationId": "4211a1cd-a868-471f-8158-965d8c96d891",
    "externalMerchantId": "9ff980b6-1fc6-4b61-9957-f8655b04cd9d",
    "status": "PENDING_PAYMENT_FORM"
}

important

The tokenId should be associated and persisted with provisioned network token within the integrated solution. This should be accessible to support staff and initially testers to submit any service requests relating to the integration process to help speed up the analysis.

Render Network Tokenization SDK for Card Data Collection

Our SmartPay SDKs are made up of light-weight libraries which allow to securely collect credit card details. This approach maintains a SAQ-A compliant payment-form solution while enabling you to build forward compatible experience which seamlessly combine your corporate identity with the required functionalities whilst adding some additional ancillary functions to ease integration.

Web Checkout

Get Network Token Status

The Network Tokenization SDK as a result of form rendering returns the result of the token provisioning in promise object when the render function was executed. The promise can be handled by the integrator in order to do any additional steps. This should be the trigger for your server (backend) to call the Get Network Token API to verify the status of the provisioned token as depicted in the example below.

Request

Path:

GET {Base URL}/network-tokens/{tokenId}

Header:

Content-Type: application/json
Accept-Language: en-US

Evaluate the response parameter "status" which should be:

• "ACTIVE" if the token has been provisioned successfully and became available for payments
• "ERROR" if the token provisioning has failed

Network token is returned in the field networkToken\tokenNumber. Can be used for cryptogram requesting during the payments.

tokenNumber, tokenReferenceIdentifier and tokenId must be stored for further requests or webhooks processing.