Skip to content

    Tokenization

    To refer to previously stored payment details and use them for services such as Easy Payment and Recurring Payments, Netaxept uses Tokenization.

    Stored cards (card-on-file)

    Card-on-file transactions

    Storing card details, also known as Card-on-file, enables customers to save their payment information with merchants and have quicker checkouts, subscriptions, and other services. In these transactions, a customer's payment card data is securely stored for future use, with their consent. Card-on-file relies on tokenization to encrypt and securely store sensitive customer card information. Tokenization replaces card numbers with unique, randomly generated tokens, which can be used for payments without exposing the actual card number.

    Card-on-file transactions can be initiated by both merchants and consumers:

    • Merchant-initiated card-on-file transactions: Merchants initiate these transactions with the consent of customers who have previously interacted with them. MITs can be used for a variety of purposes, such as subscription fees, unscheduled card-on-file transactions, and installment payments.

    • Cardholder-initiated card-on-file transactions: These occur when a customer uses their previously stored card information to make a purchase, eliminating the need for manual input of card details. This is frequently used in one-click payments, ensuring a swift and convenient checkout process. To enhance security, these payments often require authentication through 3D Secure.

    Services with stored cards

    With Netaxept, you can securely store customer card details for future payments. To store cards with your customers agreement allows you to offer the following services:

    • Easy payment: returning customers do not have to enter their payment details again. Example: One-click transactions where a customer can store their payment details upon their first purchase and pay in the website or app later using their saved details.
    • Recurring payments: a transaction in a series of transactions. The amount of recurring payments is fixed as well as the intervals of the payment. Its based on the customer's consent to allow the merchant to initiate one or more future transactions. Example: TV streaming subscription with the same monthly bill.
    • Unscheduled Card on File: contrary to recurring payments, the amount and the schedule of the transaction can be flexible. Examples: Automatic top ups of railcards or mobile phone subscriptions, where the bill changes according to amount of minutes used.
    • Delayed charge: allows supplemental acccount charge after the initial payment has been processed. Example: A hotel needs to charge minibar expenses on top of the (already paid) original bill.
    • No-show: allows a no-show-transaction. Usually used for fees that occur because the customer does not meet the terms of an agreement. Example: Customer has booked a hotel room but does not cancel the booking according to the hotel's cancellation policy.

    Definition and use of tokens

    We refer to saved payment details as tokens and storing a customer's payment details as tokenization.

    After the initial transaction, Netaxept will generate a token referring to the payment details used for this transaction. When performing subsequent transactions, you need to refer to this token with the Register call panHash parameter, to allow the card to be captured without sending all the card information again.

    The panHash parameter does not, as the name might suggest, contain any part of the PAN (card number), nor is it a value calculated based on the PAN. Also, it is not considered 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 your responsibility to store tokens in a secure way and to restrict access to it. This data mustn't be exposed on the frontend.

    Saved tokens in Netaxept's database become unaccessible, if they have been created more than 1100 days ago, or when the recurring payments token's expiration date has passed.

    Tokens can be created during a purchase as well as independently of a purchase. To create a token during a purchase, the regular payment flow for authorising and capture remains the same. Only the recurring payments related parameters have to be added to the calls. For additional information, refer to payment flow.

    The payment has to be processed successfully with process call before storing the token (panHash) for future charges. Those tokens that are stored without being processed successfully do not comply with the card scheme requirements and may result in an increased number of declines for subsequent transactions.

    Create a token without a purchase

    You can create a token without charging the customer. This may be required, for example, if the customer does not make a payment during the card registration phase or when the card expiry date changes and you need to update stored card details. For this, pass updateStoredPaymentInfo=true parameter in the Register call. That will change the Netaxept hosted payment window, so that the customer card details can be entered without a related payment.

    When using updateStoredPaymentInfo="true", the amount is no longer a mandatory parameter in the Register call. If an amount is sent with the Register call it will be ignored.

    After the Terminal call, send Process(VERIFY) call. Verify makes a zero-amount authorization request to the card to verify a customer's account status.

    The Process(VERIFY) call does not work for all payment cards. See payment methods section to learn about what payment methods are applicable.

    RegisterCardPaymentWindow2

    The transaction processing phase is a mandatory step in tokenization and should always be done before storing the token for future use.

    After a successful process call, run the Query call on that specific transaction to retrieve the token from the panHash parameter of the Query call response.

    You must store this token as part of your stored customer profile for later transactions.

    In addition to that, we recommend you store the card issuer's name and the last 4 digits of the card number to give the customer an indication of the card you have stored. We also recommend to save the expiration date of the card and to make sure the card get's updated (or replaced) before that.

    Easy payment

    Saving customer payment information and allowing them to make future transactions with fewer clicks.

    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 without a payment

    After the successful Register call, perform the Terminal call to send the customer to the payment window.

    During terminal phase, customer is redirected to 3D Secure or equivalent authentication. Strong Customer Authentication (SCA) is required for initial card-on-file transaction.

    Netaxept generates a token for the transaction, after the customer has successfully passed the Terminal phase.

    After the Terminal call response, you send the Process call (AUTH, CAPTURE or SALE) as usually.

    If it is a card registration with updateStoredPaymentInfo="true" specified in the Register call, perform process call VERIFY (or AUTH and ANNUL) instead.

    Only after that has been accomplished, you can collect the token from the response to the Query call on this transaction.

    Subsequent transactions

    Now that you have the token, you can allow your customers to pay without entering their payment details again.

    For this, the following parameters must be added to the Register call:

    • panHash=[stored token]
    • recurringType="S"
    • recurringUse3DS="true", redirects the customer to 3D Secure authentication

    as well as:

    • serviceType="B" gets 3D Secure authentication triggered and the customer redirected to the terminal to enter their CVV/CVC OR
    • serviceType="M", gets 3D Secure authentication triggered and both, terminal and CVV/CVC entry bypassed
    AskCVVPaymentWindow2

    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

    The Recurring payments give you the ability to setup recurring charges on a periodical basis, such as monthly or weekly. The amount in recurring payments is fixed as well as the interval of the payment. It is based on the customer consent to allow you to initiate one or more future transactions.

    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

    The recurringFrequency indicates how often you want to 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 (so that February with 28 days is included).

    If more than one daily payment should be possible daily, a recurring frequency of "0" can be used.

    recurringExpiryDate 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 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 & ANNUL only for cards that do not support VERIFY).

    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 with 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.

    Merchant initiated transactions

    A Merchant Initiated Transaction (MIT) refers to a card payment started by a merchant without the customer being actively involved, as part of an agreement made during an initial Customer-initiated Transaction (CIT). Payments done with changing amount and/or frequency, for example, Unscheduled Card on File (UCOF), delayed charge and no-show transactions.

    In order to categorize a payment as a merchant initiated transaction, you must have a mandate from your customer to initiate the payment or a series of payments.

    Initial transaction

    Consumer saves card details for later charges initiated by merchant. The first transaction can be either a card registration only (account verification with zero-value) or the actual purchase.

    SCA is required for initial transaction. Netaxept redirects the customers automatically to SCA after you have performed the Terminal call. To make sure the issuer doesn't apply exemption and thus leave your initial transaction without SCA, send force3DSecure="true" in the Register call.

    1. Register call:

    force3DSecure="true" - SCA required to complete transaction

    updateStoredPaymentInfo="true" - to just register the card (if omitted, the actual purchase is made).

    recurringType=S - card details get saved for MIT transactions OR

    recurringType=R - use this only if you have an existing recurring solution and you are in a process of changing it to PSD2 compliant.

    2. Terminal call:

    To redirect customer to terminal and get SCA triggered.

    3. Process call:

    operation="VERIFY" for account verification OR

    operation="AUTH" with Process(CAPTURE) (or Process(SALE)) to follow.

    4. Query call:

    To fetch panHash=[token]

    Subsequent transaction

    You charge a payment using saved card details with the changing amount and/or time frequency according to agreement made with the consumer.

    MITs are out of scope of the PSD2 SCA requirements and therefore SCA will be bypassed.

    1. Register call:

    recurringType=M - indicates MIT transaction

    recurringTransactionType= 1 - UCOF OR 2 - Delayed charge OR 3 - No-show

    panHash=[stored token]

    serviceType="C" - terminal is bypassed OR

    serviceType="A" - terminal bypassed, required for app payments, but recommended to be used also for other non-callcenter payments

    2. Process call:

    operation="AUTH" with Process(CAPTURE) (or Process(SALE)) to follow.

    Best practices

    • 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 Checkout 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 Checkout 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.
    • Merchants should manage authorization reattempts based on the response codes. Ensure that any automated authorization reattempt processing excludes response codes described here.

    Was this helpful?

    What was your feeling about it?