Dintero API (2019-05-31)

Download OpenAPI specification:Download

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

API for managing Receipts, Discounts, Customers, Wallets and Webhooks

Introduction

The Dintero API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no "switch" for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test mode incur no cost.

Changelog

All notable changes to the API.

2019-09-31

Changed

customers: extends settings with support for configuring users customer_id_format.

customers: extends the TokenEvent definition with `expires_at read only property.

customers: extends settings with support for configuring token events expiry

management: extend settings with PayEx connections

2019-07-31

Changed

customers: extend user Address, add support for latitude, longitude and comment properties.

discounts: exclude statistics, usage and stamp count and more in response from:

Added

management: new endpoints for managing PayEx connection

customers: new endpoint for deleting a tag

discounts: new endpoint for retrieving discount usages

receipts: extend the receipt format with store.mcc property, a four-digit merchant category code for classifying the merchant

2019-06-31

Changed

scopes: The scope required for accessing endpoint has changed, we will continue to support the old scopes but they was removed from the documentation

auth: support search, limit and starting_after query parameter when listing partner accounts

Added

auth: support for issuing exchange token for a sub-account, to allow partner accounts to manage sub accounts.

2019-05-31

Changed

customers: make type and company property optional when updating a customer user

Added

auth: Support for including a Refresh Token when requesting an Access Token. Use grant-type=refresh_token to get an Access Token from a Refresh Token.

auth: Support for revoking a Refresh Token

2019-04-31

Changed

webhooks: Implement support for subscription on discount_customer_update event. The event is published after a receipt_add event or when discounts are claimed.

discounts: include statistics, usage and stamp count and more in response from:

discounts deprecate the statistics.used property, replaced by statistics.usage.

discounts moved the debit_balance property into statistics.usage.

discounts add new mixes property to the discount requirement item. The new property can be used to define Mix & Match discounts, discount that requires multiple items to be purchase to enable the reward.

2019-01-31

Changed

discounts add new private property to the discount rule object. A private discount will be excluded from public discount collection if the rule is given to all customers.

discounts: add new endpoint for getting details about a discount claim.

customers: support new customer type employee.

discounts: increase maximum limit value accepted by eindpoint:

2018-12-17

Changed

management: rename typo in Account definition all bussiness_name properties renamed to business_name

2018-11-26

Changed

discounts: extend the discount.limitation with discount_eligible, an optional property for limiting what items in a purchase is eligible for the rule.

discounts: extend the discount.limitation with discount_combination, an optional property for limiting how many other discount rules the rule can be combined with.

discounts: extend the discount.limitation with blacklist, an optional property for blacklisting items by id or group, items not eligible for discount.

receipts: extend the receipt.store object with business_name, an optional property for the store legal name.

2018-06-04

Changed

discounts: extend support for discount customer requirement. Create new discount

receipts: moved endpoint for receipt search Search by receipt_id query parameter.

customers: adding tokens to deleted customers will now fail with BAD_REQUEST. Create new Token

customers: Duplication control of customer.email is now case insensitive. email case will be ignore on Search and login.

Added

discounts: Add support for claim collection get

discounts: Add support for inactive discount by new active property on discount. create update list An inactive discount will not be included in response from public or customer

receipts: Add support for updating anonymous receipt with customer_id and discounts. Update receipt

customers: Add support for query parameter total on GET user/token lists. Includes a total-count header in the response when enabled..

discounts: Add new endpoint for listing customer a discount has been given to. Get discount customer refs

2018-04-11

Changed

receipts: rename property store.created_on_terminal_id to store.terminal_id.

discounts: Extend support for update of discount rule to allow update of limitation and requirement Update Discount Include updated_by property container the user/client that last updated the discount rule.

customers: Add support for delete_token_events parameter when creating new customer token

receipts: extend receipt.discount.refs. Add statistics object and stamp property to refs. The statistics object includes total amount, usage, stamp and current debit_balance.

receipts: correct type of receipt.discount.refs.items.amount to integer (was string).

customers: filter token events by since_datetime. Get token events

customers: delete customer and all tokens owed by the customer in one request when using delete_tokens query parameter. Delete customer

customers: token event status. The status in response from Find / Add token events will now be set to customer.status if a customer with status is included in the response.

discounts: filter discounts. Allow the result from Discount Collection to be filtered by state, since_datetime, purchase_from and purchase_to.

2018-02-15

Changed

discounts: change default item.quantity requirement from 1 to 0. Allows discount on items where quantity is in weigth/volume and value is < 1 by default.

customeres: add minimum length for token token_id/type/value

discounts: add minimum length for token token_id/type/value/customer_id

Added

discounts: add new reward type discount_debit

customers: add endpoint for GET/DELETE token events

2018-02-02

Added

receipts: extend receipt.discounts.refs. Include amount and how the amount was applied to the receipt.items in discount.refs (see response from /discounts/available_for_receipt for example)

discounts: add links and metadata property to the discount. Support adding links related to the discount and any key/value metadata

customers: add type property to the customer. Support multiple customer types, add support for Company type for additional properties

Changed

customers: move endpoints for retrieving/updating token (events), use one endpoint for both retrieving and updating details about a token

2017-12-04

Added

discounts: add type property to the discount. The value is calculated from the discount.requirement, stating if the discount is given on the receipt or limited to specific items.

receipts: add refs to receipt discounts. The value is used to record the reference between the owner of the discount and how many times the discount was used on the purchase.

receipts: add monetary string properties suffixed with _dwh. The new values can be used to store monetary value with a resolution higher than the smallest unit for the currency.

Changed

discounts: change type of properties to support decimal values.

  • discount.reward.value discount.requirement.item.quantity

discounts: rename reward type enums.

  • discount_total_amount => discount_amount
  • discount_percent_amount => discount_percent
  • discount_new_item_price => discount_item_new_price
  • discount_item => discount_item_quantity
  • discount_item_percent_amount => discount_item_percent

discounts: define required properties for a discount requirement.

  • requirement.purchase_from requirement.purchase_to

receipts: define required properties for a receipt.

  • receipt.store.id receipt.receipt_id receipt.purchase_at

receipts: move customer_id from receipt customer to receipt.

2017-11-22

Changed

receipts: move receipt customer_* properties into a customer object.

  • customer_id => customer.customer_id
  • customer_token_id => customer.token.token_id
  • customer_token => customer.token.value
  • customer_token_type => customer.token.value
  • customer_pays_tax => customer.pays_tax

Added

discounts: add support for discount rule with customer.status requirement.

receipts: add support for more customer properties in the receipt, (first_name, last_name, email, phone_number, metadata, address and status).

receipts: add support for adding delivery details to the receipt. receipt.delivery.

2017-10-29

Added

receipts: add line_id property to Receipt infocode_items (InfoCodeItem).

Changed

global: change aid parameter format from UUID to a string with 9 characters.

global: fix type, rename read-only change_at property to changed_at.

global: improve description on currency and amount* properties.

2017-10-27

Changed

receipts: change dimension_lines property to dimension for Receipt items (ReceiptItem).

receipts: fix typo, rename card_amound property to card_amount for Payment card_info (CardInfo).

Downloads

Download the OpenAPI specification

customers : API for managing customers

discounts : API for managing discount for customers

hooks : API for managing webhooks

receipts : API for managing receipts

wallets : API for managing virtuall cards, digital gift cards and transactions

Authentication

clientAuth

Authorizatoin by using the Basic schema with client_id and client_secret as username/password

Security scheme type: HTTP
HTTP Authorization Scheme basic

JWT

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

Use Get Token to get an access token

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

authenticate

Authorize Passwordless link

post /accounts/{oid}/auth/authorize
https://api.dintero.com/v1/accounts/{oid}/auth/authorize

This endpoint is used to authorize Passwordless link sent to user by email/sms.

A valid request will redirect to This is the OAuth 2.0 grant that Client-side web apps utilize in order to access an API.

Authorizations:
path Parameters
oid
required
string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$>

An id that uniquely identifies the account or owner (partner)

query Parameters
audience
required
string

The unique identifier of the target API you want to access.

response_type
required
string
Value: "authenticate"

This will specify the type of token you will receive at the end of the flow. Use token to get only an access_token

If response_type=token, after the user authenticates with the provider, this will redirect them to your application callback URL while passing the access_token in the address location.hash. This is used for Single Page Apps and on Native Mobile SDKs.

client_id
required
string

Your application's Client ID.

verification_code
required
string

one-time verification-code

scope
string
Value: "openid"

The scopes which you want to request authorization for.

state
string

An opaque value the clients adds to the initial request that Dintero includes when redirecting the back to the client. This value must be used by the client to prevent CSRF attacks.

redirect_uri
string

The URL to which Dintero will redirect the browser after authorization has been granted by the user.

The redirect_uri value must be specified as a valid callback URL under your Client's Settings.

connection
string

The name of the connection configured to your client.

Responses

302

Found

400

Bad / Invalid request

401

Access forbidden, invalid JWT token was used

403

Forbidden

500

Unexpected Error

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "error":