Checkout API (LATEST)

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

Changelog

All notable changes to the API.

2024-03-01

update: Transactions can be filtered by customer_id

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
Authorizations:
apikeyJWT
query Parameters
include_session
boolean

Include all details about the session created

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

Feature toggles that will change how the API works.

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

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

The name of the ecommerce solution

Example: woocommerce

Dintero-System-Version
string <= 120 characters

The version number of the ecommerce solution

Example: 5.4

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

The name of the ecommerce plugin

Example: Dintero.Checkout.WooCommerce

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

The version number of the ecommerce plugin

Example: 2.3.4

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

configuration profile

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

Configuration for checkboxes that should be part of the checkout

object (PaymentConfiguration)

Override configuration for the profile.

object (Merchant)

Configure merchant information used in the checkout.

object

Present only for Express Checkout sessions.

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

Endpoints used in the Express Checkout flow.

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

Additional metadata about the resource

Responses

Request samples

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

Response samples

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

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

List checkout sessions

List all Checkout sessions 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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get checkout session details

scopes:

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

The session ID

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

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

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

Responses

Response samples

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