Tokenization Services

Saving card details for faster checkout, subscription payments and other payments agreed with customer

 

With Netaxept tokenization services you can get your customers' card details saved easily and securely for future subsequent transactions. Currently our services include:

  • Easy payment: Solution for faster checkout experience. The customer pays the following transactions without the need of entering card details again during the checkout. Applicable especially for mobile applications where it makes the checkout process faster and eases the customer's purchase experience.

  • Recurring Payment: A transaction in a series of transactions that use a stored credential for a fixed amount and that are processed at fixed, regular intervals, and and where the customer has provided consent for the merchant to initiate one or more future transactions. For example TV streaming subscription with the same monthly bill.

  • Unscheduled COF: A transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date, and and where the customer has provided consent for the merchant to initiate one or more future transactions. For example mobile phone subscription where the bill changes depending on the usage of minutes, SMS or data or an automatic top-up agreement for a railcard, when the customer drops below a certain stored value.

  • Delayed charge: A transaction performed to process a supplemental account charge after original services have been rendered and respective payment has been processed. For example when a hotel needs to charge minibar expenses from the customer after they have already paid the original bill and checked out from the hotel.

  • No-show: A transaction occurring when merchant and customer have an agreement for a purchase, but the customer does not meet the terms of the agreement. For example when the customer has booked a hotel room but doesn’t cancel the reservation according to the hotel’s cancellation policy. The hotel may then perform a no-show transaction to charge the customer a penalty for a guaranteed reservation.

To be able to utilize these solutions via Netaxept, besides the technical API integration towards Netaxept, you need to have the correct additional service chosen in your Netaxept agreement. Also, make sure you have signed the necessary agreements with your chosen acquirer and agreed the possible changes in CVV/CVC security code handling.

 

Definition and use of tokens

Easy Payment and Recurring Payments are based on tokenization. After the initial transaction, Netaxept will generate a token referring to the transaction. When performing subsequent transactions, you need to refer to this token to allow the card to be captured without sending all the card information again. In the API the token can be found in the parameter name panHash under the Register call and the Query call. The panHash does, contrary to its name, not contain any part of the PAN (card number), nor is it a value calculated based on the PAN. Also, it is not considered as a hash value. Instead, it is a randomly generated sequence, adhering to PCI DSS standard and stored safely in the PCI certified environment at Nets. It is the merchant's responsibility to store tokens in a secure way in their systems and restrict access to data on a need to know basis. The merchant undertakes not to store tokens on a frontend system exposed to the internet or directly on mobile devices.

The tokens used in Easy Payment and Recurring Payments have the identical formats. However, they are not interchangeable. Instead, the token in question can only be used for the same recurring type (meaning Easy Payment or Recurring Payments) it was initially created for. Also, it is good to note that Netaxept clears regularly its database due to which tokens with the following criteria are made unavailable and cannot be used anymore:

  • Tokens created more than 1100 days ago
  • Tokens for recurring payments with expiration date in the past

 

Initial card registration

For both Easy Payment and Recurring Payments, there are two alternatives to generate a token and register the card in Netaxept for later purchases.

Create token together with a purchase

If you decide to create a token together with an initial purchase, follow the regular payment flow for authorising and capturing a payment. Include the recurring related parameters into the calls as specified below in the chapters Easy Payment and Recurring Payments.

Create token without performing a purchase

If you prefer to create a token without performing an actual purchase, follow the instructions below.

In the Register call, besides recurring parameters, set updateStoredPaymentInfo="true". When set to "true", the payment window hosted by Netaxept will be changed to reflect the fact that the customer is not completing a full transaction, rather saving their card details for future transactions. In practice, the transaction amount and order description text are not displayed in the payment window, and instead of "Pay" button, the customer will see "Register" button as to register their card. Also, when using updateStoredPaymentInfo="true", amount is not mandatory parameter in the Register call. However, it doesn’t matter if the amount is still sent along the Register call, it will be then just ignored by Netaxept.

After the successful Terminal phase, instead of using the AUTH, CAPTURE or SALE operations in the Process call, use the VERIFY operation if it is supported by the payment method used. The VERIFY is used in place of AUTH when registering a card, to confirm that the card is valid and can be saved for future use. After performing the Process(Verify) call, the other Process calls (CREDIT, CAPTURE, SALE, ANNUL) cannot be used and will return "Not Supported" exception.

Fetch token

No matter whether you have performed an actual purchase or only a card registration, after the Process call, run the Query call on the transaction, to find the token from the parameter panHash. Store this token value on the customer profile for later transactions. We also recommend storing the name of the card issuer and the last 4 digits of the card number to give the customer an indication of the card you have stored for their profile. We also recommend saving the expiry date of the card so that you can inform the customer shortly before the card expires and ask them to register a new card.

 

Easy Payment

Initial transaction

Start the payment process by running the Register call, as with a regular transaction, and include the following parameters in the Register call.

  • recurringType="S"
  • updateStoredPaymentInfo="true", use this if the initial transaction is only a card registration

After the successful Register call, perform the Terminal call to send the customer to the payment window. During this phase, customer is also redirected to 3D Secure or equivalent authentication. After the customer has successfully passed the Terminal phase, Netaxept generates a token for the transaction. However, do not fetch the token until you have received the successful response for the Process call.

After the successful Terminal phase, run the chosen Process call(s). The operation varies whether this is an actual payment or only a card registration.

  • If it is an actual payment, perform the operations AUTH and CAPTURE or SALE as with a regular transaction.
  • If it is a card registration with updateStoredPaymentInfo="true" specified in the Register call, perform the operation VERIFY, or AUTH and ANNUL instead.

When this stage is done, run the Query call on the transaction to find the token, as described above.

Subsequent transactions

When performing the subsequent transaction, send the following parameters along the Register call.

  • panHash=[stored token]
  • recurringType="S"
  • recurringUse3DS="true", use this so that the customer is redirected to 3D Secure authentication
  • serviceType="B", use this to get 3D Secure authentication triggered and the customer redirected to the terminal to enter their CVV/CVC
  • serviceType="M", use this to get 3D Secure authentication triggered and the terminal and CVV/CVC entry bypassed

Depending on your agreement with your chosen acquirer you may or may not have to ask the customer for the CVV/CVC security code for each transaction. Easy Payment on Netaxept side supports both variants. Certain industries have an exemption from using the CVV/CVC security code so please consult your chosen acquirer for further information.

After the successful Register call, perform the Terminal call to redirect the customer to 3D Secure or equivalent authentication. After the customer has successfully passed the Terminal phase, continue with the Process call and choose either operation AUTH and CAPTURE or SALE as with a regular transaction.

Recurring Payments

Initial transaction

Start the payment process by running the Register call, as with a regular transaction, and include the following parameters in the Register call.

  • recurringType="R"
  • recurringFrequency="X"
  • recurringExpiryDate="YYYYMMDD"
  • updateStoredPaymentInfo="true", use this if the initial transaction is only a card registration

Recurring frequency indicates how often the merchant may make subsequent payments on the card registered. A frequency of "1" will indicate that one payment is allowed each day, while "28" would be the recommended value for monthly subscriptions, to allow for the 28 days in February. If more than one payment should be possible daily, a recurring frequency of "0" can be used. Recurring expiry date is the date when the agreement between the merchant and the customer expires. This value must be registered on the format YYYYMMDD.

After the successful Register call, perform the Terminal call to send the customer to the payment window. During this phase, customer is also redirected to 3D Secure or equivalent authentication. After the customer has successfully passed the Terminal phase, Netaxept generates a token for the transaction. However, do not fetch the token until you have received the successful response for the Process call.

After the successful Terminal phase, run the chosen Process call(s). The operation varies whether this is an actual payment or only a card registration.

  • If it is an actual payment, perform the operations AUTH and CAPTURE or SALE as with a regular transaction.
  • If it is a card registration with updateStoredPaymentInfo="true" specified in the Register call, perform the operation VERIFY, or AUTH and ANNUL instead.

When this stage is done, run the Query call on the transaction, to find the token, as described above.

Subsequent transactions

When performing the subsequent transaction, send the following parameters to Netaxept along the Register call.

  • panHash=[stored token]
  • recurringType="R"
  • serviceType="C"

After the successful Register call, skip the Terminal phase and continue directly with the Process call choosing either operation AUTH and CAPTURE or SALE as with a regular transaction.

 

Best practices

The following are our recommended best practises for Easy Payment and Recurring Payments.

  • Remember to URL-encode all API parameters sent to Netaxept.
  • You must always obtain the customer's permission to register their card and charge the card for later purchases. For example, you can require the customer to check a box stating similar to: "I approve that my card is stored and charged for later purchases. The card number is stored securely with our payment provider Nets and we will never have access to the actual card number".
  • You should state clearly how the recurring agreement can be cancelled.
  • It is recommended to send either a pre-notification email some days before the charge is done or an electronic receipt immediately when the charge is approved. This is to avoid unnecessary chargeback claims.
  • The token is a valuable asset and must always be stored in a secure way. The merchant undertakes not to store tokens on a frontend system exposed to the internet or directly on mobile devices.
  • Password requirements for customer profiles on applications in use must always use highest complexity requirements (including numbers, alphanumerics, special characters and upper/lower case). Do not store passwords in clear text on your application.
  • Use logging of IP address and where applicable IMEI for mobile devices for purchases.
  • Use transaction filter offered by Netaxept to limit the number of transactions per day and card.
  • Be aware that transactions running on Easy Payment and Recurring Payments mode without 3D Secure are not covered by the acquirers settlement guarantee so it is in your interest to build a secure solution.
  • If you have a large amount of small transactions (like download of digital content), the acquirer might accept that you aggregate transactions to one single charge as long as they are not over 25 USD in total, and not collected over a period of more than 7 days.
  • For Recurring Payments you need to sign a separate agreement with your chosen acquirer.
  • For Easy Payment you need a regular Internet agreement with your chosen acquirer. Make sure to agree with the acquirer whether the solution should run with or without entering CVV/CVC security code for each transaction.

 

Example of the Easy Payment flow

Below you can find an example of Easy Payment including initial card registration and the account verification. During the subsequent transaction the customer is directed to the payment window for entering their CVV/CVC security code.

Merchant sends the Register call for the initial transaction to Netaxept:
https://test.epayment.nets.eu/Netaxept/Register.aspx?merchantId=[MERCHANTID]&token=[APITOKEN]&orderNumber=Testtransaction&amount=100&currencyCode=EUR&servicetype=B&updateStoredPaymentInfo=true&language=en_GB&redirectUrl=http://www.test.eu&recurringtype=S

Merchant receives the RegisterResponse from Netaxept:
<RegisterResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<TransactionId>121a96aee9754de7810d19620feb17e9</TransactionId>
</RegisterResponse>

Merchant sends the Terminal call to Netaxept:
https://test.epayment.nets.eu/Terminal/default.aspx?merchantId=[MERCHANTID]&transactionId=121a96aee9754de7810d19620feb17e9

After the terminal phase customer is redirected to the URL specified in the Register call:
https://www.test.eu/?transactionId=121a96aee9754de7810d19620feb17e9&responseCode=OK

Merchant sends the Process (VERIFY) call to Netaxept:
https://test.epayment.nets.eu/Netaxept/Process.aspx?merchantId=[MERCHANTID]&token=[APITOKEN]&operation=VERIFY&transactionId=121a96aee9754de7810d19620feb17e9

Merchant receives the ProcessResponse from Netaxept:
<ProcessResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<AuthorizationId>027340</AuthorizationId>
<ExecutionTime>2017-09-27T15:17:02.0935373+02:00</ExecutionTime>
<MerchantId>[MERCHANTID]</MerchantId>
<Operation>VERIFY</Operation>
<ResponseCode>OK</ResponseCode>
<TransactionId>121a96aee9754de7810d19620feb17e9</TransactionId>
</ProcessResponse>

Merchant sends the Query call to Netaxept to fetch the token:
https://test.epayment.nets.eu/Netaxept/Query.aspx?merchantId=[MERCHANTID]&token=[APITOKEN]&transactionId=121a96aee9754de7810d19620feb17e9

Merchant receives the Query response from Netaxept:
<PaymentInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<MerchantId>[MERCHANTID]</MerchantId>
<QueryFinished>2017-09-27T15:17:54.9428568+02:00</QueryFinished>
<TransactionId>121a96aee9754de7810d19620feb17e9</TransactionId>
<AuthenticationInformation/>
<AvtaleGiroInformation/>
<CardInformation>
<ExpiryDate>1801</ExpiryDate>
<Issuer>Visa</Issuer>
<IssuerCountry>NO</IssuerCountry>
<MaskedPAN>492500******0004</MaskedPAN>
<PanHash>[STOREDTOKEN]</PanHash>
<PaymentMethod>Visa</PaymentMethod>
<IssuerId>3</IssuerId>
</CardInformation>
<CustomerInformation>
<Address1/>
<Address2/>
<CompanyName/>
<CompanyRegistrationNumber/>
<CustomerNumber/>
<Country/>
<Email/>
<FirstName/>
<IP>12.123.12.1</IP>
<LastName/>
<PhoneNumber/>
<Postcode/>
<SocialSecurityNumber/>
<Town/>
</CustomerInformation>
<ErrorLog/>
<History>
<TransactionLogLine>
<DateTime>2017-09-27T16:13:00.223</DateTime>
<Description/>
<Operation>Register</Operation>
<TransactionReconRef/>
</TransactionLogLine>
<TransactionLogLine>
<DateTime>2017-09-27T16:17:02.093</DateTime>
<Description>12.123.12.1</Description>
<Operation>Account verification</Operation>
<TransactionReconRef/>
</TransactionLogLine>
</History>
<OrderInformation>
<Amount>100</Amount>
<Currency>EUR</Currency>
<Fee>0</Fee>
<OrderDescription></OrderDescription>
<OrderNumber>Testtransaction</OrderNumber>
<Timestamp>2017-09-27T16:13:00.223</Timestamp>
<Total>100</Total>
<RoundingAmount>0</RoundingAmount>
</OrderInformation>
<Recurring>
<Type>Store (Init)</Type>
<Frequency/>
<ExpiryDate/>
<PanHash>[STOREDTOKEN]</PanHash>
</Recurring>
<SecurityInformation>
<CustomerIPCountry>NO</CustomerIPCountry>
<IPCountryMatchesIssuingCountry>true</IPCountryMatchesIssuingCountry>
</SecurityInformation>
<Summary>
<AmountCaptured>0</AmountCaptured>
<AmountCredited>0</AmountCredited>
<Annuled>false</Annuled>
<Annulled>false</Annulled>
<Authorized>false</Authorized>
</Summary>
<TerminalInformation>
<Browser>
Chrome-Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/61.0.3163.100 Safari/537.36
</Browser>
<CustomerEntered>2017-09-27T15:14:16.697</CustomerEntered>
<CustomerRedirected>2017-09-27T16:16:16.850</CustomerRedirected>
</TerminalInformation>
<Wallet>
<Issuer>EasyPayment</Issuer>
</Wallet>
</PaymentInfo>

Merchant sends the Register call for the subsequent transaction to Netaxept:
https://test.epayment.nets.eu/Netaxept/Register.aspx?merchantId=[MERCHANTID]&token=[APITOKEN]&orderNumber=Testtransaction&amount=200&currencyCode=EUR&servicetype=B&language=en_GB&redirectUrl=http://www.test.eu&recurringtype=S&panHash=[STOREDTOKEN]

Merchant receives the RegisterResponse from Netaxept:
<RegisterResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<TransactionId>454a0144086c4f718a97a4a11b7bfb57</TransactionId>
</RegisterResponse>

Merchant sends the Terminal call to Netaxept:
https://test.epayment.nets.eu/Terminal/default.aspx?merchantId=[MERCHANTID]&transactionId=454a0144086c4f718a97a4a11b7bfb57

After the terminal phase customer is redirected to the URL specified in the Register call:
https://www.test.eu/?transactionId=454a0144086c4f718a97a4a11b7bfb57&responseCode=OK

Merchant sends the Process (SALE) call to Netaxept:
https://test.epayment.nets.eu/Netaxept/Process.aspx?merchantId=[MERCHANTID]&token=[APITOKEN]&operation=SALE&amount=200&transactionId=454a0144086c4f718a97a4a11b7bfb57

Merchant receives the ProcessResponse from Netaxept:
<ProcessResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<AuthorizationId>027360</AuthorizationId>
<BatchNumber>642</BatchNumber>
<ExecutionTime>2017-09-27T15:27:20.1079944+02:00</ExecutionTime>
<MerchantId>[MERCHANTID]</MerchantId>
<Operation>SALE</Operation>
<ResponseCode>OK</ResponseCode>
<TransactionId>454a0144086c4f718a97a4a11b7bfb57</TransactionId>
</ProcessResponse>