Skip to main content

Tokenization

To save a customer's card info, you can tokenize the card and store it for future use. To enable tokenization for your account, contact your account manager.

Token types

There are support for two kinds of creditcard token via Swedbank:

  • payment token
  • recurrence token

Payment token

A payment token can be used to create payment where the card details will be prefilled in the checkout. The payer still has to enter the CVC to complete the purchase.

The payment token can also be used to perform unscheduled purchase without involving the payer, also known as an merchant initiated transaction (MIT)

info

Performing MIT transactions require approval. Contact your account manager.

Recurrence token

A recurrence token can be used to create recurring payment where you can charge a card without payer interaction. When an initial payment token is generated, subsequent payments are made through server-to-server request

Creating a token

There are two ways of creating a card token, either in advance, without withdrawing any money, or during a purchase process.

Creating token in advance

To store a token without performing a payment, do the following:

Authentication

To authenticate, you create a Checkout API client and use the credentials to Create an access token. The same client can be used for Sandbox mode and production.

For all requests to the API set the following header:

Authorization: Bearer {access_token}

Create token session

With the access token, call Payment token session with this body:

{
"session": {
"order": {
"currency": "NOK",
"merchant_reference": "order-number"
},
"url": {
"return_url": "https://example.com/accept",
"callback_url": "https://example.com/callback?method=GET",
"merchant_terms_url": "https://example.com/terms.html"
},
"customer": {
"email": "john.doe@example.com",
"phone_number": "+4799999999"
}
},
"token_provider": {
"payment_product_type": "payex.creditcard",
"token_types": ["payment_token", "recurrence_token"]
}
}

The response will look like this:

{
"id": "T11223445.5cyWnV68vzJ1kYjZPrKWWm",
"url": "https://checkout.test.dintero.com/v1/view/T11223445.5cyWnV68vzJ1kYjZPrKWWm"
}

Redirect the customer to the url for them to confirm their card.

Creating token while performing a purchase

To store card information for a customer using Swedbank Pay during the payment process, do the following:

When creating the session set

  • configuration.payex.creditcard.generate_payment_token=true
  • configuration.payex.creditcard.generate_recurrence_token=true

See create session for more information. It's also possible to disable CVC for returning payments if you have a dedicated agreement with Swedbank Pay.

Fetching and storing token

When the customer has completed filling in their card info, the return_url and callback_url will receive a request.

When you get this request, the payment token will be stored on the transaction. Use get transaction details to retrieve the transaction, with the query-param includes to include the cards tokens

example:

  • ?includes=card.payment_token
  • ?includes=card.recurrence_token

The token will then be included in the card details, e.g. card.payment_token.

info

Store the token internally in a secure manner.

Using the token

To use the token in a new session for the same customer, put the token value in the session under customer.tokens.payex.creditcard. See create session.

{
"url": {
"return_url": "https://example.com/thankyou",
"callback_url": "https://example.com/callback"
},
"order": {
"amount": 29990,
"currency": "NOK",
"merchant_reference": "merchants_order_number"
},
"customer": {
"email": "john.doe@example.com",
"phone_number": "+4799999999",
"tokens": {
"payex.creditcard": {
"payment_token": "<token previously acquired>"
}
}
},
"profile_id": "default"
}

The response will look like this:

{
"id": "T11223445.5cyWnV68vzJ1kYjZPrKWWm",
"url": "https://checkout.test.dintero.com/v1/view/T11223445.5cyWnV68vzJ1kYjZPrKWWm"
}

Redirect the customer to the url for them to confirm the payment with CVC.

Recurrence transactions

To perform transactions without involving the customer, using a recurrence token, use recurring_purchase operation when calling the pay endpoint.

With the access token, call Create and pay merchant initiated session with the following body:

{
"session": {
"url": {
"callback_url": "https://example.com/callback?method=GET"
},
"customer": {
"email": "john.doe@example.com",
"phone_number": "+4799999999",
"tokens": {
"payex.creditcard": {
"recurrence_token": "<token previously acquired>"
}
}
},
"order": {
"amount": 29990,
"currency": "NOK",
"vat_amount": 6000,
"items": [
{
"line_id": "1",
"description": "Stablestol",
"quantity": 1,
"amount": 29990,
"vat_amount": 6000,
"vat": 25
}
],
"merchant_reference": "order-1"
},
"configuration": {
"auto_capture": false
}
},
"payment": {
"payment_product_type": "payex.creditcard",
"operation": "recurring_purchase"
}
}

Unscheduled transactions

To perform transactions without involving the customer, MIT (merchant initiated) transactions use unscheduled_purchase operation when calling the pay endpoint.

With the access token, call Create and pay merchant initiated session with the following body:

{
"session": {
"url": {
"callback_url": "https://example.com/callback?method=GET"
},
"customer": {
"email": "john.doe@example.com",
"phone_number": "+4799999999",
"tokens": {
"payex.creditcard": {
"payment_token": "<token previously acquired>"
}
}
},
"order": {
"amount": 29990,
"currency": "NOK",
"vat_amount": 6000,
"items": [
{
"line_id": "1",
"description": "Stablestol",
"quantity": 1,
"amount": 29990,
"vat_amount": 6000,
"vat": 25
}
],
"merchant_reference": "order-1"
},
"configuration": {
"auto_capture": false
}
},
"payment": {
"payment_product_type": "payex.creditcard",
"operation": "unscheduled_purchase"
}
}

Prevent duplicate transactions

Use the Dintero-Feature-Toggles header to prevent creating duplicate transactions.

Including strict-merchant-reference value in the header will prevent creating duplicate transaction as it will require the merchant_reference to be unique within 24 hours

headers

Dintero-Feature-Toggles: strict-merchant-reference
Content-Type: application/json

body

{
"session": {
"url": {
"callback_url": "https://example.com/callback?method=GET"
},
"customer": {
"tokens": {
"payex.creditcard": {
"payment_token": "<token previously acquired>"
}
}
},
"order": {
"amount": 29990,
"currency": "NOK",
"vat_amount": 6000,
"merchant_reference": "order-1"
},
"configuration": {}
},
"payment": {
"payment_product_type": "payex.creditcard",
"operation": "unscheduled_purchase"
}
}

A 400 response will be returned if merchant_reference was duplicated

{
"session_id": "T11223445.5cyWnV68vzJ1kYjZPrKWWm",
"error": {
"message": "session.order.merchant_reference",
"code": "DUPLICATE"
}
}