Dintero Logo
API docs by Redocly

Checkout API (LATEST)

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

Changelog

All notable changes to the API.

2025-08-01

New: Add metadata.merchant_country and metadata.merchant_category_code properties to transaction.

2025-06-25

Update: Add dintero_psp.vipps to the session configuration

2025-06-03

Update: Add support for dintero_psp.vipps payment product

2025-06-01

update: Document support for overwrite_payout_destination_id in payout dynamic_payout_destination configuration. The new option can be used to overwrite order.payout_destination_id set by clients creating payment sessions.

update: Document support for verified_identity for Collector (Walley) transactions

update: Document support for authorization_code for Collector (Walley) B2B payment product types

update: Remove recurrence_token concept for dintero_psp.creditcard All tokens for dintero_psp are now of type payment_token. A dintero_psp.creditcard payment_token can be used for CIT, unscheduled MIT and recurring MIT.

new: Add support for Token Management. Allows users to manage their payment and recurrence tokens.

new: Add support for dintero_psp gateway configuration dintero_psp.token_scope.

new: Add support for dintero_psp configuration token_supported_auth_methods, indicating which authentication methods to support during token authentication flows.

2025-05-01

new: Extend transaction.card to support field product_platform, indicating whether the card is "consumer" or "commercial".

new: Extend transaction.card.region to support enum values "eea-uk" and "europe".

update: Support for multiple shipments. For multiple shipments we have a single top-level shipping object that contains the shipments for the order. The shipping options defined in shipments must contain shipment_items that define what items belong to what shipment.

2025-04-01

Fix: Add missing documentation for PARTIALLY_CAPTURED_REFUNDED status in Transaction and TransactionEvent

2025-03-01

new: Extend session.order to support event_reference, to provide "default" event_reference in case auto capture is enabled and Swish transactions

new: Extend session.configuration.channel to support ecommerce and update transaction model to include channel

new: Add support for Dintero PSP tokenization. Set tokenizer config on gateway configuration (prerequisite). Request payment token on zero and non-zero amount session. Request recurernce token on zero amount session. Use payment token on payment to perform unscheduled MIT or CIT. Use recurernce token on payment to perform recurring MIT.

new: Add support for includes=events.latest query param.

This lets you optionally include only the latest event in the session events array when getting all sessions. This is useful if you e.g. want to know the latest status of the sessions but don't need the rest of the events and their data.

new: Add support for updated_order_result and updated_express_result object properties on session event details to indicate how a session update modified the session.order or session.express data on the session.

new: Add support for includes=session.events.latest to include the session that the transaction resulted from, but with only the latest event in the session's events array.

2025-02-01

update: Make phone_number an optional instead of required property for the following Swish payment types:

  • swish.swish

This change was made to also support the M-Commerce payment flow.

2025-01-21

new: Add relative time properties on eta of a shipping option

new: Add support for filtering transactions by payout_destination_id

update: Make phone_number an optional instead of required property for the following Vipps payment types:

  • vipps
  • bambora.vipps
  • payex.vipps

This change was made to simplify the Vipps checkout flow and increase conversion.

2024-12-04

new: Support vipps.epayment through gateway_api_version.

2024-11-19

update: Add support for includes=event.success.true to only include successful events in transaction response

2024-11-16

update: Add support for defining opening_hours and website_url in pick_up_address for a shipping option

2024-11-01

update: Add support for pay_in_store.type=full in shipping_option to enable pay during pick-up.

2024-10-15

update: Add support for order_store_id_as_order_payout_destination_id dynamic_payout_destination_ids type to support auto selecting payout_destination_id to be equal to the order store id

2024-08-01

update: Make the social_security_number for collector.invoice and collector.installment optional for the pay endpoint. The property is not needed for payments where BankId is required

update: Update request body validation for set gift card endpoint to only require pin if type is set to dintero.wallets.card_token.

new: Add payment operation pay-bambora-creditcard-cit, using Bambora CIT token to get card info.

new: Add support for creating session with Bambora payment token.

new: Add support for paying with Bambora CIT token

new: Add new session intent endpoint with support for poll_initiated

2024-07-01

2024-07-01

new: Document unsupported payment methods for Dintero gift cards.

2024-07-01

update: Add intent type extend_authorization to events intent endpoint

2024-06-01

update: Remove optional transaction properties in events intent endpoint

update: Fix enums for card.type

update: Fix enums for event.metadata.vipps:transactionInfo.status Add enum values that was missing: SALE, Captured, Cancelled and Refund

update: Add transaction event error type and error_code to token transactions

2024-05-15

update: Add new transaction event type, INITIATE_VOID

2024-05-01

update: Extend card type for Bambora transactions with Debit and Credit. Deprecating the use of Credit Card as card type

update: Extend card with region for Bambora transactions and normalize the brand to be one of MasterCard or Visa

update: Adds additional configuration options to sessions and profiles for default_customer_type and allow_different_billing_shipping_address.

new: Support adding payment information events to sessions

new: Add optional thumbnail_url to shippping_option to be shown in checkout.

2024-04-01

new: Support authorization callback from Klarna

new: Support void, capture, and refund for Dintero PSP transactions

2024-03-01

new: Extend payout configuration to support dynamic_overrides to support using the order.store.id to set order.payout_destination_id. The new option enables existing integration that use order.store.id to start using payout with order.payout_destination_id set

update: Allow splits to be empty when creating a payment session. A transaction created from session with empty items/shipping_option splits will require splits to be specified when capture or refund is performed.

update: Transactions can be filtered by customer_id

new: Add support for Dintero-Feature-Toggles header when updating session

new: Add full support for configuring an Express checkout session or profile with custom checkboxes.

new: Support finish authorizing dintero_psp.creditcard and handle redirect

2024-02-20

new: Support getting payment operations for dintero_psp.creditcard

new: Support dintero_psp.creditcard payment configuration

2024-02-01

new: Add support for using Dintero Wallets card to partly/fully authorize the payment session

2024-01-07

update: Add optional query param, email, to View Payment Operations

2023-12-01

update: Add Visa Tokenization credentials to Dintero PSP gateway.

new: Add partial support for configuring an Express checkout session with custom checkboxes.

2023-11-01

new: Add support bambora tokenization Set token_scope and token_api_url on gateway configuration(prerequisite) Request payment(MIT) or recurrence(CIT) token on zero and non-zero amount session Use payment or recurrence token on payment to perform MIT or CIT

new: Add support for zero amount sessions by introducing new configuration option configuration.dintero.zero.enable. With the new option enabled a zero order session can be created, authorized, captured, refunded and voided. It make it possible to create express session to capture customer information via express without require any payment authorization by the customer.

2023-10-01

new: Add support for extending transaction authorization

2023-09-01

new: Add Dintero PSP gateway

new: Add support for the Klarna EMD marketplace orders package.

new: Add full support for the Klarna EMD travel-related transactions package (car rental reservation details).

new: Add partial support for the Klarna EMD travel-related transactions package (hotel reservation details).

new: Add partial support for the Klarna EMD travel-related transactions package (ferry reservation details).

new: Add partial support for the Klarna EMD travel-related transactions package (train reservation details).

new: Add partial support for the Klarna EMD travel-related transactions package (bus reservation details).

new: Add partial support for the Klarna EMD travel-related transactions package (air reservation details).

2023-05-19

new: Add generate_payment_token to session.payment_operation.

2023-05-05

break: Remove ingenico completely, i.e. payment type, payment operation, checkout config, gateway setup.

  • GET / POST /v1/events/gateways/ingenico/transaction/hooks
  • GET /v1/sessions/{session_id}/ingenico/redirect/{redirect_ref}
  • PUT /v1/admin/gateways/ingenico
  • PUT / GET /v1/admin/checkout

2023-04-01

new: Add support for appswitch deeplink URL for payex.mobilepay sessions with channel=in_app set.

new: Support payex.vipps through payex v3 when gateway_api_version is set to "payex.v3", and add payment operation for pay-payex-v3-vipps.

new: Support payex.swish through payex v3 when gateway_api_version is set to "payex.v3", and add payment operation for pay-payex-v3-swish.

2023-03-20

update: Require locale for initiating checkout payment for klarna.klarna.

update: Add string representation of order to response from view payment operations for klarna.klarna

2023-02-01

update: Limit refund to positive amount

new: Add support for finishing authorization of Klarna payment and handle redirect.

2023-01-01

update: Add support for marketing_consent when initiating Instabank payment

update: Add support for query_gateway query parameter when getting status of PayEx payment for a session.

new: Support payex.applepay payment product type. Extend configuration on gateway and session to enable Apple Pay.

new: Add support for getting payment operations for Klarna

new: Add support for enabling Klarna payment when creating payment sessions

new: Add support for configuring Klarna gateway

update: Include Klarna gateway and credentials details

update: Update Payex transaction. Extend card.type with Debit Card, and let metadata.payex:payment:number and event.metadata.payex:transaction:number be either string or number.

2022-12-01

update: Add support for strict-success-merchant-reference Dintero-Feature-Toggles header when creating merchant initiated session. The new flag allow "duplicates" if existing sessions failed

new: Add endpoint for handle callback for payex V3 payments

new: Add endpoint for handle redirect for payex V3 payments

update: Add support for pay-payex-v3-creditcard payment operations response from endpoint

update: Add support for specifying gateway_api_versions when configuring payment options

2022-11-01

update: Add suport promiting credential to gateway and gateway override The new option add support for configuring gateway and overrides when credential is created or updated

2022-08-01

new: Add endpoint for managing credentials for Collector gateway

new: Add endpoint for managing credentials for PayEx gateway

new: Add support for appswitch deeplink URL for payex.vipps sessions with channel=in_app set.

2022-07-01

new: Add support for including metadata about discounts via discount_lines when capturing or refunding a transaction.

new: Add metadata.payout property to transaction, the new property will be set if payout is enabled and state what kind of payout will be done

2022-06-01

change: Extend support for void on part capture. Void can now be used to release remaining authorization on part captured payex.mobilepay and payex.vipps transactions

new: Add possibility to change name of session_id query parameter in callback_url

change: Improve endpoint for handle unscheduled and recurring payments

2022-05-01

change: Add support for void on part capture Vipps transaction. Void can be used to release the remaining authorization on a part captured transaction.

new: Add strict mode header to validate correct session amounts

new: Add support for payout splits via Dintero Payout

2022-04-01

new: Add item types to distinguish between physical and digital items, and a category for services

new: Add thumbnail url to order item to be shown in checkout

new: Add possibility to update session without locking it first

new: Add possibility to update session.express

new: Document support for recurring payments. Extend configuration to support generating recurring payment token for payex.creditcard payments and performing recurring payments via the pay endpoint

2022-03-01

new: Add shipping_mode to decide if a shipping option is required

2022-02-22

fix: Require description when creating session profile. Document that description is a required property for session profile. The property has always been required by the service.

2022-03-01

new: Support payex.mobilepay payment product type. Extend configuration on gateway and session to enable MobilePay payment via PayEx PSP service.

2022-02-01

new: Document event_id query parameter included in request sent to session callback_url

new: Store initiating system request headers on session and transaction. Add ability to filter sessions on plugin name.

2022-01-01

new: Add support for handle authorization redirect from Collector IdP

new: Add support for including authorization_code in Collector pay requests

2021-12-01

change: Add ability to keep overrides for swish gateway PUT /v1/admin/gateways/swish

new: Add support for order.payout_destination_id when creating new sessions. The property will be included in the settlement reports and used if payout is enabled.

new: Pay with payex.swish, support for both E-Commerce and M-Commerce Swish Payments.

change: Validate PayEx subsite, return 400 if invalid subsite is used

2021-11-01

new: The profile_id used when creating new sessions will now be included in the session and transaction metadata.session:profile_id property

2021-09-01

new: Support for configuring payout for payment products

new: Support including events.request_headers when fetching session and transaction, and performing capture, refund or void on the transaction

2021-08-01

change: Add support for phone_number when getting payment operations

change: Add support for payex.vipps payment product type

2021-05-01

new: Support payex.vipps payment product type. Extend configuration on gateway and session to enable Vipps payment via PayEx PSP service.

2021-06-01

new: Support bambora.mobilepay payment product type. Extend configuration on gateway and session to enable MobilePay payment via Bambora Wallet service. The payment type must be enabled by Bambora.

doc: Fix documentation for payment-token session endpoint. session and payment_token are required when creating payment-token session.

new: Support enable_on_hold-configuration on session configuration and in checkout configuration

2021-05-01

new: Support bambora.vipps payment product type. Extend configuration on gateway and session to enable Vipps payment via Bambora Wallet service. The payment type must be enabled by Bambora.

new: Support session profile configuration when creating payment-token session

new: Extend shipping_address_callback response with support for updating the checkout session in addition to returning available shipping options. This will allow the callback endpoint to update the content of the order, like changing amount, or currency or update the items in the order.

2021-04-01

change: Add support for void on part capture. Void can be used to release the remaining authorization on a part captured transaction. The support is limited to payex.creditcard transactions.

change: Add support for language query parameter when getting payment operations

change: Add support Bambora creditcard payment.

change: Add support for bypassing the Dintero redirect for in_app-payments, and redirect from app to app.

2021-03-01

change Add support for includes query parameter in session url.callback_url. includes set to session will enable the sessions url.callback_url to include session data in the body.

2021-02-01

new: It is now possible to use full ISO 8601 compliant datetimes in date range queries. Note: If timezone isn't specified, UTC is assumed Note: To keep things backwards compatible, end-dates with the "yyyy-mm-dd" format will be shifted forward by a day.

new: Add possibility to create myDintero-user in address change

new: Extend transaction data with embedded session data includes now supports 'session'

new: Extend Vipps transaction metadata with vipps:merchantInfo.merchantSerialNumber, the Merchant Serial Number (MSN) that was used when the transaction was initiated.

new Add support for setting settlements on a transaction, one event per payout to a bank account

new: Version support when updating PayEx gateway configuration. The new option allows the gateway to be configured with multiple merchant agreements

change: Add support for additional query parameters. search will match on merchant reference's and customer name transaction_id will filter results to include only sessions associated with the provided transaction ids created_at.gte will exclude all sessions created before provided date created_at.lte will exclude all sessions created after provided date

2021-01-01

new: Endpoint for initiating MIT payments

new: Checkout sessions and profiles supports theming via configuration.theme

2020-12-01

new: Add support for using external discount codes in Express checkout. A session can be configured with a express.discount_code_callback_url that will be invoked when the session is updated with a promotion code. The response from the callback will then be used to adjust the order and shipping options available.

new: Add support for an advance credit check of Collector B2B customers

2020-11-01

new: Add support for overriding Collector gateway settings

new Add support for collector.invoice_b2b_preapproved and collector.installment_b2b_preapproved payment

new Async transaction operations. The response status from capture, refund or void can now be 202 if the request was accepted but the processing has not been completed.

The transaction with an operation that was accepted will receive a update later when the processing completes. The event that completes the operation will include an initiate_request_id property. You can use the callback_url to receive a callback when the processing completes.

The status of the transaction will remain unchanged until the processing of the operation completes.

new Add support for callback when transaction is updated. You can now receive callbacks on captures, refunds and void by including report_event=<event> query parameter in the callback_url.

https://example.com/callback?report_event=CAPTURE&report_event=REFUND

2020-10-01

new Added in_store as a possible payment channel for payments in physical stores.

2020-09-01

new Added option for configurating the payment channel. See configuration.channel. The new option add support for in_app channel with appswitch deeplink URL (Vipps).

new Add support for optional order.discount_lines when creating a new sessions.

new Add support for updating a session

total_income moved from applicant to top level for instabank.invoice and instabank.installment. The field is required, but there will be a grace period of two months before it is enforced. Deprecated applicant.total_income

2020-08-01

new Add support for optional metadata when creating a new session.

new Add support for optional merchant_reference_2 when creating a new session

new Add support for delayed callback. You can enable the delay callback feature by including delay_callback=<seconds> query parameter in the callback_url

https://example.com/callback?delay_callback=30

2020-07-01

new: Add support for overriding Netaxept gateway settings

new: Add terminal options for Netaxept creditcard payment. Enable use of Netaxept hosted checkout, and provided custom configuration.

new: Add support for Netaxept.

new: Add support for overriding PayEx gateway settings

new: Include payment token in transaction details

new Added option for using payment token for payex.creditcard payments to prefill payment details so the customer (payer) do not need to enter all these details for every purchase.

new Added option for generating payment token for payex.creditcard payments, see configuration.payex.creditcard. Use the new option to generate a payment token that can be used in future payments to prefill the details for the creditcard.

new Added instabank.postponement payment type.

new Added swish.swish payment type, direct integration with Swish.

2020-06-01

change Add support for ON_HOLD transaction status. The new status is limited to Collector transactions, to signal that the processing of the transaction is not yet completed. The new status will be used in cases where Collector performs aditional controls before approving the payment.

new Add support for setting merchant_reference_2 to an existing transaction and search for transactions by merchant_reference_2.

2020-05-01

new Add support for POST callback with the authorized transaction included in the request body. You can enable the POST callback feature by including method=POST query parameter in the callback_url

https://example.com/callback?method=POST

2020-04-01

new Add support for instabank.installment payment

changed: Removed error capture from list of valid error added to the redirect to the url.redirect_url. The error was used for payments with auto-capture enabled, and set in case where the auto capture failed. The merchant can assume the transaction will be captured automatically as soon as possible when creating a session with auto-capture enabled.

changed: A callback (when url.callback_url is set) will now be sent as soon as possible after the transaction is AUTHORIZED. We will no longer wait until the transaction CAPTURED in case when auto-capture is enabled.

change: Add support for creating session with Ingenico enabled

change: Add support for creating session with Ingenico enabled

new Add support for collector.invoice_b2b payment

2020-03-01

new Add support for configuring Ingenico gateway

new Add support for enabling Dintero-Signature header for all system-to-system request sent from Dintero to the merchant

fix: Documentation for endpoint GET /v1/admin/api-keys. The resource returns a list of api-keys, not a single api-key.

new Add support for collector.installment payment

new Add support for putting merchant_terms_url in profile and session

new Add support for overriding gateway settings

2019-12-01

new Add support for include_session query parameter

new Add support for discount calculation on sessions. The discounts will be calculated when customer is identified

Extend the order and transaction items with new properties to support discount calculation of session:

  • discount_lines
  • gross_amount
  • is_change
  • eligible_for_discount

Support calculating and updating session with discount from:

new Add store property to session.order and transaction. Adds support for including details about the sales location in the order

new Add shipping_option from session.order to to transaction

changed Minor changes to the shipping_option object(s) in sessions

new Add an endpoint for abandon a checkout payment

2019-11-01

changed: Express Checkout flow added to sessions

new Update a an Express Checkout session order

new: Extend Transaction with optional billing_address field.

2019-10-01

new: Extend Transaction Event with correction field to handle correction of status after operations errors

changed: previously required fields are now optional for instabank.finance.

  • mortgage_debt
  • student_debt
  • other_secured_debt

changed: Payments for payment product type instabank.invoice now contain an optional applicant object used for sending more details about the payee. The applicant data will be required for amounts over a limit specified by Instabank.

changed: Payment sessions with instabank.invoice now contains an require_applicant boolean flag in the instabank invoice configuration when getting the session.

changed: Adds detailed debt array to instabank.finance.

2019-09-01

changed: Disabled instabank.invoice for amounts less than 500 NOK

new: Filter transaction list by payment_product_type:

  • instabank.finance
  • instabank.invoice
  • vipps
  • payex.creditcard
  • payex.swish

new: Filter transactions list by card_brand:

  • Visa
  • MasterCard

new: Added optional remember_me boolean to POST pay request body when initializing a payment of a session.

2019-07-01

fix: Transaction.status typo, rename PARTICALLY_CAPTURED_REFUNDED to PARTIALLY_CAPTURED_REFUNDED.

changed: replaced card payment type with payex. The payex payment type adds support for payment product types:

  • payex.creditcard
  • payex.swish

changed: Add support for optional custom expires_at parameter when creating a new session either directly or from a profile.

changed: Add support for override of configuration when creating a new session from a profile.

new: support cancel of session

changed: In SessionBase, extend order with partial_payment property that can be used in case where the payment is partial and the order.amount is less or equal to the order.items.amount.

2019-06-01

break: Pay with instabank.finance type requires now additional properties to comply with new regulations from Finanstilsynet.

changed: Remove instabank.installment and instabank.postponement payment type. The types will no longer be accepted by:

2019-05-01

In SessionMeta renamed field expiry_at to expires_at.

new: PaymentConfiguration extended with optional auto_capture boolean field. If set to true the checkout serivce will automatically capture the payment after the transaction is AUTHORIZED.

new: Add support for checkout with SMS. A SMS with link to the checkout can now be sent when a new session is created. See relevant resources for more information.

2019-04-01

fix: Fix documentation for the response from api-keys endpoints. No gateways property will be included in response to api-keys requests.

doc: Document support for JWT Bearer authentication. Use API client to get an JWT access token.

2019-03-01

break: Administration of checkout gateways was moved to new endpoints. Gateway configuration will no longer be supported via the PUT /admin/checkout endpoint.

removed:

  • POST /admin/gateways/{gateway} (check gateway status)

new: Extend transaction.event with created_by property. Include the user who created the event, i.e. applied an operation to the transaction.

2019-01-31

new: Add support for checkout with QR-Code A QR Code can now be generated for a Checkout Session. See relevant resource for more information.

new: Add support for filter transactions with query parameters. Transactions can now be filtered on: status, payment_product, merchant_reference, session_id, amount and created_at.

2018-11-24

new: Add support for session.url.callback_url. Get system-to-system notification when session payment is completed.

session

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

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

Create a checkout session

Create a corresponding Checkout Session for an order placed in your system

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)
required
object (PaymentConfiguration)
object
expires_at
string <date-time>
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
object <= 10 properties

Additional metadata about the resource

object (Merchant)

Configure merchant information used in the checkout.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "string",
  • "url": "https://checkout.api.dintero.com/v1/view/9ea1610a357dc8189081c4cb955f26f612d91367",
  • "publish": [
    ],
  • "session": {
    }
}

List checkout sessions

List all Checkout sessions scopes:

  • admin:checkout
  • read:checkout
scopes: ["admin:checkout","read:checkout"]
Authorizations:
apikeyJWT
query Parameters
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.

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

search
string

Will try to match the search to either merchant_reference, merchant_reference_2, or the customer name using the format {first_name} {last_name}.

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

The id(s) of the transaction(s) that should be included in the result

created_at.gte
string <isodate>

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

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

store_id
Array of strings

The store_id that the session relates to. ?store_id=A&store_id=B&store_id=X.

initiating_system.dintero_system_plugin_name
Array of strings

The dintero-system-plugin-name that the session was created with.

payment_operation
string
Example: payment_operation=unscheduled_purchase

Filter on payment_operation: unscheduled_purchase, recurring_purchase, generate_payment_token

includes
Array of strings
Items Value: "events.latest"

Control the data that is included in the sessions.

  • events.latest: Only include the latest event in the session events array.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

QR Code for a Session

Generate a QR Code containing the URL for the Checkout Session. The QR Code can be displayed in POS to enable Checkout payment.

scopes:

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

The session ID

Request Body schema: application/json
required
format
string
Value: "png"
size
integer [ 300 .. 1024 ]
Default: 300

Size of the QR code. The code is a square, so width and height are the same

Responses

Request samples

Content type
application/json
{
  • "format": "png",
  • "size": 300
}

Response samples

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

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

payment

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

Initiate a checkout payment

For Express Checkout sessions, the order.shipping_address must be set on the session, and a _order.items.shipping_option item is required if the session has either an express.shipping_address_callback_url or the session has at least one option in express.shipping_options.

path Parameters
session_id
required
string <checkout-id>

The session ID

header Parameters
If-Unmodified-Since
string

Optional header. The put request is discarded and a 412 is returned if the header does not match the updated_at property or the version of the session.

Request Body schema: application/json
required
payment_product_type
required
string

The payment product type corresponding to this transaction

phone_number
string^\+?\d{5,15}$

mobile number of a person / company, ITU/E.123 format with international prefix (+PPNNNNNNNNN...)

remember_me
boolean

If true will either make the backend add or update a signed cookie with customer data. If false the cookie will be removed. If not set, any existing cookie will remain unchanged

Responses

Request samples

Content type
application/json
Example
{
  • "payment_product_type": "swish.swish",
  • "phone_number": "string",
  • "remember_me": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "actions": [
    ],
  • "redirect_url": "string",
  • "poll_url": "string",
  • "approval_url": "string",
  • "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAABzklEQVR42mNkAAYy...",
  • "error": "Rejected",
  • "error_details": [
    ]
}

Handle redirect from payment

path Parameters
session_id
required
string <checkout-id>

The session ID

redirect_ref
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

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",
  • "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": [
    ]
}

view

Resources used to present the customer with payment details

Get the Checkout page

path Parameters
session_id
required
string <checkout-id>

The session ID

query Parameters
language
string
ui
string
Enum: "fullscreen" "inline" "modal"
scc
string

Optional query parameter. SMS-confirm-code. To verify the identity of the payee.

Responses

Get payment operations

path Parameters
session_id
required
string <checkout-id>

The session ID

payment_product_type
required
string
Enum: "bambora.applepay" "bambora.creditcard" "bambora.googlepay" "bambora.mobilepay" "collector.installment" "collector.invoice" "collector.invoice_b2b" "collector.invoice_b2b_preapproved" "dintero_psp.creditcard" "dintero_psp.vipps" "payex.creditcard" "payex.mobilepay" "payex.swish" "payex.vipps" "payex.applepay" "payex.clicktopay" "payex.googlepay" "santander.debit_account" "klarna.klarna" "klarna.billie"
query Parameters
language
string
Example: language=nb-NO

Preferred language to use in the payment operation

phone_number
string <E.164> ^\+?[1-9]\d{1,14}$
Example: phone_number=+4738260107

Preferred phone number to use in the payment operation

email
string
Example: email=example@email.com

Preferred email to use in the payment operation

organization_number
string
Example: organization_number=919656396

The organization number that the payment is for.

country
string
Example: country=NO

The country to ship to. Required for klarna payment types.

force_new
string
Value: "true"

Forces the checkout-service to create a new payment session in the underlying gateway. Used for dintero_psp when 3Dsecure is cancelled of failed and the user wants to retry the payment.

Responses

Response samples

Content type
application/json
{
  • "operations": [],
  • "version": "22596363b3de40b06f981fb85d82312e8c0ed511"
}

Get checkout details

path Parameters
session_id
required
string <checkout-id>

The session ID

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": {
    },
  • "metadata": {
    },
  • "operations": [],
  • "pay_lock": {
    },
  • "version": "22596363b3de40b06f981fb85d82312e8c0ed511"
}

Abandon a checkout payment

Abandon a checkout payment before completing payment.

path Parameters
session_id
required
string

The session ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Lock a checkout session

When locked, the session can not be paid. Locking the session is only available when express is enabled.

path Parameters
session_id
required
string <checkout-id>

The session ID

Responses

Response samples

Content type
application/json
{
  • "pay_lock": {
    }
}

Set Express Checkout addresses and checkboxes

Changes the order.shipping_address and order.billing_address submitted by end user in the Express Checkout flow.

If the express.shipping_address_callback_url is set, the express.shipping_options in the response will be updated to show the available shipping options for the updated address.

Also changes the checkboxes that are part of the session as they are checked or unchecked by the end user in the Express Checkout flow.

path Parameters
session_id
required
string <checkout-id>

The session ID

header Parameters
If-Unmodified-Since
string

Optional header. The put request is discarded and a 412 is returned if the header does not match the updated_at property of the session.

Request Body schema: application/json
required
object (OrderAddress)

Address

object (OrderAddress)

Address

object (MyDinteroUserCreation)

Options for myDintero

Array of objects (CheckboxUpdate) <= 2 items

The checkboxes that should be updated

Responses

Request samples

Content type
application/json
{
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "my_dintero": {
    },
  • "checkboxes": [
    ]
}

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": {
    },
  • "metadata": {
    },
  • "operations": [],
  • "version": "22596363b3de40b06f981fb85d82312e8c0ed511"
}

Set Express Checkout discount codes

Changes the order.discount_codes submitted by end user in the Express Checkout flow.

If the express.discount_codes_callback_url is set, the session will be updated with discount on the order and the shipping options.

path Parameters
session_id
required
string <checkout-id>

The session ID

header Parameters
If-Unmodified-Since
string

Optional header. The put request is discarded and a 412 is returned if the header does not match the updated_at property of the session.

Request Body schema: application/json
required
discount_codes
Array of strings

Responses

Request samples

Content type
application/json
{
  • "discount_codes": [
    ]
}

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": {
    },
  • "metadata": {
    },
  • "operations": [],
  • "version": "22596363b3de40b06f981fb85d82312e8c0ed511"
}

Set gift card

Change the active gift_cards for the session. Updating with empty gift cards removes all gift cards from the session.

path Parameters
session_id
required
string <checkout-id>

The session ID

header Parameters
If-Unmodified-Since
string

Optional header. The put request is discarded and a 412 is returned if the header does not match the updated_at property of the session.

Request Body schema: application/json
required
required
Array of objects <= 1 items

Responses

Request samples

Content type
application/json
{
  • "gift_cards": [
    ]
}

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": {
    },
  • "metadata": {
    },
  • "operations": [],
  • "version": "22596363b3de40b06f981fb85d82312e8c0ed511"
}

Set Express Checkout shipping address

Deprecated in favor of PUT /v1/view/{session_id}/session/order/addresses

Changes the order.shipping_address, submitted by end user in the Express Checkout flow.

If the express.shipping_address_callback_url is set, the express.shipping_options in the response will be updated to show the available shipping options for the updated address.

path Parameters
session_id
required
string <checkout-id>

The session ID

header Parameters
If-Unmodified-Since
string

Optional header. The put request is discarded and a 412 is returned if the header does not match the updated_at property of the session.

Request Body schema: application/json
required
first_name
string
last_name
string
address_line
string

Gaustadalleen 21

address_line_2
string

PB 123

co_address
string
business_name
string

Name of the company

postal_code
string

The zip code / postal code of the address.

postal_place
string

The name of the postal code

country
string <iso3166-alpha2>

Country of the location

phone_number
string^\+?\d{5,15}$

mobile number of a person / company, ITU/E.123 format with international prefix (+PPNNNNNNNNN...)

email
string

The email address of a person or an organization

latitude
number
longitude
number
comment
string

Comment about the address

organization_number
string

The organization number of the customer.

organization_type
string

Type indicating what kind of organization it is.

customer_reference
string

The customer's reference

cost_center
string

For companies that needs to specify a cost center.

Responses

Request samples

Content type
application/json
{
  • "first_name": "John",
  • "last_name": "Doe",
  • "address_line": "string",
  • "address_line_2": "string",
  • "co_address": "Land Lord",
  • "business_name": "string",
  • "postal_code": "0349",
  • "postal_place": "Oslo",
  • "country": "NO",
  • "phone_number": "string",
  • "email": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "comment": "string",
  • "organization_number": "string",
  • "organization_type": "string",
  • "customer_reference": "string",
  • "cost_center": "string"
}

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": {
    },
  • "metadata": {
    },
  • "operations": [],
  • "version": "22596363b3de40b06f981fb85d82312e8c0ed511"
}

Set Express Checkout shipping option

Changes the selected shipping_option, submitted by end user in the Express Checkout flow.

path Parameters
session_id
required
string <checkout-id>

The session ID

header Parameters
If-Unmodified-Since
string

Optional header. The put request is discarded and a 412 is returned if the header does not match the updated_at property of the session.

Request Body schema: application/json
required
id
required
string

Id of this shipping option product.

The express checkout will group all products with the same id. Used for grouping delivery to the same address at different time slots, or for grouping deliveries to different pick up points.

line_id
required
string

Unique id of the specific configuration of this shipping product

amount
required
integer

The monetary amount of the shipping option, including VAT and discounts.

In smallest unit for the currency, e.g. cents

operator
required
string

Name of company that provides shipping service

title
required
string

A shipping option title. Eg. "Standard"

countries
Array of strings <iso3166-alpha2> [ items <iso3166-alpha2 > ]

Countries where this shipping option can be used

vat_amount
integer

The VAT of the amount parameter. Only used for display purposes.

vat
number

The VAT percentage

description
string

A short description of the shipping option product

delivery_method
string
Enum: "delivery" "pick_up" "unspecified" "none"
operator_product_id
string

The operators own id for this shipping product

object

Estimated time of arrival

object

A specified time for delivery to customer

object

Address

object <= 20 properties

Additional metadata about the shipping_option

object

Environmental data about the shipping option

thumbnail_url
string <uri>

URL to a thumbnail of the shipping option. Will be displayed when redirecting to the session. Recommended limitations for the image:

  • all images should preferrably have the same dimensions
  • max file size should be less than 2MB
object

Enable pay in-store during pick-up. The amount to be paid will be zero. Requires that the payment method dintero.zero is enabled

object (PayoutFeeSplit)

Specify how fees are handled with splits. The default behaviour is to share the fees proportional with all splits destinations

Array of objects (PayoutSplit)

An array of objects specifying how the amount should be split between sellers when using Dintero Payout

Specify an empty array if the splits will be provided during capture. auto_capture cannot be enabled when splits are defined as empty array.

Array of objects (MultiShipmentShippingOption) >= 2 items

For multiple shipments we have a single top-level shipping object that contains the shipments for the order. The shipping options defined in shipments must contain shipment_items that define what items belong to what shipment.

For multiple shipments:

  • do not define splits on the toplevel shipping option
  • do not define fee_split on the toplevel shipping option
  • the pay_in_store option is not compatible with shipments
  • empty shipments array is not allowed
  • single item multi shipping option is not allowed

Responses

Request samples

Content type
application/json
{
  • "id": "bring-pick-up-00001",
  • "line_id": "bring-pick-up-00001-location-0a1f6b",
  • "countries": [
    ],
  • "amount": 3900,
  • "vat_amount": 975,
  • "vat": 25,
  • "title": "Standard",
  • "description": "Pick up at your nearest postal office",
  • "delivery_method": "pick_up",
  • "operator": "Bring",
  • "operator_product_id": "pick-up-00001-location-0a1f6b",
  • "eta": {
    },
  • "time_slot": {
    },
  • "pick_up_address": {
    },
  • "metadata": {
    },
  • "environmental_data": {
    },
  • "thumbnail_url": "http://example.com",
  • "pay_in_store": {
    },
  • "fee_split": {
    },
  • "splits": [
    ],
  • "shipments": [
    ]
}

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": {
    },
  • "metadata": {
    },
  • "operations": [],
  • "version": "22596363b3de40b06f981fb85d82312e8c0ed511"
}

Send a verification code to the customer

Send a SMS with a payment verification code

path Parameters
session_id
required
string <checkout-id>

The session ID

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Add payment information

path Parameters
session_id
required
string <checkout-id>

The session ID

Request Body schema: application/json
required
payment_product_type
required
string

The payment product type corresponding to event

required
object (KlarnaAddress)
required
object (KlarnaAddress)
locale
required
string^[A-Za-z]{2}-[A-Za-z]{2}$

Combination of purchase country and language. Example: "en-GB"

Responses

Request samples

Content type
application/json
Example
{
  • "payment_product_type": "klarna.klarna",
  • "billing_address": {
    },
  • "shipping_address": {
    },
  • "locale": "en-GB"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

callback

Example session callbacks

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:

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:

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

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" "instabank.finance" "instabank.invoice" "instabank.installment" "instabank.postponement" "klarna.klarna" "klarna.billie" "netaxept.creditcard" "payex.creditcard" "payex.mobilepay" "payex.swish" "payex.vipps" "payex.applepay" "payex.clicktopay" "payex.googlepay" "santander.debit_account" "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

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 (VerifiedIdentity)

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

Transactions

View and perform operations on transactions

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
[
  • {
    }
]

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",
  • "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": {