Card Token

Card tokens can be used through the Digiteal API to initiate payments using a payment card. This solution is useful to store payment card in your own system without having to store sensitive card information.
A token allows you to split the initiation process into different operations making it possible to reserve funds before initiating a payment, this is usually used when the amount to pay is not known at the start of the initiation.
Tokens can also be used without customer input for server to server initiation like recurrent payment.

The card token solution is available for the following payment cards:

• Visa (debit/credit)
• Mastercard (debit/credit)
• Maestro

To get started with payment card tokenization, contact the Digiteal support team to setup your account and look over your needs.

Temporary token

To protect payment cards sensitive information we recommend to store card information into a temporary token that is then use to share those sensitive data throughout the payment flow.

A temporary token can be created using the Digiteal API by redirecting the cardholder to a web form to collect card information, or by connecting directly to a TSP to host the form yourself.
It can also be created using a payment service like Apple Pay or Google Pay.

Web form redirection

Use Digiteal API to collect card information into a temporary token.

❗️

This service is not yet available

Self hosted form

Manage the collection of card information into a PKey with your own self hosted form, connect directly to the TSP to create a temporary token.

Apple Pay

Implementing Apple Pay

Google Pay

Implementing Google Pay

Permanent token

Like temporary tokens, a permanent token is use to store sensitive card information, however a permanent token has an infinite lifespan. This is useful to store card information on your server and use it later to initiate payments.

Create token

Make a PKey into a permanent token.

A security challenge may be required to validate the customer identity before completing the operation. If the token creation triggers a security challenge, the token will be flagged as validated.

Force validation

You can force the validation of a token to trigger the security challenge and verify the cardholder identity. This is required to do MIT as the cardholder is not present during the process to respond to a security challenge.

🚧

Do not use force validation to create tokens that will only be used for CIT, this will always trigger a security challenge for the customer and therefore worse the customer experience.

Webhook

You can subscribe to a webhook to be notified of token creation.
In addition to the payment card details, the webhook will also contains the requestId for you to link with your system.

📘

Webhook type

PAYMENT_CARD_TOKEN_CREATED

You can override the default webhook URL using the notificationUrl attribute of the request if you wish to change the default behaviour of the webhook.

🚧

notificationUrl cannot be defined without an existing webhook.

The webhook payload is defined in the callback section of the create token endpoint.

Payment initiation

Payment initiation is made using 2 operations: first reserve the funds and then initiate a payment with those reserved funds or cancel the reservation.

Reserve funds

Reserve a certain amount of money from a card linked to a token. This amount may be higher than the final amount of the transaction. This operation will make sure that the requested amount is available on the card for the time of the payment initiation.

MIT

By default a reservation is CIT, this means that a security challenge may be required to validate the customer identity before completing the operation.

You can make the reservation MIT, this removes the needs to validate the customer identity but it requires the use of a validated token for such an operation to complete.

🚧

Digiteal needs to verify your ability to use MIT. Contact the support team to activate this option on your account.

Transfer

You can link the payment created through the initiation process to a transfer (aka. Trusted Payment). Learn more about this feature.

Webhook

You can subscribe to a webhook to be notified of funds reservation.
In addition to the reservationId, the webhook will also contains the requestId for you to link with your system.

📘

Webhook type

PAYMENT_CARD_TOKEN_RESERVED

You can override the default webhook URL using the notificationUrl attribute of the request if you wish to change the default behaviour of the webhook.

🚧

notificationUrl cannot be defined without an existing webhook.

You can find the details of the webhook payload in the callback section of the reserve funds endpoint.

Initiate payment

Charge the card using a reservation. Non charged funds will be released after the initiation.

Webhook

You can subscribe to webhooks to be notified of payment status changes.

📘

Webhook types

PAYMENT_INITIATED
PAYMENT_RECEIVED_IN_TRANSIT

You can find the details of the webhook payload in the callback section of the initiate payment endpoint.

Cancel reservation

Cancel a reservation and release the funds.

3D secure

A security challenge may be requested by the card issuer to validate the customer identity for certain operations. To respond to this challenge the customer must be present throughout the process.
If a challenge is requested, the operation will respond with an attribute 3dsRedirectUrl containing a URL. The customer must be redirected following this URL to the issuer security challenge web page. After completing the challenge the customer will be again redirected to a page of your choice and the result of the initial operation is returned within a notification.

Configuration

You can configure the 3DS flow using the 3dsConfig object.
The redirectUrl attribute lets you setup the final destination of the customer after completing the security process.
The language attribute defines the language used to display texts in the issuer security challenge web page.

Customer

The customer object is used to give more context to the issuer about the customer responding to the challenge. This may have a positive impact on the decision of the issuer to request a challenge; the more data you provide, better are the chances to skip the security challenge entirely.

Fingerprint

The status of the device fingerprint is required to create a permanent token.
Learn here how to implement the device fingerprint retrieval flow using Finaro as a TSP.