Dintero Logo
API docs by Redocly

Payments API (LATEST)

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

Public endpoints for payments, including checkout, payout and settlement reports.

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

We recommend that keys used are prefixed with ext to avoid collision with reserved keys

  • dintero
  • merchant
  • session
  • event
  • payout
  • gateway
  • bambora
  • collector
  • instabank
  • klarna
  • kravia
  • netaxept
  • payex
  • santander
  • swish
  • vipps

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",
  • "url": "https://checkout.api.dintero.com/v1/view/9ea1610a357dc8189081c4cb955f26f612d91367",
  • "publish": [
    ],
  • "session": {
    }
}

Get checkout session details

scopes:

  • admin:checkout
  • read:checkout
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
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-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 (SessionOrderUpdate)
object
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
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
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",
  • "url": "https://checkout.api.dintero.com/v1/view/9ea1610a357dc8189081c4cb955f26f612d91367",
  • "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
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

object <= 10 properties

Additional metadata about the resource

All metadata keys must be prefixed with ext_ and the length if key/value pair is 128/256 characters

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.

final_capture
boolean
Default: false

Indicates whether the capture is final. If true additional captures on the transaction are not allowed and the authorization on any remaining uncaptured amount will be voided. Only applies to transactions where the payment_product is dintero_psp.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "amount": 29990,
  • "capture_reference": "string",
  • "items": [
    ],
  • "final_capture": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_product": "bambora",
  • "payment_product_type": "bambora.applepay",
  • "amount": 72200,
  • "currency": "NOK",
  • "payout_destination_id": "string",
  • "merchant_reference": "string",
  • "channel": "ecommerce",
  • "platform_type": "aggregator",
  • "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": {
    },
  • "billing_address": {
    },
  • "store": {
    },
  • "status": "CAPTURED",
  • "gift_cards": [
    ],
  • "items": [
    ],
  • "url": {},
  • "events": [
    ],
  • "session_id": "P00000000.465U8CUzaPVpneu1wt8Wei",
  • "session": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "checkboxes": [
    ],
  • "card": {
    },
  • "verified_identity": {
    }
}

Update transaction authorization

This endpoint is used to update an existing authorization:

Use cases:

  1. Extend authorization (Klarna)

    • Provider: klarna
    • Purpose: Extend the lifetime of an existing authorization.
    • Required fields:
      • reason (string): The reason for the extension.
      • reference (string): A reference specified by the merchant to identify the transaction.

  2. Update order amount (Klarna)

    • Provider: klarna
    • Purpose: Update the authorized amount for an existing Klarna order.
    • Required fields:
      • amount (number): The new amount to authorize.
      • items (array): List of transaction items. Sum of item amounts must equal the updated transaction amount.
      • description (string): Optional description of the order.
      • reason (string): Optional reason for the update.
      • reference (string): Optional merchant reference to identify the transaction.

  3. Update pre-authorization (Dintero PSP)

    • Provider: dintero_psp
    • Purpose: Update the pre-authorized amount and/or finalize the authorization.
    • Required fields:
      • amount (number): The new amount to authorize.
        • If final_authorization=false, the new amount must be greater than the previous pre-authorized amount.
        • If final_authorization=true, the amount may be increased, reduced, or unchanged.
      • final_authorization (boolean): Indicates whether this is the final authorization step.
        • true: Finalizes the authorization and locks the transaction for further updates.
        • false: Keeps the pre-authorization open for future updates.
      • reference (string): Optional merchant reference to identify the transaction.
      • items (array): Optional list of transaction items to update. If the transaction already has items, this field is required. When present, sum of item amounts must equal the updated transaction amount.

  4. Authorize external transaction (Dintero External)

    • Provider: dintero
    • Purpose: Authorize a transaction currently on hold.
    • If amount or items are provided, the API will validate if the details are consistent with the order in the transaction.

Notes:

  • For Klarna:
    • If amount is not provided: Extend authorization flow is used (use case 1). Only reason and reference are relevant.
    • If amount is provided: Update order amount flow is used (use case 2). amount is required; items and description are optional.
  • For pre-authorization: Only amount, final_authorization, and reference are relevant.
scopes: ["admin:checkout","write:checkout"]
Authorizations:
apikeyJWT
path Parameters
id
required
string <checkout-id>

The ID of the transaction

Request Body schema: application/json
reason
string

The reason of the extension

reference
string

A reference specified by the merchant to identify the transaction

amount
number

The new amount to authorize.

final_authorization
boolean

Indicates whether this is the final authorization step.

Array of objects

Optional list of transaction items to update. If the transaction already has items, this field is required. When present, sum of item amounts must equal the updated transaction amount.

description
string

Description of the order. Used when updating Klarna order amounts.

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "reference": "string",
  • "amount": 0,
  • "final_authorization": true,
  • "items": [
    ],
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_product": "bambora",
  • "payment_product_type": "bambora.applepay",
  • "amount": 72200,
  • "currency": "NOK",
  • "payout_destination_id": "string",
  • "merchant_reference": "string",
  • "channel": "ecommerce",
  • "platform_type": "aggregator",
  • "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": {
    },
  • "billing_address": {
    },
  • "store": {
    },
  • "status": "CAPTURED",
  • "gift_cards": [
    ],
  • "items": [
    ],
  • "url": {},
  • "events": [
    ],
  • "session_id": "P00000000.465U8CUzaPVpneu1wt8Wei",
  • "session": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "checkboxes": [
    ],
  • "card": {
    },
  • "verified_identity": {
    }
}

Refund transaction

Once a transaction has been successfully captured, a refund operation is available. Like other operations, refund can be partial or total

Refund Instabank transaction

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

scopes:

  • admin:checkout
  • write:checkout
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
required
amount
required
integer <int32>

The amount to be refunded

object <= 10 properties

Additional metadata about the resource

All metadata keys must be prefixed with ext_ and the length if key/value pair is 128/256 characters

reason
string

The reason of the refund

refund_reference
string

A reference specified by the merchant to identify the transaction

Array of objects

Info about the refunded order items

Instabank

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_product": "bambora",
  • "payment_product_type": "bambora.applepay",
  • "amount": 72200,
  • "currency": "NOK",
  • "payout_destination_id": "string",
  • "merchant_reference": "string",
  • "channel": "ecommerce",
  • "platform_type": "aggregator",
  • "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": {
    },
  • "billing_address": {
    },
  • "store": {
    },
  • "status": "CAPTURED",
  • "gift_cards": [
    ],
  • "items": [
    ],
  • "url": {},
  • "events": [
    ],
  • "session_id": "P00000000.465U8CUzaPVpneu1wt8Wei",
  • "session": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "checkboxes": [
    ],
  • "card": {
    },
  • "verified_identity": {
    }
}

Void transaction

At any moment before capture of a transaction, it is possible to cancel an authorization. This operation is called voiding and can be performed by doing a POST to this endpoint

Void on part capture

Void after a part capture will cancel the difference between the capture amount and the authorization amount.

Void on part capture is only supported on following types:

  • payex.creditcard
  • payex.mobilepay
  • payex.vipps
  • payex.applepay
  • payex.clicktopay
  • payex.googlepay
  • vipps
  • klarna.klarna
  • klarna.billie

scopes:

  • admin:checkout
  • write:checkout
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

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_product": "bambora",
  • "payment_product_type": "bambora.applepay",
  • "amount": 72200,
  • "currency": "NOK",
  • "payout_destination_id": "string",
  • "merchant_reference": "string",
  • "channel": "ecommerce",
  • "platform_type": "aggregator",
  • "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": {
    },
  • "billing_address": {
    },
  • "store": {
    },
  • "status": "CAPTURED",
  • "gift_cards": [
    ],
  • "items": [
    ],
  • "url": {},
  • "events": [
    ],
  • "session_id": "P00000000.465U8CUzaPVpneu1wt8Wei",
  • "session": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "checkboxes": [
    ],
  • "card": {
    },
  • "verified_identity": {
    }
}

Get a transaction

scopes:

  • admin:checkout
  • read:checkout
scopes: ["admin:checkout","read:checkout"]
Authorizations:
apikeyJWT
path Parameters
id
required
string <checkout-id>

The ID of the transaction

query Parameters
includes
Array of strings
Items Enum: "card.payment_token" "card.recurrence_token" "session" "session.events.latest" "events.request_headers" "events.success.true" "initiating_system_request_headers"

Include additional data that are by default excluded from the transaction details.

  • card.payment_token: Include the payment_token generated from the transaction. Only available for transaction with a session that enabled generate_payment_token.
  • card.recurrence_token: Include the recurrence generated from the transaction. Only available for transaction with a session that enabled generate_recurrence_token.
  • session Include the session that the transaction resulted from.
  • session.events.latest Include the session that the transaction resulted from with only the latest event in its events array.
  • events.request_headers Include the event headers stored for each event.
  • events.success.true Include events where success is true.
  • initiating_system_request_headers Include the request headers from the initiating system.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_product": "bambora",
  • "payment_product_type": "bambora.applepay",
  • "amount": 72200,
  • "currency": "NOK",
  • "payout_destination_id": "string",
  • "merchant_reference": "string",
  • "channel": "ecommerce",
  • "platform_type": "aggregator",
  • "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": {
    },
  • "billing_address": {
    },
  • "store": {
    },
  • "status": "CAPTURED",
  • "gift_cards": [
    ],
  • "items": [
    ],
  • "url": {},
  • "events": [
    ],
  • "session_id": "P00000000.465U8CUzaPVpneu1wt8Wei",
  • "session": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "checkboxes": [
    ],
  • "card": {
    },
  • "verified_identity": {
    }
}

Update a transaction

scopes:

  • admin:checkout
  • write:checkout
scopes: ["admin:checkout","write:checkout"]
Authorizations:
apikeyJWT
path Parameters
id
required
string <checkout-id>

The ID of the transaction

Request Body schema: application/json
merchant_reference_2
string

A reference specified by the merchant to identify the transaction, can be updated after the transaction has been created

Responses

Request samples

Content type
application/json
{
  • "merchant_reference_2": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_product": "bambora",
  • "payment_product_type": "bambora.applepay",
  • "amount": 72200,
  • "currency": "NOK",
  • "payout_destination_id": "string",
  • "merchant_reference": "string",
  • "channel": "ecommerce",
  • "platform_type": "aggregator",
  • "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": {
    },
  • "billing_address": {
    },
  • "store": {
    },
  • "status": "CAPTURED",
  • "gift_cards": [
    ],
  • "items": [
    ],
  • "url": {},
  • "events": [
    ],
  • "session_id": "P00000000.465U8CUzaPVpneu1wt8Wei",
  • "session": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "checkboxes": [
    ],
  • "card": {
    },
  • "verified_identity": {
    }
}

List all transactions

scopes:

  • admin:checkout
  • read:checkout
scopes: ["admin:checkout","read:checkout"]
Authorizations:
apikeyJWT
query Parameters
id
Array of strings <checkout-id> [ items <checkout-id > ]

List of ids that should be included in the result. ?id=A&id=B&id=X

limit
integer [ 1 .. 100 ]
Default: 10

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

starting_after
string <checkout-id>

cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

status
Array of strings
Items Enum: "AUTHORIZATION_VOIDED" "AUTHORIZED" "CAPTURED" "DECLINED" "FAILED" "INITIATED" "ON_HOLD" "PARTIALLY_CAPTURED" "PARTIALLY_REFUNDED" "PARTIALLY_CAPTURED_REFUNDED" "REFUNDED" "UNKNOWN"

The status of the transaction.

payment_product
Array of strings

The type of payment product used

payment_product_type
Array of strings

The payment product type

card_brand
Array of strings

The card brand for the payment

merchant_reference
string

The merchant reference used

merchant_reference_2
string

The second merchant reference on the transaction

session_id
Array of strings <checkout-id> [ items <checkout-id > ]

The session id(s) associated with the transactions. ?session_id=A&session_id=B&session_id=X.

store_id
Array of strings

The store_id that the transaction belongs to. ?store_id=A&store_id=B&store_id=X.

payout_correlation_id
Array of strings

Filter by the payout_correlation_id. Different format between payment providers. ?payout_correlation_id=A,B

currency
Array of strings

The currency of the transaction. ?currency=NOK&currency=SEK.

amount
integer >= 0

Exact transaction amount, amount authorized.

amount.gte
integer >= 0

Lower limit for filtering on transaction amount, amount authorized.

amount.lte
integer

Upper limit for filtering on transaction amount, amount authorized.

created_at.gte
string <isodate>

Transaction created after (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

created_at.lte
string <isodate>

Transaction created before a date (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

captured_at.gte
string <isodate>

Transaction captured after date (This param is subject to change in the future) (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

captured_at.lte
string <isodate>

Transaction captured before date (This param is subject to change in the future) (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

refunded_at.gte
string <isodate>

Transaction refunded after date (This param is subject to change in the future) (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

refunded_at.lte
string <isodate>

Transaction refunded before date (This param is subject to change in the future) (ISO 8601. We recommend using a localised ISO 8601 datetime like 2017-07-21T17:32:28Z. If a timezone is not specified we assume UTC)

search
string

Will try to match the search to either transaction_id, session_id or merchant_reference, merchant_reference_2, phone_number, email or the customer name using the format {first_name} {last_name}, or token_id using value of card.payment_token_id.

payment_operation
string
Example: payment_operation=unscheduled_purchase

Filter on payment_operation

customer_id
string

Filter transactions on the customer.customer_id.

includes
Array of strings
Items Value: "events.success.true"

Control the data that is included in the transactions

  • events.success.true Include only event where success is true
payout_destination_id
string

Filter transactions on payout_destination_id and items[].splits[].payout_destination_id.

token_id
Array of strings

Filter transactions on token_id(s) associated with the transactions, using card.payment_token_id. ?token_id=A&token_id=B&token_id=X.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Payment

Resources used by the customer aka user to complete the payment of a session.

Create and pay merchant initiated session

For merchant initiated payments, where the customer is not involved.

Receives a session and pays it with the given card token.

Merchant is resposible for managing their retry policy for payments that fails, and not retry when payment fails with DO_NOT_RETRY error.

200 response will be returned when request fails due to authorization error. Transaction will have status FAILED and error information can be found at events.error.

Insufficient error handling will cause cards to be blocked https://docs.dintero.com/docs/checkout/tokenization#do-not-try-again--excessive-reattempts

scopes:

  • admin:checkout
  • write:checkout
scopes: ["admin:checkout","write:checkout"]
Authorizations:
apikeyJWT
header Parameters
Dintero-Feature-Toggles
Array of strings
Default:
Items Enum: "strict-merchant-reference" "strict-success-merchant-reference"
Example: strict-merchant-reference
  • strict-merchant-reference: The session.order.merchant_reference must be unique. The pay request will fail with 400 BadRequest error if merchant_reference is duplicated by existing session.
  • strict-success-merchant-reference: The session.order.merchant_reference must be unique. The pay request will fail with 400 BadRequest error if merchant_reference is duplicated by existing session that was successfully authorized. This flag is less strict than strict-merchant-reference, allowing for duplicates session if previous session failed
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
object (PaySessionOptions)

The session to create the payment from

object (PayPayment)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_product": "bambora",
  • "payment_product_type": "bambora.applepay",
  • "amount": 72200,
  • "currency": "NOK",
  • "payout_destination_id": "string",
  • "merchant_reference": "string",
  • "channel": "ecommerce",
  • "platform_type": "aggregator",
  • "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": {
    },
  • "billing_address": {
    },
  • "store": {
    },
  • "status": "CAPTURED",
  • "gift_cards": [
    ],
  • "items": [
    ],
  • "url": {},
  • "events": [
    ],
  • "session_id": "string",
  • "session": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "checkboxes": [
    ],
  • "card": {
    },
  • "verified_identity": {
    },
  • "success": true,
  • "actions": [
    ]
}

Example Callbacks

Example of callbacks delivered

Discount codes Update

This API endpoint on the merchant side allows Dintero to get shipping_options and order with discounts based on the provided session that had its order.discount_codes updated.

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

An ID that uniquely identifies the resource

created_at
string <date-time>

The date-time when the resource was created

object
expires_at
string <date-time>

The session expiration time after which the Checkout page wouldn't be available

Array of objects (CheckboxConfiguration) <= 2 items

Configuration for checkboxes that should be part of 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
updated_at
string <date-time>

Last time when the Checkout was updated

customer_ip
string

The IP of the customer upon visiting the page. If the page is visited multiple times, the field is always updated with the last known value.

user_agent
string

The full user agent of the device the customer used when visiting the checkout page

object (SystemRequestHeaders)
payment_operation
string (PaymentOperationIntent)
Enum: "unscheduled_purchase" "recurring_purchase" "generate_payment_token"

Initiated by the merchant or used to generate a token

Array of objects

Checkout process events

transaction_id
string

Transaction which has been created using the checkout.

object

metadata about the session

Responses

Request 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": {
    }
}

Response samples

Content type
application/json
{
  • "order": {
    },
  • "shipping_options": [
    ]
}

Session Callback

This API endpoint on the merchant side allows Dintero to notify the session.url.callback_url when the payment is completed

The transaction_id is optional if report_error=true

query Parameters
transaction_id
required
string

The Id for the transaction created

merchant_reference
required
string

The merchants reference

time
required
string <date-time>

ISO 8601 format for when the transaction was created

session_id
string

Session Id. Either session_id or sid is required.

sid
string

Session Id if sid_parameter_name=sid. Either session_id or sid is required.

error
string
Example: error=authorization

Error code

event
string

Event applied to transaction

event_id
string
Example: event_id=3

Id for the event applied to transaction

method
string
Example: method=POST

The method to use when delivering the callback

report_error
boolean

Report error callback

delay_callback
integer

Delay before delivering the callback

report_event
string
Example: report_event=CAPTURE

Deliver callback on othe transaction events

header Parameters
Dintero-Signature
string

Dintero signature that can be used to verify the payload from the callback.

Only include if a signature secret exist:

event-delivery
string

A unique delivery ID to identify the event, which can be useful for tracking and troubleshooting purposes

Responses

Response samples

Content type
application/json
{ }

Session Callback

This API endpoint on the merchant side allows Dintero to notify the session.url.callback_url when the payment is completed

POST is only use if callback_url includes method=POST query parameter.

The body and transaction_id is optional if report_error=true

query Parameters
transaction_id
required
string

The Id for the transaction created

merchant_reference
required
string

The merchants reference

time
required
string <date-time>

ISO 8601 format for when the transaction was created

method
required
string
Example: method=POST

POST method used to deliver the callback

includes
required
string
Example: includes=session

Aditional data included

session_id
string

Session Id. Either session_id or sid is required.

sid
string

Session Id if sid_parameter_name=sid. Either session_id or sid is required.

error
string
Example: error=authorization

Error code

event
string

Event applied to transaction

event_id
string
Example: event_id=3

Id for the event applied to transaction

report_error
boolean

Report error callback

delay_callback
integer

Delay before delivering the callback

report_event
string
Example: report_event=CAPTURE

Deliver callback on othe transaction events

header Parameters
Dintero-Signature
string

Dintero signature that can be used to verify the payload from the callback.

Only include if a signature secret exist:

event-delivery
string

A unique delivery ID to identify the event, which can be useful for tracking and troubleshooting purposes

Request Body schema: application/json
payment_product
required
string
Enum: "bambora" "collector" "dintero" "dintero_psp" "instabank" "klarna" "netaxept" "payex" "santander" "swish" "vipps" "kravia" "seitatech"

The payment product corresponding to this transaction

payment_product_type
required
string
Enum: "bambora.applepay" "bambora.creditcard" "bambora.googlepay" "bambora.mobilepay" "bambora.vipps" "collector.invoice" "collector.invoice_b2b" "collector.invoice_b2b_preapproved" "collector.installment" "dintero.zero" "dintero.wallets" "dintero_psp.creditcard" "dintero_psp.vipps" "dintero_psp.googlepay" "dintero_psp.applepay" "dintero_psp.clicktopay" "instabank.finance" "instabank.invoice" "instabank.installment" "instabank.postponement" "klarna.klarna" "klarna.billie" "kravia.invoice_b2b" "kravia.invoice_b2b_grouped" "kravia.invoice_b2c" "netaxept.creditcard" "payex.creditcard" "payex.mobilepay" "payex.swish" "payex.vipps" "payex.applepay" "payex.clicktopay" "payex.googlepay" "santander.debit_account" "seitatech.in_person" "swish.swish" "vipps"

The payment product type corresponding to this transaction

amount
required
integer

Non-negative, minor units. Total amount of the transaction

currency
required
string <iso4217-code>

ISO 4217 transaction currency

id
string

An ID that uniquely identifies the resource

created_at
string <date-time>

The date-time when the resource was created

payout_destination_id
string <= 40 characters

An id that identifies the seller, value will be included in the settlement reports

merchant_reference
string

A reference specified by the merchant to identify the transaction

channel
string
Default: "ecommerce"
Enum: "ecommerce" "in_app" "in_store"

The channel for the transaction

platform_type
string
Enum: "aggregator" "marketplace"

Type of platform the merchant is.

merchant_reference_2
string

A reference specified by the merchant to identify the transaction, can be updated after the transaction has been created

dynamic_descriptor
string

A short reference / descriptor that will show up on the customers bank statement

payment_operation
string (PaymentOperationIntent)
Enum: "unscheduled_purchase" "recurring_purchase" "generate_payment_token"

Initiated by the merchant or used to generate a token

settlement_status
string (SettlementStatus)
Enum: "NOT_SETTLED" "PENDING_SETTLEMENT" "PARTIALLY_SETTLED" "SETTLED"

Overall settlement status after the events

object
customer_ip
string

The IP address of the customer

user_agent
string

The full user agent string of the device the customer used to submit the transaction

object (SystemRequestHeaders)
object (OrderAddress)

Address

object (MultiShipmentTopLevelShippingOption)

A shipping option

object (OrderAddress)

Address

object (Store)
Array of objects (Giftcard)

The gift cards that used to partially or fully authorize the transaction

Array of objects

The applicable transaction items

object
Array of objects

All events recorded on the transaction

session_id
string

The session id for the transaction

object (Session)
updated_at
string <date-time>

When the transaction was last modified.

object

Additional details about the transaction

Array of objects (CheckboxConfiguration) <= 2 items

Configuration for checkboxes that should be part of the checkout

object
object

Verified identity of the customer aka payer

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "payment_product": "bambora",
  • "payment_product_type": "bambora.applepay",
  • "amount": 72200,
  • "currency": "NOK",
  • "payout_destination_id": "string",
  • "merchant_reference": "string",
  • "channel": "ecommerce",
  • "platform_type": "aggregator",
  • "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": {
    },
  • "billing_address": {
    },
  • "store": {
    },
  • "gift_cards": [
    ],
  • "items": [
    ],
  • "url": {},
  • "events": [
    ],
  • "session_id": "P00000000.465U8CUzaPVpneu1wt8Wei",
  • "session": {
    },
  • "updated_at": "2019-08-24T14:15:22Z",
  • "metadata": {
    },
  • "checkboxes": [
    ],
  • "card": {
    },
  • "verified_identity": {
    }
}

Response samples

Content type
application/json
{ }

Address Update

This API endpoint on the merchant side allows Dintero to get shipping options based on the provided session after an address update

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

An ID that uniquely identifies the resource

created_at
string <date-time>

The date-time when the resource was created

object
expires_at
string <date-time>

The session expiration time after which the Checkout page wouldn't be available

Array of objects (CheckboxConfiguration) <= 2 items

Configuration for checkboxes that should be part of 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
updated_at
string <date-time>

Last time when the Checkout was updated

customer_ip
string

The IP of the customer upon visiting the page. If the page is visited multiple times, the field is always updated with the last known value.

user_agent
string

The full user agent of the device the customer used when visiting the checkout page

object (SystemRequestHeaders)
payment_operation
string (PaymentOperationIntent)
Enum: "unscheduled_purchase" "recurring_purchase" "generate_payment_token"

Initiated by the merchant or used to generate a token

Array of objects

Checkout process events

transaction_id
string

Transaction which has been created using the checkout.

object

metadata about the session

Responses

Request 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": {
    }
}

Response samples

Content type
application/json
{
  • "shipping_options": [
    ],
  • "order": {