Checkout API (2019-05-01)

Download OpenAPI specification:Download

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

Changelog

All notable changes to the API.

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.

POST /v1/sessions-profile

POST /v1/sessions

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

POST /v1/sessions-profile

new: support cancel of session

POST /v1/sessions/{session_id}/cancel

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.

POST /v1/sessions

POST /v1/sessions-profile

2019-06-01

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

POST /v1/sessions/{session_id}/pay

changed*: In SessionMeta events, extend event with details object and enumerate the event names available.

GET /v1/sessions/{session_id}

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

PUT /v1/admin/checkout

PUT /v1/admin/gateways/instabank

POST /v1/admin/session/profiles

POST /v1/sessions

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.

POST /v1/sessions-profile

POST /v1/sessions

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.

Create Client

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

PUT /admin/checkout

POST /admin/gateways/{gateway}/status

PUT /admin/gateways/instabank

PUT /admin/gateways/vipps

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 or a Sale Location. See relevant resource for more information.

POST /v1/locations/{location_id}/qr

POST /v1/sessions/{session_id}/qr

POST /v1/locations/{location_id}/checkout/{session_id}

DELETE /v1/locations/{location_id}/checkout/{session_id}

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.

GET /v1/transactions

2018-11-24

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

POST /v1/sessions-profile

POST /v1/sessions

Authentication

JWT

Bearer authentication (also called token authentication) should be used when accessing the API.

Use Get Token to get an access token for client credentials

Authorization by using the Bearer schema The content of the header should look like the following:

Authorization: Bearer {access_token}

where the access_token is JSON Web Tokens (JWT).

Security scheme type:	API Key
Header parameter name:	Authorization

apikey

X-API-Key authentication for accessing regular endpoints. Use Create api-key to create a key.

The content of the header should look like the following:

x-api-key: {api_key}

Security scheme type:	API Key
Header parameter name:	x-api-key

adminKey

X-API-Key authentication for accessing admin endpoints. Use Create api-key to create a key.

The content of the header should look like the following:

x-api-key: {api_key}

Security scheme type:	API Key
Header parameter name:	x-api-key

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

post /sessions-profile

https://checkout.dintero.com/v1/sessions-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

Request Body schema: application/json

order required	object
url required	object
profile_id required	string configuration profile
customer	object
expires_at	string <date-time>
configuration	object Override configuration for the profile.

Responses

200

checkout session created

400

Bad / Invalid request

401

Access forbidden, invalid JWT token was used

403

Forbidden

500

Unexpected Error

Request samples

Payload

application/json

Copy

Expand all Collapse all

{

"url":
{
- "return_url": "https://example.com/accept",
- "callback_url": "https://example.com/callback"
},
"customer":
{
- "email": "john.doe@example.com",
- "phone_number": "+4799999999"
},
"order":
{
- "amount": 29990,
- "vat_amount": 6000,
- "currency": "NOK",
- "merchant_reference": "string",
- "shipping_address":
  {
  - "first_name": "John",
  - "last_name": "Doe",
  - "address_line": "string",
  - "postal_code": "O349",
  - "postal_place": "Oslo",
  - "country": "NO"
  },
- "billing_address":
  {
  - "first_name": "John",
  - "last_name": "Doe",
  - "address_line": "string",
  - "postal_code": "O349",
  - "postal_place": "Oslo",
  - "country": "NO"
  },
- "partial_payment": false,
- "items":
  [
  - {
    "id": "item_01",
    "groups":
    [
    {
    "id": "B234",
    "name": "Stol"
    }
    ],
    "line_id": "1",
    "description": "Stablestol",
    "quantity": 1,
    "amount": 29990,
    "vat_amount": 6000,
    "vat": 25
    }
  ]
},
"expires_at": "2019-07-12T11:27:09Z",
"configuration":
{
- "auto_capture": true,
- "publish":
  [
  - {
    "channel": "sms",
    "type": "checkout-link"
    }
  ],
- "default_payment_type": "instabank.finance",
- "instabank":
  {
  - "finance":
    {
    "enabled": true
    },
  - "invoice":
    {
    "enabled": true
    }
  },
- "payex":
  {
  - "dynamic_descriptor": "string",
  - "swish":
    {
    "enabled": true
    },
  - "creditcard":
    {
    "enabled": true
    }
  },
- "vipps":
  {
  - "enabled": true,
  - "dynamic_descriptor": "string"
  }
},
"profile_id": "string"

}

Response samples

application/json

Copy

Expand all Collapse all

{

"id": "string",
"url": "https://checkout.api.dintero.com/v1/view/9ea1610a357dc8189081c4cb955f26f612d91367",
"publish":
[
- {
  - "channel": "sms",
  - "type": "checkout-link",
  - "status": "sent"
  }
]

}

Create a checkout session

post /sessions

https://checkout.dintero.com/v1/sessions

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

Request Body schema: application/json

order required	object
url required	object
configuration required	object (PaymentConfiguration)
customer	object
expires_at	string <date-time>

Responses

200

checkout session created

400

Bad / Invalid request

401

Access forbidden, invalid JWT token was used

403

Forbidden

500

Unexpected Error

Request samples

Payload

application/json

Copy

Expand all Collapse all

{

"url":
{
- "return_url": "https://example.com/accept",
- "callback_url": "https://example.com/callback"
},
"customer":
{
- "email": "john.doe@example.com",
- "phone_number": "+4799999999"
},
"order":
{
- "amount": 29990,
- "vat_amount": 6000,
- "currency": "NOK",
- "merchant_reference": "string",
- "shipping_address":
  {
  - "first_name": "John",
  - "last_name": "Doe",
  - "address_line": "string",
  - "postal_code": "O349",
  - "postal_place": "Oslo",
  - "country": "NO"
  },
- "billing_address":
  {
  - "first_name": "John",
  - "last_name": "Doe",
  - "address_line": "string",
  - "postal_code": "O349",
  - "postal_place": "Oslo",
  - "country": "NO"
  },
- "partial_payment": false,
- "items":
  [
  - {
    "id": "item_01",
    "groups":
    [
    {
    "id": "B234",
    "name": "Stol"
    }
    ],
    "line_id": "1",
    "description": "Stablestol",
    "quantity": 1,
    "amount": 29990,
    "vat_amount": 6000,
    "vat": 25
    }
  ]
},
"expires_at": "2019-07-12T11:27:09Z",
"configuration":
{
- "auto_capture": true,
- "publish":
  [
  - {
    "channel": "sms",
    "type": "checkout-link"
    }
  ],
- "default_payment_type": "instabank.finance",
- "instabank":
  {
  - "finance":
    {
    "enabled": true
    },
  - "invoice":
    {
    "enabled": true
    }
  },
- "payex":
  {
  - "dynamic_descriptor": "string",
  - "swish":
    {
    "enabled": true
    },
  - "creditcard":
    {
    "enabled": true
    }
  },
- "vipps":
  {
  - "enabled": true,
  - "dynamic_descriptor": "string"
  }
}

}

Response samples

application/json

Copy

Expand all Collapse all

{

"id": "string",
"url": "https://checkout.api.dintero.com/v1/view/9ea1610a357dc8189081c4cb955f26f612d91367",
"publish":
[
- {
  - "channel": "sms",
  - "type": "checkout-link",
  - "status": "sent"
  }
]

}

List checkout sessions

get /sessions

https://checkout.dintero.com/v1/sessions

List all Checkout session 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.

Responses

200

list checkout sessions

400

Bad / Invalid request

401

Access forbidden, invalid JWT token was used

403

Forbidden

500

Unexpected Error

Response samples

application/json

Copy

Expand all Collapse all

[

{
- "id": "string",
- "created_at": "2019-07-12T11:27:09Z",
- "url":
  {
  - "return_url": "https://example.com/accept",
  - "callback_url": "https://example.com/callback"
  },
- "customer":
  {
  - "email": "john.doe@example.com",
  - "phone_number": "+4799999999"
  },
- "order":
  {
  - "amount": 29990,
  - "vat_amount": 6000,
  - "currency": "NOK",
  - "merchant_reference": "string",
  - "shipping_address":
    {
    "first_name": "John",
    "last_name": "Doe",
    "address_line": "string",
    "postal_code": "O349",
    "postal_place": "Oslo",
    "country": "NO"
    },
  - "billing_address":
    {
    "first_name": "John",
    "last_name": "Doe",
    "address_line": "string",
    "postal_code": "O349",
    "postal_place": "Oslo",
    "country": "NO"
    },
  - "partial_payment": false,
  - "items":
    [
    {
    "id": "item_01",
    "groups":
    [
    {
    "id": "B234",
    "name": "Stol"
    }
    ],
    "line_id": "1",
    "description": "Stablestol",
    "quantity": 1,
    "amount": 29990,
    "vat_amount": 6000,
    "vat": 25
    }
    ]
  },
- "expires_at": "2019-07-12T11:27:09Z",
- "configuration":
  {
  - "auto_capture": true,
  - "publish":
    [
    {
    "channel": "sms",
    "type": "checkout-link",
    "status": "sent"
    }
    ],
  - "default_payment_type": "instabank.finance",
  - "instabank":
    {
    "finance":
    {
    "enabled": true,
    "payment_plans":
    [
    {
    "id": "1",
    "terms_url": "https://example.finance.terms?id=1",
    "currency": "NOK",
    "monthly_fee": 3500,
    "interest_percent": 2100,
    "arrangement_fee": 4500,
    "annual_interest_percent": 20599,
    "payments":
    [
    {
    "capital": 0,
    "fee": 3500,
    "interest": 1050,
    "total": 4550,
    "number": 1,
    "invoide_date": "2018-09-14",
    "due_date": "2018-09-28"
    }
    ]
    }
    ]
    },
    "invoice":
    {
    "enabled": true,
    "payment_plans":
    [
    {
    "id": "1",
    "terms_url": "https://example.invoice.terms?id=1",
    "currency": "NOK",
    "monthly_fee": 3500,
    "interest_percent": 0,
    "arrangement_fee": 0,
    "annual_interest_percent": 1167,
    "total_capital": 29990,
    "total_amount": 33490,
    "total_fee": 3500,
    "total_interest": 0,
    "payments":
    [
    {
    "capital": 29990,
    "fee": 3500,
    "interest": 0,
    "total": 33490,
    "number": 1,
    "invoide_date": "2018-09-14",
    "due_date": "2018-09-28"
    }
    ]
    }
    ]
    }
    },
  - "payex":
    {
    "dynamic_descriptor": "string",
    "swish":
    {
    "enabled": true
    },
    "creditcard":
    {
    "enabled": true
    }
    },
  - "vipps":
    {
    "enabled": true,
    "dynamic_descriptor": "string"
    },
  - "merchant":
    {
    "id": "string",
    "logo_url": "http://example.com",
    "name": "TKP tech AS"
    }
  },
- "updated_at": "2019-07-12T11:27:09Z",
- "customer_ip": "string",
- "user_agent": "string",
- "events":
  [
  - {
    "id": "769952fe-86c9-4185-a1ce-aeb46da3509c",
    "name": "INITIATED",
    "created_at": "2019-07-12T11:27:08.998Z"
    },
  - {
    "name": "VISITED",
    "created_at": "2019-07-12T11:27:08.998Z"
    },
  - {
    "name": "PAY_FAILED",
    "created_at": "2019-07-12T11:27:08.998Z",
    "details":
    {
    "error": "Rejected",
    "payment_product_type": "instabank.finance"
    }
    },
  - {
    "name": "FAILED",
    "created_at": "2019-07-12T11:27:08.998Z"
    }
  ],
- "transaction_id": "string",
- "cancelled_by": "string",
- "cancelled_at": "2019-07-12T11:27:09Z"
}

]

Get checkout session details

get /sessions/{session_id}

https://checkout.dintero.com/v1/sessions/{session_id}

scopes:

admin:checkout
read:checkout

Authorizations:

apikeyJWT

path Parameters

session_id

required

string <checkout-id>

The session ID

Responses

200

checkout session

400

Bad / Invalid request

401

Access forbidden, invalid JWT token was used

403

Forbidden

404

Resource was not found

500

Unexpected Error

Response samples

application/json

Copy

Expand all Collapse all

{

"id": "string",
"created_at": "2019-07-12T11:27:09Z",
"url":
{
- "return_url": "https://example.com/accept",
- "callback_url": "https://example.com/callback"
},
"customer":
{
- "email": "john.doe@example.com",
- "phone_number": "+4799999999"
},
"order":
{
- "amount": 29990,
- "vat_amount": 6000,
- "currency": "NOK",
- "merchant_reference": "string",
- "shipping_address":
  {
  - "first_name": "John",
  - "last_name": "Doe",
  - "address_line": "string",
  - "postal_code": "O349",
  - "postal_place": "Oslo",
  - "country": "NO"
  },
- "billing_address":
  {
  - "first_name": "John",
  - "last_name": "Doe",
  - "address_line": "string",
  - "postal_code": "O349",
  - "postal_place": "Oslo",
  - "country": "NO"
  },
- "partial_payment": false,
- "items":
  [
  - {
    "id": "item_01",
    "groups":
    [
    {
    "id": "B234",
    "name": "Stol"
    }
    ],
    "line_id": "1",
    "description": "Stablestol",
    "quantity": 1,
    "amount": 29990,
    "vat_amount": 6000,
    "vat": 25
    }
  ]
},
"expires_at": "2019-07-12T11:27:09Z",
"configuration":
{
- "auto_capture": true,
- "publish":
  [
  - {
    "channel": "sms",
    "type": "checkout-link",
    "status": "sent"
    }
  ],
- "default_payment_type": "instabank.finance",
- "instabank":
  {
  - "finance":
    {
    "enabled": true,
    "payment_plans":
    [
    {
    "id": "1",
    "terms_url": "https://example.finance.terms?id=1",
    "currency": "NOK",
    "monthly_fee": 3500,
    "interest_percent": 2100,
    "arrangement_fee": 4500,
    "annual_interest_percent": 20599,
    "payments":
    [
    {
    "capital": 0,
    "fee": 3500,
    "interest": 1050,
    "total": 4550,
    "number": 1,
    "invoide_date": "2018-09-14",
    "due_date": "2018-09-28"
    }
    ]
    }
    ]
    },
  - "invoice":
    {
    "enabled": true,
    "payment_plans":
    [
    {
    "id": "1",
    "terms_url": "https://example.invoice.terms?id=1",
    "currency": "NOK",
    "monthly_fee": 3500,
    "interest_percent": 0,
    "arrangement_fee": 0,
    "annual_interest_percent": 1167,
    "total_capital": 29990,
    "total_amount": 33490,
    "total_fee": 3500,
    "total_interest": 0,
    "payments":
    [
    {
    "capital": 29990,
    "fee": 3500,
    "interest": 0,
    "total": 33490,
    "number": 1,
    "invoide_date": "2018-09-14",
    "due_date": "2018-09-28"
    }
    ]
    }
    ]
    }
  },
- "payex":
  {
  - "dynamic_descriptor": "string",
  - "swish":
    {
    "enabled": true
    },
  - "creditcard":
    {
    "enabled": true
    }
  },
- "vipps":
  {
  - "enabled": true,
  - "dynamic_descriptor": "string"
  },
- "merchant":
  {
  - "id": "string",
  - "logo_url": "http://example.com",
  - "name": "TKP tech AS"
  }
},
"updated_at": "2019-07-12T11:27:09Z",
"customer_ip": "string",
"user_agent": "string",
"events":
[
- {
  - "id": "769952fe-86c9-4185-a1ce-aeb46da3509c",
  - "name": "INITIATED",
  - "created_at": "2019-07-12T11:27:08.998Z"
  },
- {
  - "name": "VISITED",
  - "created_at": "2019-07-12T11:27:08.998Z"
  },
- {
  - "name": "PAY_FAILED",
  - "created_at": "2019-07-12T11:27:08.998Z",
  - "details":
    {
    "error": "Rejected",
    "payment_product_type": "instabank.finance"
    }
  },
- {
  - "name": "FAILED",
  - "created_at": "2019-07-12T11:27:08.998Z"
  }
],
"transaction_id": "string",
"cancelled_by": "string",
"cancelled_at": "2019-07-12T11:27:09Z"

}

Cancel session

post /sessions/{session_id}/cancel

https://checkout.dintero.com/v1/sessions/{session_id}/cancel

Cancel a session

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

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

scopes:

admin:checkout
write:checkout

Authorizations:

apikeyJWT

path Parameters

session_id

required

string <checkout-id>

The session ID

Responses

200

checkout session

400

Bad / Invalid request

401

Access forbidden, invalid JWT token was used

403

Forbidden

404

Resource was not found

500

Unexpected Error

Response samples

application/json

Copy

Expand all Collapse all

{

"id": "string",
"created_at": "2019-07-12T11:27:09Z",
"url":
{
- "return_url": "https://example.com/accept",
- "callback_url": "https://example.com/callback"
},
"customer":
{
- "email": "john.doe@example.com",
- "phone_number": "+4799999999"
},
"order":
{
- "amount": 29990,
- "vat_amount": 6000,
- "currency": "NOK",
- "merchant_reference": "string",
- "shipping_address":
  {
  - "first_name": "John",
  - "last_name": "Doe",
  - "address_line": "string",
  - "postal_code": "O349",
  - "postal_place": "Oslo",
  - "country": "NO"
  },
- "billing_address":
  {
  - "first_name": "John",
  - "last_name": "Doe",
  - "address_line": "string",
  - "postal_code": "O349",
  - "postal_place": "Oslo",
  - "country": "NO"
  },
- "partial_payment": false,
- "items":
  [
  - {
    "id": "item_01",
    "groups":
    [
    {
    "id": "B234",
    "name": "Stol"
    }
    ],
    "line_id": "1",
    "description": "Stablestol",
    "quantity": 1,
    "amount": 29990,
    "vat_amount": 6000,
    "vat": 25
    }
  ]
},
"expires_at": "2019-07-12T11:27:09Z",
"configuration":
{
- "auto_capture": true,
- "publish":
  [
  - {
    "channel": "sms",
    "type": "checkout-link",
    "status": "sent"
    }
  ],
- "default_payment_type": "instabank.finance",
- "instabank":
  {
  - "finance":
    {
    "enabled": true,
    "payment_plans":
    [
    {
    "id": "1",
    "terms_url": "https://example.finance.terms?id=1",
    "currency": "NOK",
    "monthly_fee": 3500,
    "interest_percent": 2100,
    "arrangement_fee": 4500,
    "annual_interest_percent": 20599,
    "payments":
    [
    {
    "capital": 0,
    "fee": 3500,
    "interest": 1050,
    "total": 4550,
    "number": 1,
    "invoide_date": "2018-09-14",
    "due_date": "2018-09-28"
    }
    ]
    }
    ]
    },
  - "invoice":
    {
    "enabled": true,
    "payment_plans":
    [
    {
    "id": "1",
    "terms_url": "https://example.invoice.terms?id=1",
    "currency": "NOK",
    "monthly_fee": 3500,
    "interest_percent": 0,
    "arrangement_fee": 0,
    "annual_interest_percent": 1167,
    "total_capital": 29990,
    "total_amount": 33490,
    "total_fee": 3500,
    "total_interest": 0,
    "payments":
    [
    {
    "capital": 29990,
    "fee": 3500,
    "interest": 0,
    "total": 33490,