> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dintero.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.dintero.com/feedback
```json
{
"path": "/api-reference/ordersessions/create-a-session",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Create a session
> Initiate a payment session for the order.
scopes:
- admin:shopping
- write:shopping
> A session event will be added to the order
## OpenAPI
````yaml /mintlify-docs/openapi/spec-orders.yaml post /accounts/{aid}/shopping/orders/{order_id}/sessions
openapi: 3.0.0
info:
title: Shopping API
contact:
name: API Integration Support
email: integration@dintero.com
description: >
API for cart and orders
# Changelog
All notable changes to the API.
## 2025-11-30
> - **new**: Add support for order item with exchange rate information
> The new properties can be included when creating and updating draft
items
> and when updating an order
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_post)
> - [POST /v1/accounts/{aid}/shopping/draft_orders/{id}/items
](#operation/aid_draft_orders_id_items_post)
> - [PUT
/v1/accounts/{aid}/shopping/draft_orders/{id}/items/{line_id}](#operation/aid_draft_orders_id_items_line_id_put)
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](#operation/aid_orders_id_put)
## 2025-06-01
> - **new**: Add support for order item discount_lines with
`discount_subtype`
> The new property can be included when creating and updating draft items
> and when updating an order
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_post)
> - [POST /v1/accounts/{aid}/shopping/draft_orders/{id}/items
](#operation/aid_draft_orders_id_items_post)
> - [PUT
/v1/accounts/{aid}/shopping/draft_orders/{id}/items/{line_id}](#operation/aid_draft_orders_id_items_line_id_put)
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](#operation/aid_orders_id_put)
## 2021-01-10
> - **new** add support for order item status property `order.items.status`.
> The new property can be included when creating and updating drafts items
and
> when updating an order.
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_post)
> - [POST /v1/accounts/{aid}/shopping/draft_orders/{id}/items
](#operation/aid_draft_orders_id_items_post)
> - [PUT
/v1/accounts/{aid}/shopping/draft_orders/{id}/items/{line_id}](#operation/aid_draft_orders_id_items_line_id_put)
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](#operation/aid_orders_id_put)
> - **new** support updating `order.external_ids`
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](#operation/aid_orders_id_put)
## 2021-01-08
> - Extend order item with optional `external_id` property
> - **new** support updating `order.itinerary`
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](#operation/aid_orders_id_put)
## 2021-01-06
> - Extend the draft with `options.generate_order_id=ALPHANUMERIC_9_RESERVE`
> The draft `order.order_id` will be set when the new option is used.
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_post)
> - Extend the draft options with `multiple_authorizations`
> Use `options.multiple_authorizations` to enable support for
> multiple authorizations on order items.
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_post)
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](#operation/aid_orders_id_put)
> - Require `authorization_id` to be included in captures, refunds and
> cancellations if order was created with
`options.multiple_authorizations`
> enabled.
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/captures](#operation/aid_orders_id_capture_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/refunds](#operation/aid_orders_id_refunds_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/cancellations](#operation/aid_orders_id_cancellation_post)
## 2021-01-01
> - **new** support filter orders by: `itinerary_travel_mode`,
> `itinerary_arrival_address`, `itinerary_departure_address` and
> `items_discount_lines_discount_type`.
> - [GET /v1/accounts/{aid}/shopping/orders](#operation/aid_orders_get)
> - Extend the Order itinerary with new properties
> - Add support for `route_id` and `vehicle_id`.
> - Add support for `external_ids` in `arrival_address` and
> `departure_address`
> - **new** support `include_events` when updating an order
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](#operation/aid_orders_id_put)
> - [POST
/v1/accounts/{aid}/shopping/orders/{id}/comments](#operation/aid_orders_id_comments_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{id}/cancel](#operation/aid_orders_id_cancel_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{id}/close](#operation/aid_orders_id_close_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{id}/open](#operation/aid_orders_id_open_post)
> - [DELETE
/v1/accounts/{aid}/shopping/orders/{id}/comments/{comment_id}](#operation/aid_orders_id_comments_comment_id_delete)
> - **new** endpoint for deleting comment
> - [DELETE
/v1/accounts/{aid}/shopping/orders/{id}/comments/{comment_id}](#operation/aid_orders_id_comments_comment_id_delete)
## 2020-12-01
> - Request for creating authorization, capture, refund or cancellation
> can fail with `409 Conflict` error.
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/authorizations](#operation/aid_orders_id_authorization_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/captures](#operation/aid_orders_id_capture_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/refunds](#operation/aid_orders_id_refunds_post)
> - [POST
/v1/accounts/{aid}/shopping/orders/{order_id}/cancellations](#operation/aid_orders_id_cancellation_post)
## 2020-11-01
> - Extend the draft options to specify TTL for the order
> Use `options.order_time_to_live` to set expiry for when
> the order and its draft data will be removed.
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_post)
> - [PUT
/v1/accounts/{aid}/shopping/orders/{id}](#operation/aid_orders_id_put)
## 2020-09-01
> - Extend payment operations items to include `payout`
> for order items that have a payout rule
> The new property shows how the payment operation item amounts
> should be split by its payout rule destinations
> - [captures](#tag/order.captures)
> - [cancellations](#tag/order.cancellations)
> - [authorizations](#tag/order.authorizations)
> - Extend endpoint for listing draft and orders to support currency filter
> - [GET
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_get)
> - [GET /v1/accounts/{aid}/shopping/orders](#operation/aid_orders_get)
> - Extend the draft options to support replace of existing order.
> Use `options.replace="order"` option to replace an order when
> the draft is completed. This option is only valid for existing
> orders that have no payment operations registered (when draft is
completed)
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_post)
## 2020-08-01
> - Extend `include_events` query parameter to support multiple values. The
parameter accept
> now:
>
> - `false`
> - `true`
> - `api-event`
> - `service-event`.
>
> `api-event` will be excluded from the store/customer endpoints:
>
> - [GET
/v1/accounts/{aid}/shopping/stores/{sid}/orders/](#operation/aid_stores_sid_orders_get)
> - [GET
/v1/accounts/{aid}/shopping/stores/{sid}/orders/{oid}](#operation/aid_stores_sid_orders_id_get)
> - [GET
/v1/accounts/{aid}/shopping/customers/{cid}/orders/](#operation/aid_customers_cid_orders_get)
> - [GET
/v1/accounts/{aid}/shopping/customers/{cid}/orders/{oid}](#operation/aid_customers_cid_orders_id_get)
> - Support adding comments to an order
> - [POST
/v1/accounts/{aid}/shopping/orders/{id}/comments](#operation/aid_orders_id_comments_post)
> - Extend the draft options to allow alphanumeric short order_id.
> Use `options.generate_order_id` to control the ID format for generated
`order.order_id`.
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_post)
> - Create order with custom order_id. The new property is only supported
when
> creating draft with `split_draft=false`. The `order.order_id` will be
set to
> `order.id` if no order_id is provided.
> - [POST
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_post)
## 2020-07-01
> - Extend endpoint for listing draft and orders to support filtering
> - [GET
/v1/accounts/{aid}/shopping/draft_orders](#operation/aid_draft_orders_get)
> - [GET /v1/accounts/{aid}/shopping/orders](#operation/aid_orders_get)
> - Extend order with `external_ids`
> - Extend order with `external_links`.
> - Extend order itinerary and attachments
> - Add `name` and `id` to itinerary `arrival_address` and
> `departure_address. Make all address properties options
> - Add `line_ids` and `id` to itinerary and attachments
> - Add `operator` to itinerary
> - Extend `itinerary.travel_mode` with `CUSTOM`
> - Extend order events with `event_type` to support event types `api-event`
and `service-event`.
> - Extend order event with `draft_id`, a readOnly property that are
included
> in events where the order was created or updated by a draft.
> - Extend order with `itinerary` and `attachment` for including travel
details
> - Extend order items with readOnly `version` property that will be set
> when the draft order item is added or updated.
> - Extend order payment operation definition with
> `processed_by` and `payment_details`.
## 2020-06-01
> **[draft](#tag/draft)**
>
> - Extend the draft options to allow more control for how payout is
configured
> - Extend the draft order items to support including `manual_payout` to
support
> use of any payout rule when calculating the split for the order items.
> **[draft](#tag/draft)**
>
> - Extend order item with `attachment`. Add support for including details
> about car, bus and train reservation as attachment in order items.
## 2020-05-01
> **[draft](#tag/draft)**
>
> - Add `events` to draft. A event will be added to the draft events list
> when the draft is updated.
> - Add `payout` option to enable calculating the payout for the order items
> store id.
> See [Billing
API](https://docs.dintero.com/billing-api.html#operation/aid_billing_payout_rules_get)
> - Add support for dynamic payout rules via `options.payout.rules`.
> - Add `order_id` option to allow creating a draft that will be
> added to an existing order.
> - Add `split_draft` option to allow one-to-many mapping between
> draft and order
> - Add support for including store when creating a draft.
> - Add support for adding draft items with `reversed_reason`
> property. Use the property in case when an item should be reversed
> and the payment refunded.
> - Add support for item `related_item.type=reversed`, that should be
> used when reversing an existing item.
> - Add support for negative item `gross_amount` to support reversing items.
> **[order](#tag/order)**
>
> - Include authorizations and cancellations in order details
> - Include `payment_details` to the order.
> **[sessions](#tag/order.sessions)**
> Add support for creating sessions for and order
> **[refunds](#tag/order.refunds)**
> Require items to be specified when creating a refund
> **[captures](#tag/order.captures)**
> Require items to be specified when creating a capture
> **[cancellations](#tag/order.cancellations)**
> Add support for creating cancellations for an order
> **[authorizations](#tag/order.authorizations)**
> Add support for creating authorizations for an order
## 2019-07-01
> **[orders](#operation/aid_orders_get)**
> Extend order definitions with Discounts
> **[orders](#operation/aid_orders_get)** > **[store
orders](#operation/aid_stores_sid_orders_get)**
> add support for `include_events` on order requests. The order event
> `state` and `events` list will be included in the response.
>
> - [GET shopping/orders/](#operation/aid_orders_get)
> - [GET shopping/orders/{order_id}](#operation/aid_orders_id_get)
> - [GET
shopping/customers/{customer_id}/orders/](#operation/aid_customers_cid_orders_get)
> - [GET
shopping/customers/{customer_id}/orders/{order_id}](#operation/aid_customers_cid_orders_id_get)
> - [GET
shopping/stores/{store_id}/orders/](#operation/aid_stores_sid_orders_get)
> - [GET
shopping/stores/{store_id}/orders/{order_id}](#operation/aid_stores_sid_orders_id_get)
## 2019-06-01
> **[draft orders](/#tag/Draft)**
>
> - extend draft definition with optional
`options.serial_order_number_suffix`
> property.
> **[orders](#tag/Order)**
>
> - extend order definition with `courier_id` and `pickup_at` that can be
set
> and updated after the order is created
> - extend order definition with `delivery_id` that can be set after the
> the order is created
> - extend order definition with optional `pre_order` property
> - extend order definition with optional `type` property.
> - extend order shipping_address and billing_address property
> with optional `comment` property that can be used for additional
> information needed for the address.
> **[events](#tag/Events)**
>
> - allow scopes
> - `read:shopping:/orders/ANY/events`
> - `write:shopping:/orders/ANY/events`
## 2019-05-01
> **[draft orders](#operation/aid_draft_orders_get)**
>
> - filter by `status`: _open, completed, deleted_
> - filter by `created_at.gte` and `created_at.lte`
> **[customer orders](#operation/aid_customers_cid_orders_get)**
>
> - filter by `status`: _open, closed, cancelled_
> - filter by `payment_status`:
> _pending, partially_paid, paid, partially_refunded, refunded_
> - filter by `created_at.gte` and `created_at.lte`
> **[store orders](#operation/aid_stores_sid_orders_get)**
>
> - filter by `status`: _open, closed, cancelled_
> - filter by `payment_status`:
> _pending, partially_paid, paid, partially_refunded, refunded_
> - filter by `created_at.gte` and `created_at.lte`
> **[orders](#operation/aid_orders_get)**
>
> - filter by `status`: _open, closed, cancelled_
> - filter by `payment_status`:
> _pending, partially_paid, paid, partially_refunded, refunded_
> - filter by `created_at.gte` and `created_at.lte`
> - accept any `customer.id` format
> **[order payments](#tag/Order-payment)**
>
> - require `amount` and `processed_at` when
> [creating a refund](#operation/aid_orders_id_refunds_post)
> - require `amount` and `processed_at` when
> [creating a capture](#operation/aid_orders_id_capture_post)
## 2019-04-01
> **[store orders](#tag/Store-Orders)**
>
> - Add endpoint for [list orders](#operation/aid_stores_sid_orders_get) for
a store
> - Add endpoint for [get order](#operation/aid_stores_sid_orders_id_get)
for a store
> **[customer orders](#tag/Customer-Orders)**
>
> - Remove uuid format requirement on customer_id path parameter
> **[complete draft order](#operation/aid_draft_orders_id_complete_put)**
>
> - remove support for `apply_discounts` query parameter, the parameter will
> only be supported from endpoints updating the draft order.
## 2019-03-02
> **[complete draft order](#operation/aid_draft_orders_id_complete_put)**
>
> - change the response to include one or more orders created from the
> draft.
> Rename the API, Shopping API, all endpoints will now be prefixed with
>
> - `/v1/accounts/{aid}/shopping/`
> **[order](#operation/aid_orders_id_get)**
>
> - Add `salesperson_id` and `salesperson_name` properties
> - Add `delivery_at` property for specifying when the order should be
> delivered (in the future)
> **[order item](#operation/aid_orders_id_get)**
>
> - Require `percentage` in `tax_lines` for an order item
> - Add `quantity` property to `item.additions`, and allow negative
> `gross_amount`
> - Add `related_item` property that can be used to create a relationship
> between two items
> - Add `description_alias`, shorter item description for receipt
> - Add `salesperson_id` and `salesperson_name` property
## 2019-02-27
> **[order item](#operation/aid_orders_id_get)**
>
> - Add `metadata` property that can be used to included additional
> key/values on order items.
> - Add `additions` array property. The property can be used to describe
> customization the customer want to be included with the order item.
> - Add `comment` property for recording customer comments on the item
> **[order](#operation/aid_orders_id_get)**
>
> - Add `comment` property for recording customer comments on the order
# Webhooks
Use webhooks to get notification on shopping events. See
[Create new
subscription](https://docs.dintero.com/api.html#operation/aid_source_hooks_post)
for details on how to create a webhooks subscription
## Events
Following event types are supported
| Event | Description |
| -------------------------- | ---------------------------------------- |
| `shopping_draft_add` | new draft order created |
| `shopping_draft_update` | existing draft order updated |
| `shopping_draft_complete` | draft completed, includes orders created |
| `shopping_order_update` | existing order updated |
| `shopping_order_event_add` | new event added to order |
version: LATEST
license:
name: UNLICENSED
url: https://dintero.com
x-logo:
url: https://docs.dintero.com/img/dintero-dark-padded.svg
altText: Dintero Logo
servers:
- url: https://api.dintero.com/v1
- url: https://test.dintero.com/v1
security:
- JWT: []
tags:
- name: order.sessions
x-displayName: Session
description: Manage order sessions
- name: order.authorizations
description: Manage order authorizations
x-displayName: Authorizations
- name: order.captures
description: Manage order captures
x-displayName: Captures
- name: order.refunds
description: Manage order refunds
x-displayName: Refunds
- name: order.cancellations
description: Manage order cancellations
x-displayName: Cancellations
- name: draft
description: Manage draft
x-displayName: Draft
- name: draft.items
description: Manage draft items
x-displayName: Draft items
- name: order
description: Manage order
x-displayName: Order
- name: order.comments
description: Manage order comments
x-displayName: Comments
- name: order.events
description: Manage order events
x-displayName: Events
- name: order.status
description: Manage order status
x-displayName: Status
- name: order.list
description: View orders
x-displayName: Collections
- name: customer.order
description: View customer orders
x-displayName: Customer
- name: store.order
description: View store orders
x-displayName: Store
paths:
/accounts/{aid}/shopping/orders/{order_id}/sessions:
post:
tags:
- order.sessions
summary: Create a session
description: |
Initiate a payment session for the order.
scopes:
- admin:shopping
- write:shopping
> A session event will be added to the order
operationId: aid_orders_id_session_post
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/OrderId'
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrderSession'
- $ref: '#/components/schemas/SessionExpress'
- required:
- url
- profile_id
properties:
profile_id:
type: string
description: |
Configuration profile for the session to create
url:
$ref: '#/components/schemas/SessionUrls'
merchant_reference:
type: string
shipping_option:
$ref: '#/components/schemas/ShippingOption'
description: order session
required: true
responses:
'200':
$ref: '#/components/responses/OrderSession'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/AccessForbidden'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
$ref: '#/components/responses/Conflict'
'500':
$ref: '#/components/responses/ServerError'
components:
parameters:
accountId:
name: aid
description: |
An id that uniquely identifies the account.
in: path
required: true
schema:
type: string
format: ^[PT]{1}\d{8}$
minLength: 9
maxLength: 9
OrderId:
name: order_id
in: path
description: The resource identifier string
required: true
schema:
type: string
schemas:
OrderSession:
type: object
required:
- items
properties:
id:
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceId'
created_at:
readOnly: true
description: |
The date-time when the resource was created
allOf:
- $ref: '#/components/schemas/ServerTimestamp'
created_by:
readOnly: true
description: |
The ID of the user/client created the resource
allOf:
- $ref: '#/components/schemas/ResourceId'
amount:
readOnly: true
type: integer
example: 27840
description: |
Monetary amount in smallest unit for the currency success:
description: |
The result from the operation.
type: boolean
items:
description: |
Selected items from the order
type: array
items:
allOf:
- required:
- line_id
properties:
amount:
readOnly: true
type: integer
example: 27840
description: |
Monetary amount in smallest unit for the currency
line_id:
type: string
description: |
Selected order items to include in the session
processed_at:
type: string
format: date-time
description: |
The date and time when the capture was processed by payment
gateway
metadata:
type: object
description: |
Additional details about the operation
_links:
type: array
description: The links related to resource
readOnly: true
items:
$ref: '#/components/schemas/Link'
SessionExpress:
type: object
properties:
express:
description: >
### 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](/#operation/checkout_sid_json_order_shipping_address_put)
2. [Set shipping
option](/#operation/checkout_sid_json_order_items_shipping_option_put)
type: object
allOf:
- $ref: '#/components/schemas/SessionExpressUpdate'
- properties:
discount_codes:
description: |
Enable discount codes for Express Checkout
properties:
max_count:
type: number
description: >
Limit how many discount codes can be added by the
customer
callback_url:
type: string
format: uri
pattern: https?://*
example: >-
https://example.com/order/00128110/discount_codes_updated
description: >
URL that Checkout will POST to when the user has
submitted/changed
the discount codes for an express session.
Dintero will not attempt a retry after a failed delivery
attempt.
Following situations is considered as failed delivery
- HTTP status codes that are not 200.
- A request timeout (60 seconds)
- Any connection error such as connection timeout, bad
certificate, etc
The response from the callback will be used to update
the order amount,
items discount_lines and shipping options.
See [POST
example/discount_codes_callback_url](#operation/example_discount_codes_callback_url)
for details about the request and response.
shipping_address_callback_url:
type: string
format: uri
pattern: https?://*
example: https://example.com/order/00128110/address_updated
description: >
URL that Checkout will POST to when the end user has
submitted/changed
a shipping address for an express-session.
Dintero will not attempt a retry after a failed delivery
attempt.
Following situations is considered as failed delivery
- HTTP status codes that are not 200.
- A request timeout (60 seconds)
- Any connection error such as connection timeout, bad
certificate, etc
The response from the callback will be used to update the
shipping options.
See [POST
example/shipping_address_callback_url](#operation/example_shipping_address_callback_url)
for details about the request and response.
customer_types:
type: array
description: >
Limit the lind of customers that can be submitted via the
address form in the express checkout.
default:
- b2c
- b2b
items:
type: string
enum:
- b2c
- b2b
default_different_billing_shipping_address:
description: >
Configure the default behavior for how Checkout presents the
shipping and billing addresses.
If `[]`, Checkout defaults to assuming the shipping and
billing addresses are the same.
If `["b2b"]`, Checkout defaults to assuming different
addresses for B2B only.
If `["b2c"]`, Checkout defaults to assuming different
addresses for B2C only.
If `["b2b", "b2c"]`, Checkout defaults to assuming different
addresses for all customer types.
If omitted, Checkout defaults to the same behaviour as
setting `[]`.
This will only have an effect if
`allow_different_billing_shipping_address` is set.
type: array
default: []
items:
type: string
enum:
- b2c
- b2b
SessionUrls:
type: object
required:
- return_url
properties:
return_url:
type: string
format: uri
example: https://example.com/accept
description: >
URL to page where Checkout will redirect the
customer to after the Checkout process has ended.
If a transaction was completed successfully, a `transaction_id`
will be appended to the URL as a `query` string parameter
> A `transaction_id` will be appended to the URL if the
> Checkout failed with `error=capture`
> A transaction with status `ON_HOLD` must be handled as a payment
> that is pending approval, where the transaction will later be
updated
> with a final payment staus `AUTHORIZED` or `FAILED`.
> We recommend that `callback_url` is used to receive the callback
when
> the transaction changes status from `ON_HOLD` to `AUTHORIZED` or
`FAILED`.
> Alternative is to do an hourly/daily poll on the transaction to
check
> if the status has changed.
*Example*:
```
https://example.com/accept?transaction_id=T00000000.3YkJXSdSnUBXcmQSzn7uJj
```
query name | type | description | required
------------------ | :----------: | ------------------------------ |
:-----------:
transaction_id | string | Transaction Id |
false
error | string | Error code identifying cause |
false
merchant_reference | string | The merchants reference |
true
In case of that something went wrong with the payment flow, an
`error` query parameter will be appended to the URL. The value
of the error is a code identifying the cause.
error | Description
------------- | ------------
cancelled | Customer cancelled the checkout payment
authorization | Customer failed to authorize the payment
failed | The transaction has been rejected by us, or an error
has occurred during transaction processing
### configuration.channel=in_app
The `in_app` channel is intended for payments done from mobile
devices
where `url.return_url` can be set to the application's appswitch
URL.
#### initial_recipient=merchant
If the query-param `initial_recipient=merchant` is appended to the
appswitch URL, the payment app will switch directly to the app,
i.e. without doing a redirect.
**The option is not supported for:**
- payex.vipps
- payex.swish
- bambora.mobilepay
Following query parameters will be added to the `return_url`
query name | type | description | required
------------------------- | :----------: |
------------------------------ | :-----------:
transaction_id | string | Transaction
Id | false
session_id | string | Session
Id | false
error | string | Error code identifying
cause | false
payment_return_url | string | Redirect URL to Dintero
API | false
merchant_reference | string | The merchants
reference | true
If the `payment_return_url` is present, you can use it to get a url
containing the `session_id`
or `transaction_id`. `payment_return_url` will only be present when
`configuration.channel=in_app`
and `initial_recipient=merchant` is appended on the appswitch URL.
> The `payment_return_url` may initially return `202 Accepted` if
the
> payment confirmation is not ready yet.
> Once ready, a `302 Found` redirect is returned to the `return_url`
You will in this case be required to poll for status on the payment
by using the
`session_id` or `transaction_id` to poll from the endpoints:
- [GET /v1/sessions/{session_id}](#operation/checkout_session_get)
- [GET
/v1/transactions/{transaction_id}](#operation/transactions_id_get)
Poll the transaction until it has been updated with one of these
statuses:
- AUTHORIZED
- CAPTURED
- FAILED
In case no `transaction_id` is included in the return url, poll the
session to get the `transaction_id`
Example url:
`myapp://?initial_recipient=merchant&transaction_id=T12345678.abc&merchant_reference=mref123&session_id=T12345678.abd`
callback_url:
$ref: '#/components/schemas/CallbackUrl'
merchant_terms_url:
type: string
format: uri
pattern: https?://*
example: https://example.com/terms.html
description: >
URL to a webpage with the merchant's Terms of Service. Will be
linked to from the checkout.
ShippingOption:
type: object
description: |
A shipping option
required:
- id
- line_id
- amount
- operator
- title
properties:
id:
type: string
description: >
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.
example: bring-pick-up-00001
line_id:
type: string
description: |
Unique id of the specific configuration of this shipping product
example: bring-pick-up-00001-location-0a1f6b
countries:
description: Countries where this shipping option can be used
type: array
items:
type: string
format: iso3166-alpha2
example: 'NO'
amount:
type: integer
description: >
The monetary amount of the shipping option, including VAT and
discounts.
In smallest unit for the currency, e.g. cents
example: 3900
vat_amount:
type: integer
description: |
The VAT of the `amount` parameter. Only
used for display purposes.
example: 975
vat:
type: number
description: >
The VAT percentage. Supports up to 2 decimal places. If the vat is
20% the number should be 20, not 0.2.
example: 25
title:
type: string
description: |
A shipping option title. Eg. "Standard"
example: Standard
description:
type: string
description: |
A short description of the shipping option product
example: Pick up at your nearest postal office
delivery_method:
type: string
enum:
- delivery
- pick_up
- unspecified
- none
example: pick_up
operator:
type: string
description: |
Name of company that provides shipping service
example: Bring
operator_product_id:
type: string
description: |
The operators own id for this shipping product
example: pick-up-00001-location-0a1f6b
eta:
description: Estimated time of arrival
type: object
allOf:
- $ref: '#/components/schemas/RelativeTime'
- properties:
starts_at:
type: string
format: date-time
example: '2020-10-14T19:00:00Z'
ends_at:
type: string
format: date-time
example: '2020-10-14T20:00:00Z'
time_slot:
description: A specified time for delivery to customer
type: object
properties:
starts_at:
type: string
format: date-time
example: '2020-10-14T19:00:00Z'
ends_at:
type: string
format: date-time
example: '2020-10-14T20:00:00Z'
pick_up_address:
type: object
allOf:
- $ref: '#/components/schemas/OrderAddress'
- $ref: '#/components/schemas/ShippingAddressDetails'
- properties:
distance:
type: number
description: |
Distance in kilometers from the shipping_address.
metadata:
type: object
description: Additional metadata about the shipping_option
maxProperties: 20
additionalProperties:
oneOf:
- type: string
- type: number
example:
operator_dest: XAB1239
number_x: 1921
environmental_data:
type: object
description: |
Environmental data about the shipping option
required:
- description
properties:
description:
type: string
description: |
A short description of the environmental data, something like
- "Fossil free",
- "Carbon neutral"
- "Low emissions"
- "Renewable Energy Sourced"
- "Eco-certified Fleet"
example: Fossil free
details:
type: array
items:
type: object
required:
- label
- value
properties:
label:
description: |
Give context to the value field. Example:
- "CO2 emissions"
- "Energy consumption"
- "Carbon footprint"
- "Carbon offset"
- "Trees planted"
- "Renewable energy percentage"
type: string
example: Carbon offset
maxLength: 50
value:
type: string
example: 1KG CO2
maxLength: 50
thumbnail_url:
type: string
description: |
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
format: uri
ResourceId:
type: string
description: The resource ID. Defaults to UUID v4
maxLength: 40
example: bd04c959-d159-49b4-a096-2d84e014a8da
ServerTimestamp:
type: string
description: Read-only timestamp, automatically assigned on back-end.
format: date-time
readOnly: true
Link:
type: object
properties:
href:
description: The link URL
type: string
rel:
description: The link type
type: string
enum:
- draft
- events
- order
- receipt
- self
- session
- session-checkout
- transaction
required:
- href
- rel
SessionExpressUpdate:
type: object
required:
- shipping_options
properties:
shipping_options:
type: array
description: >
Shipping options that will be presented to the end user after the
end user has submitted a shipping address.
To dynamically update the shipping_options when the
_`order.shipping_address`_ is
changed by the end user in the checkout, use the
_`url.shipping_address_callback_url`_.
If the merchant is not able to ship the order to the end users shipping address, use an empty array.
If there is only one option, a free delivery, the order still has to contain one option with a _`price.amount`_ of 0.
items:
$ref: '#/components/schemas/ShippingOption'
shipping_mode:
type: string
enum:
- shipping_required
- shipping_not_required
default: shipping_required
CallbackUrl:
type: string
format: uri
pattern: https?://*
example: https://example.com/callback?method=GET
description: >
URL that Checkout will call when the session
payment is complete and the transaction has been authorized.
> **Callback is only delivered to HTTPS URLs**
> A callback done with a transaction with status `ON_HOLD` will receive
> an aditional callback (later) when the transaction state changes
status
> from `ON_HOLD`.
> The callback may be received after the transaction is `CAPTURED`
> in case when the transaction was created from a session where
> `auto_capture` was enabled.
Unlike the `return_url` the `callback_url` is system-to-system
which means delivery is guaranteed.
Once a session payment is complete the callback_url is invoked as a
`GET` request to notify your system that the payment has been approved.
- A callback_url with `method=POST` query parameter will be invoked as a
`POST` request with the transaction included in the request body.
- A callback_url with `report_error=true` will enable the callback_url
to be called if the payment failed with error `cancelled`, `authorization`
or `failed`.
- A callback_url with `delay_callback=` will delay the callback
before trying to deliver the callback. The **maximum** delay is 60 seconds.
- A callback_url with `report_event={EVENT}` will enable the
callback_url
to be called if a payment event has been applied to the transaction. Valid
values are `CAPTURE`, `REFUND` and `VOID`. The callback_url can contain
multiple `report_event` query parameters. An `event` query parameter will be
included in the request sent to the callback_url.
- A callback_url with `includes=session` will enable the callback_url
to include the session data in the body.
- A callback_url with `sid_parameter_name=sid` will change the query
param `session_id`
to `sid` to avoid false session fixation alarms in firewalls. Possible values: `sid`, `session_id`
A successful delivery to an HTTPS callback_url sometimes requires
more than one attempt. This can be the case, for example, if the server
hosting the callback_url is down for maintenance or is experiencing
heavy traffic.
Dintero attempts a retry only after a failed delivery attempt, following
situations is considered as failed delivery
- HTTP status code 100 to 101 and 500 to 599 (inclusive)
(HTTP status code 400 to 499 is considered as permanent failure)
- A request timeout (10 seconds)
- Any connection error such as connection timeout, bad certificate, etc
Failed delivery will be retried 20 times.
query name | type | description | required
------------------ | :-----------: | :--------------------------- |
:-----------
transaction_id | string | Transaction Id | true
session_id | string | Session Id | true
sid | string | Session Id when
sid_parameter_name=sid | true
merchant_reference | string | The merchants reference | true
time | string | ISO 8601 format | true
error | string | Error code |
false
event | string | event applied |
false
event_id | string | event id for callback |
false
includes | string array | include additional data |
false
> The transaction_id is optional when callback_url enables
`report_error`
> where error query will be included in case where the payment was
completed
> without creating an authorized transaction.
> It is not possible to use `https://localhost` or `http://127.0.0.1`
for
> the callback URL as Checkout backend would then call itself.
See [validating
callbacks](https://docs.dintero.com/docs/validating-callbacks) to see
how you can verify the integrity of the callbacks,
RelativeTime:
description: Relative time for delivery or pick-up
type: object
properties:
working_days:
type: array
description: >
The expected range of days until the relative time is reached.
A range of `[0,0]` means the relative time is today. `[0,3]` means
the relative time is within the next 3 days.
example:
- 1
- 2
minItems: 2
maxItems: 2
items:
type: number
minimum: 0
shipping_day_of_week:
type: number
description: |
The day of the week the relative time for shipping is on.
1 is Monday, 2 is Tuesday, ..., 7 is Sunday.
example: 3
minimum: 1
maximum: 7
arrival_day_of_week:
type: number
description: |
The day of the week the relative time for arrival is on.
1 is Monday, 2 is Tuesday, ..., 7 is Sunday.
example: 3
minimum: 1
maximum: 7
OrderAddress:
type: object
description: Address
properties:
first_name:
type: string
example: John
last_name:
type: string
example: Doe
address_line:
type: string
description: Gaustadalleen 21
address_line_2:
type: string
description: PB 123
co_address:
type: string
example: Land Lord
business_name:
type: string
description: Name of the company
postal_code:
type: string
description: The zip code / postal code of the address.
example: '0349'
postal_place:
type: string
description: The name of the postal code
example: Oslo
country:
type: string
format: iso3166-alpha2
description: Country of the location
example: 'NO'
phone_number:
type: string
pattern: ^\+?\d{5,15}$
description: |
mobile number of a person / company, ITU/E.123 format with
international prefix (+PPNNNNNNNNN...)
email:
type: string
description: |
The email address of a person or an organization
latitude:
type: number
longitude:
type: number
comment:
type: string
description: |
Comment about the address
organization_number:
type: string
description: |
The organization number of the customer.
organization_type:
type: string
description: |
Type indicating what kind of organization it is.
customer_reference:
type: string
description: The customer's reference
cost_center:
type: string
description: For companies that needs to specify a cost center.
ShippingAddressDetails:
type: object
description: Additional information about the shipping address
properties:
website_url:
type: string
description: |
The website URL of the customer.
opening_hours:
$ref: '#/components/schemas/OpeningHours'
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- message
properties:
code:
type: string
description: The code used to identify the error/warning
errors:
type: array
description: The nested error(s) encountered during validation
items:
type: object
message:
type: string
description: The human readable description of the error/warning
OpeningHours:
type: object
properties:
open_now:
type: boolean
description: |
Indicates if the location is open now.
example: true
periods:
type: array
items:
type: object
description: |
A period of time when the opening hours are valid.
properties:
opens_at:
type: string
format: time
example: '08:00'
closes_at:
type: string
format: time
example: '16:00'
day_of_week:
type: number
description: |
The day of the week when the opening hours are valid.
example: 1
timezone:
type: string
description: |
The timezone of the location.
example: Europe/Oslo
responses:
OrderSession:
description: session
content:
application/json:
schema:
$ref: '#/components/schemas/OrderSession'
BadRequest:
description: Bad / Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
AccessForbidden:
description: Access forbidden, invalid JWT token was used
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Conflict:
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ServerError:
description: Unexpected Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
JWT:
type: http
description: >
Bearer authentication (token authentication) should be used for
accessing the API.
Use [Get
Token](https://docs.dintero.com/api.html#operation/aid_auths_oauth_token_post)
to get an access token for client credentials.
Pass the token in the request header:
Authorization: Bearer {access_token}
where the **access_token** is JSON Web Tokens (JWT).
scheme: bearer
bearerFormat: JWT
````