Easy Payment and Recurring Payments

Fast and easy payments with one click or a regular basis

 

This page gives you instructions needed for a fluent implementation of solutions that enable to perform subsequent transactions on a card. 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.

  • Easy Payment: After the initial transaction, the customer can initiate the following transaction by logging in to your webshop or mobile app and paying simply with one click or by entering their card's CVV/CVC security code. Easy Payment is applicable especially for mobile applications where it eases the customer’s purchase experience significantly.
  • Recurring Payments: After the initial transaction, you as a merchant can charge the customer's preferred card at specific times based on the agreement you have made with the customer. Recurring Payments is applicable especially for paying subscriptions, membership fees and other regular payments, without the need of customer interaction after the initial payment.

 

Definition and use of tokens

Easy Payment and Recurring Payments are based on the use of token. 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 payment 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) as 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
  • Tokens for recurring payments not used for more than 735 days

 

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 this variable is 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 registering their card 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. The VERIFY is used in place of AUTH when registering a card, to confirm that the card is current and can be stored 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 parameter recurringType="S" in the Register call. If this is only a card registration, include also updateStoredPaymentInfo="true" in the Register call, as described above.

After the successful Register call, perform the Terminal call to send the customer to the payment window. During this phase, the 3DS authentication is performed as well unless it has been waived by your chosen card acquirer. 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 operations used is depending on if this is an actual payment or only a card registration.

  • If this is an actual payment, perform the operations AUTH and CAPTURE or SALE as with a regular transaction.
  • If this 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="S"
  • serviceType="B" use this if the customer needs to enter their CVV/CVC security code
  • serviceType="C" use this if you are allowed to process the transaction without CVV/CVC security code

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 if needed. If you need to ask the customer for the CVV/CVC security code, perform the Terminal call first and then continue with the Process call and choose either operation AUTH and CAPTURE or SALE as with a regular transaction. If the CVV/CVC security code is not required, skip the Terminal phase and after successful Register call continue directly with the Process call. Please note that Easy Payment without entering the CVV/CVC security code for subsequent transactions does not work with Dankort due to the technical restrictions. If implementing this functionality for Dankort, you need to follow the instructions for Recurring Payments that give the same user experience and functionality.

If you want to redirect customer to perform 3D Secure authentication for subsequent transactions as well, then send the parameter recurringUse3DS along the Register call and set the parameter to ”true”. Otherwise subsequent payments with stored cards are non-3DS authenticated.

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. If this is only a card registration, include also updateStoredPaymentInfo="true" in the Register call, as described above.

  • recurringType="R"
  • recurringFrequency="X"
  • recurringExpiryDate="YYYYMMDD"

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, the 3DS authentication is performed as well unless it has been waived by your chosen card acquirer. 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 operations used is depending on if this is an actual payment or only a card registration.

  • If this is an actual payment, perform the operations AUTH and CAPTURE or SALE as with a regular transaction.
  • If this 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, continue with the Process call and choose 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.
  • The initial transaction is recommended to be done from a PC as long as you use 3D Secure authentication.
  • 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.
  • Some acquirers will demand that the solution runs on 2 separate merchant IDs. One for the first 3D Secure transaction and a separate one for the subsequent transactions.

 

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>