Checkout API (LATEST)

API Integration Support: integration@dintero.com License: UNLICENSED

Public endpoints

authenticate

Get Token

Use this endpoint to directly request an access_token

Client Access Token

Use HTTP Basic authentication scheme for authenticating grant_type client_credentials, use client_id/client_secret as user/password.

Code/Password Token

Use HTTP Bearer authentication scheme for authenticating grant_type authorization_code or password, where the Bearer value must be a JWT toke with access to the token endpoint.

Account User Token

Use HTTP Bearer authentication scheme for authenticating grant_type account_user_token, where the Bearer value must be a account user JWT token.

Use ID token as Bearer toke if the user was authenticated externally. The ID must include a email claim that identifies the account user.

Refresh Token

Use HTTP Bearer authentication scheme for authenticating grant_type refresh_token where the Bearer value must be an Access Token for the clients that was used to create the Refresh Token.

Multi-factor authentication (MFA)

When a request is made to the endpoint to get an access token, normally you either get an error, or you get an access token. However, when the MFA is enabled, the endpoint may return a new error with error.code: mfa_required.

When an mfa_required error is returned, the client must perform a challenge. This is done by sending a request to the auth/mfa/challenge endpoint

To verify MFA using an OOB challenge, the client must make a request to this endpoint with grant_type=mfa-oob. Include the oob_code you received from the challenge response, as well as the mfa_token you received as part of mfa_required error.

scopes:

  • admin:accounts
  • write:accounts
  • write:accounts:/auth/users
  • write:accounts:/auth/users/no-mfa
Authorizations:
clientAuthJWT
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

Request Body schema: application/json
required
grant_type
required
string
audience
required
string

The unique identifier of the target API you want to access. The audience must be a grant associated with the client

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGci...t7P4",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "refresh_token": "string"
}

Sessions

A Checkout Session relates to an order in your system. When an order has been placed you create a corresponding Checkout Session to receive payment for that order.

Create checkout session from profile

Create a corresponding Checkout Session for an order placed in your system using predefined session profile

Session with Instabank

Note that items is a required property when creating a session with Instabank configured.

scopes:

  • admin:checkout
  • write:checkout
Authorizations:
apikeyJWT
query Parameters
include_session
boolean

Include all details about the session created

header Parameters
Dintero-Feature-Toggles
Array of strings
Default:
Items Value: "strict-session-amounts"

Feature toggles that will change how the API works.

These feature toggles are usually the preferred way to use the API, but they break the current API.

  • strict-session-amounts: order.amount must equal the sum of amounts in order.items + order.shipping_option.amount when creating sessions
Dintero-System-Name
string <= 120 characters

The name of the ecommerce solution

Example: woocommerce

Dintero-System-Version
string <= 120 characters

The version number of the ecommerce solution

Example: 5.4

Dintero-System-Plugin-Name
string <= 120 characters

The name of the ecommerce plugin

Example: Dintero.Checkout.WooCommerce

Dintero-System-Plugin-Version
string <= 120 characters

The version number of the ecommerce plugin

Example: 2.3.4

Request Body schema: application/json
required
required
object (SessionOrder)
required
object (SessionUrls)
profile_id
required
string

configuration profile

object
expires_at
string <date-time>
Array of objects (CheckboxConfiguration) <= 2 items

Configuration for checkboxes that should be part of the checkout

object (PaymentConfiguration)

Override configuration for the profile.

object (Merchant)

Configure merchant information used in the checkout.

object

Present only for Express Checkout sessions.

An Express Checkout session is a session where the end user will submit a shipping address and then select a shipping option before the before a payment method is selected and the payment is initiated.

Endpoints used in the Express Checkout flow.

  1. Set shipping address
  2. Set shipping option
object <= 10 properties

Additional metadata about the resource

Responses

Request samples

Content type
application/json
{
  • "url": {},
  • "customer": {
    },
  • "order": {
    },
  • "expires_at": "2019-08-24T14:15:22Z",
  • "checkboxes": [
    ],
  • "configuration": {
    },
  • "profile_id": "string",
  • "merchant": {
    },
  • "express": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "publish": [
    ],
  • "session": {
    }
}

Get checkout session details

scopes:

  • admin:checkout
  • read:checkout
Authorizations:
apikeyJWT
path Parameters
session_id
required
string <checkout-id>

The session ID

query Parameters
includes
Array of strings
Items Enum: "events.request_headers" "initiating_system_request_headers"

Include aditional data that are by default excluded from the session details.

  • events.request_headers Include the event headers stored for each event
  • initiating_system_request_headers Include the request headers from the initating system

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "url": {},
  • "customer": {
    },
  • "order": {
    },
  • "expires_at": "2019-08-24T14:15:22Z",
  • "checkboxes": [
    ],
  • "express": {
    },
  • "configuration": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "customer_ip": "string",
  • "user_agent": "string",
  • "initiating_system_request_headers": {
    },
  • "payment_operation": "unscheduled_purchase",
  • "events": [
    ],
  • "transaction_id": "string",
  • "metadata": {
    },
  • "cancelled_by": "string",
  • "cancelled_at": "2019-08-24T14:15:22Z"
}

Update checkout session details

Session must be locked for paying before updating.

Requirements:

  • order.shipping_option must be included in express_shipping_options if both are set.
  • order.amount must be equal to the sum of order.items and order.shipping_option

scopes:

  • admin:checkout
  • read:checkout
Authorizations:
apikeyJWT
path Parameters
session_id
required
string <checkout-id>

The session ID

query Parameters
force_shipping_address_callback
boolean
Default: false

If express.shipping_options is set, there will not be a callback to shipping_address_callback_url, unless force_shipping_address_callback is also set.

If express.shipping_options is not set, there will be a callback to shipping_address_callback_url.

update_without_lock
boolean
Default: false

Allow updating session without it having been locked first.

Allowed for server-to-server when the checkout has not been rendered yet.

header Parameters
Dintero-System-Name
string <= 120 characters

The name of the ecommerce solution

Example: woocommerce

Dintero-System-Version
string <= 120 characters

The version number of the ecommerce solution

Example: 5.4

Dintero-System-Plugin-Name
string <= 120 characters

The name of the ecommerce plugin

Example: Dintero.Checkout.WooCommerce

Dintero-System-Plugin-Version
string <= 120 characters

The version number of the ecommerce plugin

Example: 2.3.4

Request Body schema: application/json
required
required
object (SessionOrderUpdate)
object (SessionExpressUpdate)
remove_lock
boolean
Default: true

Remove lock after updating

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "express": {
    },
  • "remove_lock": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "url": {},
  • "customer": {
    },
  • "order": {
    },
  • "expires_at": "2019-08-24T14:15:22Z",
  • "checkboxes": [
    ],
  • "express": {
    },
  • "configuration": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "customer_ip": "string",
  • "user_agent": "string",
  • "initiating_system_request_headers": {
    },
  • "payment_operation": "unscheduled_purchase",
  • "events": [
    ],
  • "transaction_id": "string",
  • "metadata": {
    },
  • "cancelled_by": "string",
  • "cancelled_at": "2019-08-24T14:15:22Z"
}

Cancel session

Cancel a session

The session transaction will be voided in case where it is initialized or authorized.

Cancel is not allowed in case where the current transaction state is not initialized or authorized.

scopes:

  • admin:checkout
  • write:checkout
Authorizations:
apikeyJWT
path Parameters
session_id
required
string <checkout-id>

The session ID

header Parameters
Dintero-System-Name
string <= 120 characters

The name of the ecommerce solution

Example: woocommerce

Dintero-System-Version
string <= 120 characters

The version number of the ecommerce solution

Example: 5.4

Dintero-System-Plugin-Name
string <= 120 characters

The name of the ecommerce plugin

Example: Dintero.Checkout.WooCommerce

Dintero-System-Plugin-Version
string <= 120 characters

The version number of the ecommerce plugin

Example: 2.3.4

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "url": {},
  • "customer": {
    },
  • "order": {
    },
  • "expires_at": "2019-08-24T14:15:22Z",
  • "checkboxes": [
    ],
  • "express": {
    },
  • "configuration": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "customer_ip": "string",
  • "user_agent": "string",
  • "initiating_system_request_headers": {
    },
  • "payment_operation": "unscheduled_purchase",
  • "events": [
    ],
  • "transaction_id": "string",
  • "metadata": {
    },
  • "cancelled_by": "string",
  • "cancelled_at": "2019-08-24T14:15:22Z"
}

Payment token session

This endpoint lets you create payment and recurrence tokens without reserving or charging any amount.

The URL returned by this endpoint opens a web site where the customer can enter their payment details, e.g. card information.

The payment details will be validated and a transaction with a payment/recurrence token will be created on success containing the payment token created from the customer payment details.

scopes:

  • admin:checkout
  • write:checkout
Authorizations:
apikeyJWT
query Parameters
include_session
boolean

Include all details about the session created

header Parameters
Dintero-System-Name
string <= 120 characters

The name of the ecommerce solution

Example: woocommerce

Dintero-System-Version
string <= 120 characters

The version number of the ecommerce solution

Example: 5.4

Dintero-System-Plugin-Name
string <= 120 characters

The name of the ecommerce plugin

Example: Dintero.Checkout.WooCommerce

Dintero-System-Plugin-Version
string <= 120 characters

The version number of the ecommerce plugin

Example: 2.3.4

Request Body schema: application/json
required
required
object

The session to create the payment token from

required
object (TokenProvider)

Responses

Request samples

Content type
application/json
{
  • "session": {
    },
  • "token_provider": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "publish": [
    ],
  • "session": {
    }
}

Transactions

View and perform operations on transactions

Capture a transaction

Captures a transaction that was created with the Checkout endpoint with a capture_now value of false.

Capture Instabank transaction

Note that items is required when capturing a transaction with payment_product=instabank. The items must include the lines to Capture, with line_id, quantity and amount.

scopes:

  • admin:checkout
  • write:checkout
Authorizations:
apikeyJWT
path Parameters
id
required
string <checkout-id>

The ID of the transaction

query Parameters
includes
Array of strings
Items Enum: "events.request_headers" "initiating_system_request_headers"

Include aditional data in the returned data that are by default excluded from the transaction details.

  • events.request_headers Include the event headers stored for each event deprecated
  • initiating_system_request_headers Include the request headers from the initating system deprecated

From 2023-09, events.request_headers and initiating_system_request_headers will be included by default

header Parameters
Dintero-System-Name
string <= 120 characters

The name of the ecommerce solution

Example: woocommerce

Dintero-System-Version
string <= 120 characters

The version number of the ecommerce solution

Example: 5.4

Dintero-System-Plugin-Name
string <= 120 characters

The name of the ecommerce plugin

Example: Dintero.Checkout.WooCommerce

Dintero-System-Plugin-Version
string <= 120 characters

The version number of the ecommerce plugin

Example: 2.3.4

Request Body schema: application/json
amount
required
integer <int32>

The amount to be captured

capture_reference
string

A reference specified by the merchant to identify the transaction

Array of objects

Info about the captured order items

Instabank

required if the transaction payment_product is instabank. The capture will then be applied to the items included.

Responses

Request samples

Content type
application/json
{
  • "amount": 0,
  • "capture_reference": "string",
  • "items": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "id": "string",
  • "payment_product": "bambora",
  • "amount": 72200,
  • "currency": "NOK",
  • "payout_destination_id": "string",
  • "merchant_reference": "string",
  • "merchant_reference_2": "string",
  • "dynamic_descriptor": "string",
  • "payment_operation": "unscheduled_purchase",
  • "settlement_status": "NOT_SETTLED",
  • "customer": {
    },
  • "customer_ip": "127.0.0.1",
  • "user_agent": "Mozilla/5.0 ...",
  • "initiating_system_request_headers": {
    },
  • "shipping_address": {
    },
  • "shipping_option": {