Download OpenAPI specification:Download
API for managing Receipts, Discounts, Customers, Wallets and Webhooks
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.
Download the OpenAPI specification
Use this endpoint to obtains an access token by presenting its authorization grant
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
audience required | string The unique identifier of the target API you want to access.
The audience must be a grant associated with the client that
has |
code required | string |
grant_type required | string Value: "authorization_code" |
client_id required | string |
redirect_uri | string The redirect URL which the user agent is redirected to after finishing a login. |
{- "grant_type": "authorization_code",
- "code": "string",
- "client_id": "string",
- "redirect_uri": "string",
}
{- "access_token": "eyJhbGci...t7P4",
- "token_type": "Bearer",
- "expires_in": 86400,
- "user_info": {
- "value": {
- "sub": "c06c4afe-d9e1-4c5d-939a-177d752a0944",
- "name": "Ada Lovelace"
}
}
}
Passwordless connections do not require the user to remember a password. Instead, another mechanism is used to prove identity, such as a one-time code sent through email or SMS, every time the account user logs in.
authorization_code
to allow sending verification-codescopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
client_id required | string |
connection required | string Enum: "email" "sms" How to send the code to the user. |
audience required | string The unique identifier of the target API you want to access. |
string The user's email address | |
type | string Default: "customer" Enum: "company" "customer" Passwordless for type company/customer requires that the email is registered to a customers users |
send | string Default: "code" Value: "code" Use |
login_session_id | string Use |
{- "audience": "string",
- "client_id": "string",
- "connection": "email",
- "email": "string",
- "type": "company",
- "send": "code",
- "login_session_id": "string"
}
{- "error": {
- "code": "string",
- "errors": [
- { }
], - "message": "string"
}
}
Passwordless connections do not require the user to remember a password. Instead, another mechanism is used to prove identity, such as a one-time code sent through email or SMS, every time the account user logs in.
Use this endpoint to generate a one-time verification-code that can be sent to the user.
The client_id/audience must have a grant with type
authorization_code
to allow creating a verification-code
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
audience required | string The unique identifier of the target API you want to grant the user |
client_id required | string The client whoose grants will be granted to the user, the |
user_id required | string The user_id / subject to grant access |
{- "audience": "string",
- "client_id": "string",
- "user_id": "string"
}
{- "verification_code": "string"
}
Use this endpoint to redirect to an URL with a ID token added.
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
redirect_uri required | string <uri> ^https?://.* The HTTP URL to redirect to |
object <= 5 properties Include custom claims to the ID token. Custom claims will be
prefixed by | |
claims | Array of strings Items Enum: "name" "email" Specify optional claims to include in the ID token |
{- "custom_claims": {
- "property1": "string",
- "property2": "string"
}, - "claims": [
- "name"
]
}
{
}
Use this endpoint to invalidate a Refresh Token if it has been compromised.
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
token required | string |
{- "token": "YOUR_REFRESH_TOKEN"
}
{ }
Use this endpoint to directly request an access_token
Use HTTP Basic authentication scheme for
authenticating grant_type client_credentials
, use
client_id/client_secret as user/password.
Use HTTP Bearer authentication scheme for authenticating
grant_type authorization_code
or password
, where the
Bearer value must be a JWT toke with access to the token
endpoint.
Use HTTP Bearer authentication scheme for authenticating
grant_type account_user_token
, where the Bearer value
must be a account user JWT token.
Use ID token as Bearer toke if the user was authenticated externally. The ID must include a
Use HTTP Bearer authentication scheme for authenticating
grant_type refresh_token
where the Bearer value must
be an Access Token for the clients that was used to create
the Refresh Token.
When a request is made to the endpoint to get an access token,
normally you either get an error, or you get an access token.
However, when the MFA is enabled, the endpoint may return a new
error with error.code: mfa_required
.
When an mfa_required
error is returned, the client must perform
a challenge
. This is done by sending a request to the
auth/mfa/challenge endpoint
To verify MFA using an OOB challenge, the client must make a request to
this endpoint with grant_type=mfa-oob
. Include the oob_code
you
received from the challenge response, as well as the mfa_token
you
received as part of mfa_required error.
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
grant_type required | string |
{- "grant_type": "account_user"
}
{- "access_token": "eyJhbGci...t7P4",
- "token_type": "Bearer",
- "expires_in": 86400,
- "refresh_token": "string"
}
Use this endpoint to exchange access_token to a sub-account
scopes:
partner_id required | string <^[PT]{1}\d{3}00000$> = 9 characters An id that uniquely identifies the partner account |
account_id required | string <^[PT]{1}\d{8}$> The account_id to create exchange access_token for |
{- "account_id": "string"
}
{- "access_token": "eyJhbGci...t7P4",
- "token_type": "Bearer",
- "expires_in": 86400,
- "refresh_token": "string"
}
Retrieve a list of all client applications
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "name": "string",
- "description": "string",
- "client_id": "string",
- "callbacks": [
- "string"
]
}
]
Creates a new client application.
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
name | string |
description | string |
client_id | string Your client ID. |
callbacks | Array of strings |
{- "name": "string",
- "description": "string",
- "client_id": "string",
- "callbacks": [
- "string"
]
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "name": "string",
- "description": "string",
- "client_id": "string",
- "callbacks": [
- "string"
], - "client_secret": "JYCRP/x7iBGWA1fun0J9laH5sEg5cP9g/4QivhfGzm4"
}
Retrieves a client by its id.
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
id required | string The id of the client |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "name": "string",
- "description": "string",
- "client_id": "string",
- "callbacks": [
- "string"
]
}
Deletes a client and all its related assets
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
id required | string The id of the client |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "name": "string",
- "description": "string",
- "client_id": "string",
- "callbacks": [
- "string"
]
}
Rotate a client secret.
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
id required | string The id of the client |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "name": "string",
- "description": "string",
- "client_id": "string",
- "callbacks": [
- "string"
], - "client_secret": "JYCRP/x7iBGWA1fun0J9laH5sEg5cP9g/4QivhfGzm4"
}
Manage your Client Grants (also called Client Credentials Grants). Using Client Grants, your Client can request an access token using its credentials (a Client ID and a Client Secret). The access token then represents your Client during API calls.
Use the Grant type to limit how the grant can be used when requesting
an access token. A Grant with type password
can only be used when
requesting an access token with grant_type set to password
.
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
audience | string <= 1 filter client grants by audience |
client_id | string <= 1 filter client grants by client_id |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "client_id": "string",
- "scope": [
- "receipts:write"
], - "type": "any",
- "oidc": {
- "client_id": "string",
- "client_secret": "string",
}
}
]
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
client_id required | string |
audience required | string |
scope required | Array of strings[ items non-empty ] |
type | string Default: "any" Enum: "any" "authorization_code" "client_credentials" "password" Limit the usage of the grant. A grant with grant_types set
to only |
object Open ID connect configuration for the Grant. The option enables client to verify the identify of the End-User based on the authentication performed by an authorization server The grant type must be set to |
{- "client_id": "string",
- "scope": [
- "receipts:write"
], - "type": "any",
- "oidc": {
- "client_id": "string",
- "client_secret": "string",
}
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "client_id": "string",
- "scope": [
- "receipts:write"
], - "type": "any",
- "oidc": {
- "client_id": "string",
- "client_secret": "string",
}
}
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
id required | string The id of the client grant to delete |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "client_id": "string",
- "scope": [
- "receipts:write"
], - "type": "any",
- "oidc": {
- "client_id": "string",
- "client_secret": "string",
}
}
Retrieve filtered list of roles that can be assigned to users.
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
search | string lookup roles matching id, name and description |
name | string lookup roles by name |
include_deleted | boolean Default: false include deleted roles in the response |
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 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, end the result contains
|
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "name": "order support",
- "description": "Administrate orders",
- "scope": [
- "read:accounts",
- "read:billing",
- "admin:shopping"
]
}
]
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
scope required | Array of strings[ items non-empty ] |
name | string |
description | string |
{- "name": "order support",
- "description": "Administrate orders",
- "scope": [
- "read:accounts",
- "read:billing",
- "admin:shopping"
]
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "name": "order support",
- "description": "Administrate orders",
- "scope": [
- "read:accounts",
- "read:billing",
- "admin:shopping"
]
}
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
role_id required | string The id of the rule to delete |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "name": "order support",
- "description": "Administrate orders",
- "scope": [
- "read:accounts",
- "read:billing",
- "admin:shopping"
]
}
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
role_id required | string The id of the rule to delete |
scope required | Array of strings[ items non-empty ] |
name | string |
description | string |
{- "name": "order support",
- "description": "Administrate orders",
- "scope": [
- "read:accounts",
- "read:billing",
- "admin:shopping"
]
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "name": "order support",
- "description": "Administrate orders",
- "scope": [
- "read:accounts",
- "read:billing",
- "admin:shopping"
]
}
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
role_id required | string The id of the rule to delete |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "name": "order support",
- "description": "Administrate orders",
- "scope": [
- "read:accounts",
- "read:billing",
- "admin:shopping"
]
}
Retrieve the JSON Web Key Set (JWKS) that can be used
to validate access_token
scopes:
oid required | string <^[PT]{1}(?=(?:.{3}|.{8})$)[0-9]*$> An id that uniquely identifies the account or owner (partner) |
[- {
- "alg": "RS256",
- "kty": "RSA",
- "use": "sig",
- "n": "lC4ehVB6W0OCtNPnz8udYH9Ao83B6EKnHA5eTcMOap_lQZ-nKtS1lZwBj4wXRVc1XmS0d2OQFA1VMQ-dHLDE3CiGfsGqWbaiZFdW7U\nGLO1nAwfDdH6xp3xwpKOMewDXbAHJlXdYYAe2ap-CE9c5WLTUBU6JROuWcorHCNJisj1aExyiY5t3JQQVGpBz2oUIHo7NRzQoKimvp\ndMvMzcYnTlk1dhlG11b1GTkBclprm1BmOP7Ltjd7aEumOJWS67nKcAZzl48Zyg5KtV11V9F9dkGt25qHauqFKL7w3wu-DYhT0hmyFc\nwn-tXS6e6HQbfHhR_MQxysLtDGOk2ViWv8AQ\n",
- "e": "AQAB",
- "kid": "a8fdc205a9f19cc1c7507a60c4f01b13d11d7fd0"
}
]
Create a new user
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
username required | string [ 1 .. 255 ] characters The user's username. |
password required | string >= 8 characters The user's password |
Array of objects (AuthUserLinks) Links to resources related to the user, links is required when MFA is enabled. | |
object (AuthUserMfa) Require Multi-factor authentication (MFA) for the user |
{- "username": "string",
- "links": [
- {
- "rel": "phone_number",
- "href": "tel:+4799999999"
}, - {
- "rel": "email",
- "href": "mailto:name@email.com"
}
], - "mfa": {
- "challenge_type": "string",
- "oob_channels": [
- "sms"
]
}, - "password": "stringst"
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "username": "string",
- "links": [
- {
- "rel": "phone_number",
- "href": "tel:+4799999999"
}, - {
- "rel": "email",
- "href": "mailto:name@email.com"
}
], - "mfa": {
- "challenge_type": "string",
- "oob_channels": [
- "sms"
]
}
}
Update existing user with new password
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
username required | string <= 255 characters Username identifying the user |
password required | string >= 8 characters The user's password |
Array of objects (AuthUserLinks) Links to resources related to the user, links is required when MFA is enabled. | |
object (AuthUserMfa) Require Multi-factor authentication (MFA) for the user |
{- "password": "stringst",
- "links": [
- {
- "rel": "phone_number",
- "href": "tel:+4799999999"
}, - {
- "rel": "email",
- "href": "mailto:name@email.com"
}
], - "mfa": {
- "challenge_type": "string",
- "oob_channels": [
- "sms"
]
}
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "username": "string",
- "links": [
- {
- "rel": "phone_number",
- "href": "tel:+4799999999"
}, - {
- "rel": "email",
- "href": "mailto:name@email.com"
}
], - "mfa": {
- "challenge_type": "string",
- "oob_channels": [
- "sms"
]
}
}
Delete existing user
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
username required | string <= 255 characters Username identifying the user |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "username": "string",
- "links": [
- {
- "rel": "phone_number",
- "href": "tel:+4799999999"
}, - {
- "rel": "email",
- "href": "mailto:name@email.com"
}
], - "mfa": {
- "challenge_type": "string",
- "oob_channels": [
- "sms"
]
}
}
Update existing users username
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
username required | string <= 255 characters Username identifying the user |
username required | string [ 1 .. 255 ] characters The user's new usernname |
{- "username": "string"
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "username": "string",
- "links": [
- {
- "rel": "phone_number",
- "href": "tel:+4799999999"
}, - {
- "rel": "email",
- "href": "mailto:name@email.com"
}
], - "mfa": {
- "challenge_type": "string",
- "oob_channels": [
- "sms"
]
}
}
Request a challenge for multi-factor authentication (MFA) based on the challenge types supported by the user.
The challenge_type is how the user will get the challenge and prove possession. Supported challenge types include:
oob
: for SMS messages or out-of-band (OOB)Use the response to request access token from the
auth/token endpoint
with grant_type=mfa_oob
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
challenge_type required | string Value: "oob" The challenge type accepted by your application |
mfa_token required | string The token received from |
oob_channel | string Default: "sms" Enum: "sms" "email" The channel to use for OOB. Can only be provided when
|
{- "challenge_type": "oob",
- "oob_channel": "sms",
- "mfa_token": "string"
}
{- "challenge_type": "oob",
- "binding_method": "prompt",
- "oob_code": "bkaiew...akas"
}
Request a recovery for user with multi-factor authentication (MFA) enabled.
A recovery is done with two out-of-band (OOB) challenges over different channels.
Use the response to request access token from the
auth/token endpoint
with grant_type=mfa_oob
.
A 403 status
with mfa_required
error will be returned on success,
use the response to request a new challenge from the
auth/mfa/challenge endpoint.
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
challenge_type required | string Value: "oob" The challenge type accepted by your application |
username required | string The end user's identifier. |
audience required | string The unique identifier of the target API you want to access. The audience must be a grant associated with the client used in the request |
oob_channel | string Default: "sms" Enum: "sms" "email" The channel to use for OOB. Can only be provided when
|
{- "challenge_type": "oob",
- "oob_channel": "sms",
- "username": "string",
}
{- "challenge_type": "oob",
- "binding_method": "prompt",
- "oob_code": "bkaiew...akas",
- "mfa_token": "string"
}
Create a new customer, customer_id
, email
and phone_number
must
be unique if specified.
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customer to create
type required | string Default: "customer" Enum: "customer" "company" "contact" "employee" "other" Describe type of a user.
|
metadata | object <= 40 properties A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format. You can unset an individual key by setting its value to null and then saving. To clear all keys, set metadata to null |
first_name | string or null |
last_name | string or null |
string or null customer email,
case insensitive duplication control prevents
multiple user with same customer@example.com is equal to CUStOMer@EXAMPLE.com | |
phone_number | string or null <^\+?[1-9]\d{1,14}$> A phone number in E.164 number formatting. |
attributes | object Custom attributes |
status | string or null Status of the customer |
favorite_store | string or null customer favorite store |
object The source that recruited the customer | |
object Customers consent for marketing in different channels | |
Array of objects (CustomerAddress) | |
object (CustomerTerm) | |
object Company details, supported when type is Company | |
gender | string or null |
date_of_birth | string or null <date> |
Array of objects The users that it is a contact for, supported when type is | |
customer_id | string <= 255 characters The customer id you have defined for the customer. (must not have trailing or leading spaces) An auto-generated customer_id will be created if no customer_id is provided. |
password | string [ 8 .. 255 ] characters The customer password. The caller must have scope
|
pin | string = 6 characters ^\d{6}$ 6 digit customer pin, can only used for MFA login. The caller must have scope
|
{- "metadata": {
- "dob_year": 1985
}, - "first_name": "John",
- "last_name": "Doe",
- "email": "customer@example.com",
- "phone_number": "+4799999999",
- "attributes": { },
- "status": "string",
- "favorite_store": "string",
- "marketing_consent": {
- "sms": {
- "consent": true
}, - "email": {
- "consent": true
}
}, - "type": "customer",
- "addresses": [
- {
- "address_line": "Sommerkroveien 34",
- "address_line_2": "PB 123",
- "postal_code": "0349",
- "postal_place": "Oslo",
- "country": "NO",
- "latitude": 59.942112,
- "longitude": 10.716991,
- "type": "custom",
- "custom_type": "string",
- "comment": "5th floor, use doorbell."
}
], - "term": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}, - "company": {
- "organization_number": "123456789MVA",
- "bussiness_name": "TKP tech AS",
- "department": "sales department",
- "industry": "computer industry",
- "website": "string",
- "number_of_employees": "string"
}, - "gender": "male",
- "date_of_birth": "1990-09-20",
- "contact_for": [
- {
- "customer_id": "string"
}
], - "customer_id": "string",
- "password": "stringst",
- "pin": "string"
}
{- "metadata": {
- "dob_year": 1985
}, - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "first_name": "John",
- "last_name": "Doe",
- "email": "customer@example.com",
- "phone_number": "+4799999999",
- "attributes": { },
- "status": "string",
- "favorite_store": "string",
- "marketing_consent": {
- "sms": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}, - "email": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}
}, - "type": "customer",
- "addresses": [
- {
- "address_line": "Sommerkroveien 34",
- "address_line_2": "PB 123",
- "postal_code": "0349",
- "postal_place": "Oslo",
- "country": "NO",
- "latitude": 59.942112,
- "longitude": 10.716991,
- "type": "custom",
- "custom_type": "string",
- "comment": "5th floor, use doorbell."
}
], - "term": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "accepted_at": "2019-08-24T14:15:22Z"
}, - "company": {
- "organization_number": "123456789MVA",
- "bussiness_name": "TKP tech AS",
- "department": "sales department",
- "industry": "computer industry",
- "website": "string",
- "number_of_employees": "string"
}, - "gender": "male",
- "date_of_birth": "1990-09-20",
- "contact_for": [
- {
- "customer_id": "string"
}
], - "customer_id": "string"
}
Check if there is users that match the parameters. The result will
match all parameters with AND
.
This endpoint must be enabled from PUT /customers/settings
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
string lookup customer by email | |
phone_number | string lookup customer by phone_number |
{- "error": {
- "code": "string",
- "errors": [
- { }
], - "message": "string"
}
}
Get all customers, limited by parameters. The result will
match all parameters with AND
.
Search is done by prefix match, and +
in phone_number/email
must be URL encoded, (+4799999999 => %2B4799999999)
Users with type contact
are by default excluded from the result,
use type=contact
or type=any
to include contact users
The response from a request that match contact users will include the users that are linked from the contact
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
token_value | string lookup customers by token value |
token_type | string lookup customer by token type |
string lookup customer by email | |
phone_number | string lookup customer by phone_number |
type | string Enum: "customer" "company" "contact" "employee" "other" "any" lookup customer by type |
search | string lookup customer where search term match name, phone number, customer_id or email. The search term will be matched with the user details |
tag_id | string lookup customers by tag id |
include_deleted | boolean Default: false include deleted customers in the response. A deleted user will only have an id/customer_id, created_at/created_by and deleted_at/deleted_by set All other details of a customer, like email or phone_number will be deleted. |
attributes_keys | Array of strings <= 4 items include customers that has all the attributes. |
attributes_values | Array of strings <= 4 items Combine with |
since_datetime | string <date-time> lookup customers that has been added or modified
since an ISO timestamp. NOTE: this parameter can't be combined
with |
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 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, end the result contains
|
total | boolean Default: false include |
[- {
- "metadata": {
- "dob_year": 1985
}, - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "first_name": "John",
- "last_name": "Doe",
- "email": "customer@example.com",
- "phone_number": "+4799999999",
- "attributes": { },
- "status": "string",
- "favorite_store": "string",
- "marketing_consent": {
- "sms": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}, - "email": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}
}, - "type": "customer",
- "addresses": [
- {
- "address_line": "Sommerkroveien 34",
- "address_line_2": "PB 123",
- "postal_code": "0349",
- "postal_place": "Oslo",
- "country": "NO",
- "latitude": 59.942112,
- "longitude": 10.716991,
- "type": "custom",
- "custom_type": "string",
- "comment": "5th floor, use doorbell."
}
], - "term": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "accepted_at": "2019-08-24T14:15:22Z"
}, - "company": {
- "organization_number": "123456789MVA",
- "bussiness_name": "TKP tech AS",
- "department": "sales department",
- "industry": "computer industry",
- "website": "string",
- "number_of_employees": "string"
}, - "gender": "male",
- "date_of_birth": "1990-09-20",
- "contact_for": [
- {
- "customer_id": "string"
}
], - "customer_id": "string"
}
]
Customer details scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customer_id required | string <= 255 characters The customer id you have defined for the customer. (must not have trailing or leading spaces) |
{- "metadata": {
- "dob_year": 1985
}, - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "first_name": "John",
- "last_name": "Doe",
- "email": "customer@example.com",
- "phone_number": "+4799999999",
- "attributes": { },
- "status": "string",
- "favorite_store": "string",
- "marketing_consent": {
- "sms": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}, - "email": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}
}, - "type": "customer",
- "addresses": [
- {
- "address_line": "Sommerkroveien 34",
- "address_line_2": "PB 123",
- "postal_code": "0349",
- "postal_place": "Oslo",
- "country": "NO",
- "latitude": 59.942112,
- "longitude": 10.716991,
- "type": "custom",
- "custom_type": "string",
- "comment": "5th floor, use doorbell."
}
], - "term": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "accepted_at": "2019-08-24T14:15:22Z"
}, - "company": {
- "organization_number": "123456789MVA",
- "bussiness_name": "TKP tech AS",
- "department": "sales department",
- "industry": "computer industry",
- "website": "string",
- "number_of_employees": "string"
}, - "gender": "male",
- "date_of_birth": "1990-09-20",
- "contact_for": [
- {
- "customer_id": "string"
}
], - "customer_id": "string"
}
Update customer properties, properties not included in the body will remain unchanged. scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customer_id required | string <= 255 characters The customer id you have defined for the customer. (must not have trailing or leading spaces) |
Customer update
first_name | string or null |
last_name | string or null |
string or null customer email,
case insensitive duplication control prevents
multiple user with same customer@example.com is equal to CUStOMer@EXAMPLE.com | |
phone_number | string or null <^\+?[1-9]\d{1,14}$> A phone number in E.164 number formatting. |
attributes | object Custom attributes |
status | string or null Status of the customer |
favorite_store | string or null customer favorite store |
object The source that recruited the customer | |
object Customers consent for marketing in different channels | |
type | string Default: "customer" Enum: "customer" "company" "contact" "employee" "other" Describe type of a user.
|
Array of objects (CustomerAddress) | |
object (CustomerTerm) | |
object Company details, supported when type is Company | |
gender | string or null |
date_of_birth | string or null <date> |
Array of objects The users that it is a contact for, supported when type is | |
password | string [ 8 .. 255 ] characters The customer password. The caller must have scope
|
pin | string = 6 characters ^\d{6}$ 6 digit customer pin, can only be used for MFA login. The caller must have scope
|
{- "first_name": "John",
- "last_name": "Doe",
- "email": "customer@example.com",
- "phone_number": "+4799999999",
- "attributes": { },
- "status": "string",
- "favorite_store": "string",
- "marketing_consent": {
- "sms": {
- "consent": true
}, - "email": {
- "consent": true
}
}, - "type": "customer",
- "addresses": [
- {
- "address_line": "Sommerkroveien 34",
- "address_line_2": "PB 123",
- "postal_code": "0349",
- "postal_place": "Oslo",
- "country": "NO",
- "latitude": 59.942112,
- "longitude": 10.716991,
- "type": "custom",
- "custom_type": "string",
- "comment": "5th floor, use doorbell."
}
], - "term": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}, - "company": {
- "organization_number": "123456789MVA",
- "bussiness_name": "TKP tech AS",
- "department": "sales department",
- "industry": "computer industry",
- "website": "string",
- "number_of_employees": "string"
}, - "gender": "male",
- "date_of_birth": "1990-09-20",
- "contact_for": [
- {
- "customer_id": "string"
}
], - "password": "stringst",
- "pin": "string"
}
{- "metadata": {
- "dob_year": 1985
}, - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "first_name": "John",
- "last_name": "Doe",
- "email": "customer@example.com",
- "phone_number": "+4799999999",
- "attributes": { },
- "status": "string",
- "favorite_store": "string",
- "marketing_consent": {
- "sms": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}, - "email": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}
}, - "type": "customer",
- "addresses": [
- {
- "address_line": "Sommerkroveien 34",
- "address_line_2": "PB 123",
- "postal_code": "0349",
- "postal_place": "Oslo",
- "country": "NO",
- "latitude": 59.942112,
- "longitude": 10.716991,
- "type": "custom",
- "custom_type": "string",
- "comment": "5th floor, use doorbell."
}
], - "term": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "accepted_at": "2019-08-24T14:15:22Z"
}, - "company": {
- "organization_number": "123456789MVA",
- "bussiness_name": "TKP tech AS",
- "department": "sales department",
- "industry": "computer industry",
- "website": "string",
- "number_of_employees": "string"
}, - "gender": "male",
- "date_of_birth": "1990-09-20",
- "contact_for": [
- {
- "customer_id": "string"
}
], - "customer_id": "string"
}
Delete single customer scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customer_id required | string <= 255 characters The customer id you have defined for the customer. (must not have trailing or leading spaces) |
delete_tokens | boolean Default: false Delete all tokens owned by the customer |
{- "metadata": {
- "dob_year": 1985
}, - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "first_name": "John",
- "last_name": "Doe",
- "email": "customer@example.com",
- "phone_number": "+4799999999",
- "attributes": { },
- "status": "string",
- "favorite_store": "string",
- "marketing_consent": {
- "sms": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}, - "email": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}
}, - "type": "customer",
- "addresses": [
- {
- "address_line": "Sommerkroveien 34",
- "address_line_2": "PB 123",
- "postal_code": "0349",
- "postal_place": "Oslo",
- "country": "NO",
- "latitude": 59.942112,
- "longitude": 10.716991,
- "type": "custom",
- "custom_type": "string",
- "comment": "5th floor, use doorbell."
}
], - "term": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "accepted_at": "2019-08-24T14:15:22Z"
}, - "company": {
- "organization_number": "123456789MVA",
- "bussiness_name": "TKP tech AS",
- "department": "sales department",
- "industry": "computer industry",
- "website": "string",
- "number_of_employees": "string"
}, - "gender": "male",
- "date_of_birth": "1990-09-20",
- "contact_for": [
- {
- "customer_id": "string"
}
], - "customer_id": "string"
}
Update customer_id for an customer
warning: Any external resources "owned" by the user, i.e
receipts, discounts etc. will not be updated with the new
customer_id.
A new metadata property dintero_change_customer_id_{timestamp}.{hash}
will be added everytime the customer_id is changed
Following data will be included in the metadata property
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customer_id required | string <= 255 characters The customer id you have defined for the customer. (must not have trailing or leading spaces) |
Customer update
customer_id | string [ 1 .. 255 ] characters New customer_id (must not have trailing or leading spaces). |
{- "customer_id": "string"
}
{- "metadata": {
- "dob_year": 1985
}, - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "first_name": "John",
- "last_name": "Doe",
- "email": "customer@example.com",
- "phone_number": "+4799999999",
- "attributes": { },
- "status": "string",
- "favorite_store": "string",
- "marketing_consent": {
- "sms": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}, - "email": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}
}, - "type": "customer",
- "addresses": [
- {
- "address_line": "Sommerkroveien 34",
- "address_line_2": "PB 123",
- "postal_code": "0349",
- "postal_place": "Oslo",
- "country": "NO",
- "latitude": 59.942112,
- "longitude": 10.716991,
- "type": "custom",
- "custom_type": "string",
- "comment": "5th floor, use doorbell."
}
], - "term": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "accepted_at": "2019-08-24T14:15:22Z"
}, - "company": {
- "organization_number": "123456789MVA",
- "bussiness_name": "TKP tech AS",
- "department": "sales department",
- "industry": "computer industry",
- "website": "string",
- "number_of_employees": "string"
}, - "gender": "male",
- "date_of_birth": "1990-09-20",
- "contact_for": [
- {
- "customer_id": "string"
}
], - "customer_id": "string"
}
Get the token events scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
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 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, end the result contains
|
since_datetime | string <date-time> Only token events added/updated at or after this time is returned
NOTE: this parameter can't be combined with |
deleted_since | string <date-time> return only token events that has been deleted |
[- {
- "id": "string",
- "status": "DELETED",
- "events": [
- {
- "created_at": "2018-01-31T16:56:33Z",
- "event": "anonymous token",
- "status": "PENDING"
}, - {
- "created_at": "2018-02-05T00:00:00Z",
- "event": "reqruited",
- "status": "DELETED"
}
]
}
]
Delete the connection between token (type/value) and list of events. Include an event in the request to store the reason for the request scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
required | object (TokenTypeValue) Lookup by token type and value |
object Record an delete event, the status will be set to DELETED. |
{- "token": {
- "type": "string",
- "value": "string"
}, - "event": {
- "event": "customer registered in webshop",
- "metadata": { }
}
}
Find details about a token, inclusive details about any customer the token belongs to and any token events recorded Include event in the request to update the status of the token scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
required | object (TokenTypeValue) Lookup by token type and value |
object (TokenEvent) Record event data about a token An event can be created before the customer exist and before the token has been added to the customer |
{- "token": {
- "type": "string",
- "value": "string"
}, - "event": {
- "event": "customer declined signup in store",
- "status": "OPT_OUT",
- "metadata": {
- "store_id": "SID1234"
}
}
}
{- "id": "string",
- "customer": {
- "metadata": {
- "dob_year": 1985
}, - "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "first_name": "John",
- "last_name": "Doe",
- "email": "customer@example.com",
- "phone_number": "+4799999999",
- "attributes": { },
- "status": "string",
- "favorite_store": "string",
- "marketing_consent": {
- "sms": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}, - "email": {
- "consent": true,
- "updated_at": "2018-01-12T13:42:00Z"
}
}, - "type": "customer",
- "addresses": [
- {
- "address_line": "Sommerkroveien 34",
- "address_line_2": "PB 123",
- "postal_code": "0349",
- "postal_place": "Oslo",
- "country": "NO",
- "latitude": 59.942112,
- "longitude": 10.716991,
- "type": "custom",
- "custom_type": "string",
- "comment": "5th floor, use doorbell."
}
], - "term": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "accepted_at": "2019-08-24T14:15:22Z"
}, - "company": {
- "organization_number": "123456789MVA",
- "bussiness_name": "TKP tech AS",
- "department": "sales department",
- "industry": "computer industry",
- "website": "string",
- "number_of_employees": "string"
}, - "gender": "male",
- "date_of_birth": "1990-09-20",
- "contact_for": [
- {
- "customer_id": "string"
}
], - "customer_id": "string"
}, - "token": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "token_id": "string",
- "type": "sha1:email",
- "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
- "metadata": {
- "exp_month": 10,
- "exp_year": 20,
- "mask_pan": "**** **** **** 3477"
}
}, - "status": "OPT_OUT",
- "events": [
- {
- "expires_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "event": "customer declined signup in store",
- "status": "OPT_OUT",
- "metadata": {
- "store_id": "SID1234"
}
}
]
}
Get all tokens for a Customer scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customer_id required | string <= 255 characters The customer id you have defined for the customer. (must not have trailing or leading spaces) |
type | string filter tokens on type |
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 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, end the result contains
|
total | boolean Default: false include |
include_deleted | boolean Default: true include deleted tokens in the response. |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "token_id": "string",
- "type": "sha1:email",
- "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
- "metadata": {
- "exp_month": 10,
- "exp_year": 20,
- "mask_pan": "**** **** **** 3477"
}
}
]
Create a new customer token scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customer_id required | string <= 255 characters The customer id you have defined for the customer. (must not have trailing or leading spaces) |
delete_token_events | boolean Default: false delete all token events recorded on token type/value before creating new customer token |
customer token to add
type required | string non-empty identifies how or who is resposible for the token value |
value required | string non-empty |
token_id | string [ 1 .. 255 ] characters The token id you have defined for the token. (must not have trailing or leading spaces). An auto-generated token_id will be created if no token_id is provided. |
metadata | object Additional metadata about the token or the entity the token was created from |
{- "token_id": "string",
- "type": "sha1:email",
- "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
- "metadata": {
- "exp_month": 10,
- "exp_year": 20,
- "mask_pan": "**** **** **** 3477"
}
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "token_id": "string",
- "type": "sha1:email",
- "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
- "metadata": {
- "exp_month": 10,
- "exp_year": 20,
- "mask_pan": "**** **** **** 3477"
}
}
Delete Token
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customer_id required | string <= 255 characters The customer id you have defined for the customer. (must not have trailing or leading spaces) |
tid required | string <= 255 characters The token id you have defined for the token. (must not have trailing or leading spaces) |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "token_id": "string",
- "type": "sha1:email",
- "value": "a1b79ef1a62d94ffa86b3f3d846df0ee3993af92",
- "metadata": {
- "exp_month": 10,
- "exp_year": 20,
- "mask_pan": "**** **** **** 3477"
}
}
Specify the email address of the user whose password you
would like to reset. If the call is successful, the user
will receive an email prompting them to change their password.
The caller must have scope write:accounts:/auth/users
to perform a
change password request.
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
audience required | string The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource. |
email required | string |
type required | string Enum: "customer" "company" user type to login, required as users with different type can share email |
{- "email": "string",
- "audience": "string",
- "type": "customer"
}
{- "error": {
- "code": "string",
- "errors": [
- { }
], - "message": "string"
}
}
Login a customer user, the caller must have scope
write:accounts:/auth/users
.
If MFA is enabled on account, use
write:accounts:/auth/users/no-mfa
to skip MFA.
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
credentials
audience required | string The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource. |
type required | string Enum: "customer" "company" user type to login, required as users with different type can share email |
password required | string [ 4 .. 255 ] characters The customer pin or password. The caller must have scope
|
string Required if | |
ident_type | string Enum: "phone_number" "email" Required if |
ident | string Email or phone_number, depending on the Required if |
{- "email": "string",
- "ident_type": "phone_number",
- "ident": "string",
- "audience": "string",
- "type": "customer",
- "password": "string"
}
{- "access_token": "eyJhbGci...t7P4",
- "token_type": "Bearer",
- "expires_in": 86400,
- "refresh_token": "string"
}
Initiate a Multi-Factor Authentication for a customer user, the caller must
have scope write:accounts:/auth/users
to perform a login.
Post the ident_type
, along with the ident
and secret
.
The server will return a challenge response specifying the
challenge_type
that will have to be completed to when getting an access
token from the POST /v1/accounts/{oid}/auth/token
endpoint.
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
credentials
audience required | string The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource. |
ident_type required | string Enum: "phone_number" "email" |
ident required | string Email or phone_number, depending on the |
type required | string Enum: "customer" "company" user type to login, required as users with different type can share email |
secret required | string The customers pin or password. |
{- "ident_type": "phone_number",
- "ident": "string",
- "audience": "string",
- "type": "customer",
- "secret": "string"
}
{- "links": [
- {
- "rel": "mfa_challenge",
},
], - "mfa_token": "string",
- "challenge_type": "oob",
- "oob_channel": "sms"
}
Initiate a Multi-Factor Authentication recovery login for a customer user
that has forgotten/lost their secret
.
Specify the ident_type and the ident (email or phone_number) of the user. If
the call is successful, the user will get an email with an one time recovery
code that has to be submitted to the mfa_recovery endpoint.
When a valid one time recovery has been posted the server response with a
regular MFA challenge.
Once authenticated the password or pin can be changed by updating the
customer.
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
audience required | string The unique identifier of the target API you want to access. The audience must be a grant associated with the client used when calling this resource. |
ident_type required | string Enum: "phone_number" "email" |
ident required | string Email or phone_number, depending on the |
type required | string Enum: "customer" "company" user type to login, required as users with different type can share email |
{- "ident_type": "phone_number",
- "ident": "string",
- "audience": "string",
- "type": "customer"
}
{- "links": [
- {
- "rel": "mfa_oob",
- "href": "string"
}
], - "binding_method": "prompt",
- "oob_code": "bkaiew...akas",
- "mfa_token": "string",
- "challenge_type": "oob"
}
Get the status of customer email / phone_number communication scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customer_id required | string <= 255 characters The customer id you have defined for the customer. (must not have trailing or leading spaces) |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "communication": {
- "email": {
- "verified_at": "2019-08-24T14:15:22Z",
- "allowed": true
}, - "phone_number": {
- "verified_at": "2019-08-24T14:15:22Z",
- "allowed": true
}
}
}
Verify customer email/phone_number field. Consist of to steps:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customer_id required | string <= 255 characters The customer id you have defined for the customer. (must not have trailing or leading spaces) |
field required | string Enum: "email" "phone_number" field to verify |
operation required | string Enum: "send-verification-code" "confirm-verification-code" Verify operation |
verification code
code | string Verification code sent to customer |
{- "code": "string"
}
{- "error": {
- "code": "string",
- "errors": [
- { }
], - "message": "string"
}
}
Create customer terms and conditions scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
terms to create
terms required | string |
{- "terms": "string"
}
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "terms": "string"
}
Get all customer terms and conditions scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
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 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, end the result contains
|
include_deleted | boolean Default: false include deleted terms in the response |
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "terms": "string"
}
]
Get single terms and conditions scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
tid required | string <uuid> terms id |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "terms": "string"
}
Delete the customer term scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
tid required | string <uuid> terms id |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_by": "1c92f7e1-2897-4d46-bdcc-c127a914fb4e",
- "deleted_at": "2019-08-24T14:15:22Z",
- "terms": "string"
}
Get customers settings
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
{- "users": {
- "head": {
- "enabled": false
}, - "phone_number_validation": {
- "allow_duplicates": false
}, - "customer_id_format": "uuid",
- "mfa": {
- "enabled": false,
- "login": {
- "challenge_type": "oob",
- "oob_channel": "sms"
}, - "login_recovery": {
- "challenge_type": "oob",
- "oob_channel": "sms"
}
}, - "verifications": {
- "phone_number": "sms"
}
}, - "auto_tokens": {
- "phone_number": [
- {
- "type": "SHA256"
}
], - "email": [
- {
- "type": "SHA256"
}
]
}, - "tokens": {
- "event_expiry": [
- {
- "status": "OPT_OUT",
- "time_to_live": 15780000
}
]
}, - "attributes": [
- {
- "name": "string",
- "type": "string",
- "multiple_values": false,
- "private": false
}
]
}
Update customers settings
scopes:
aid required | string <^[PT]{1}\d{8}$> = 9 characters An id that uniquely identifies the account. |
customers settings
object customers user configurations | |
object Automatically generate tokens for these properties on the customer | |
object tokens configuration | |
Array of objects user attributes |
{- "users": {
- "head": {
- "enabled": false
}, - "phone_number_validation": {
- "allow_duplicates": false
}, - "customer_id_format": "uuid",
- "mfa": {
- "enabled": false,
- "login": {
- "challenge_type": "oob",
- "oob_channel": "sms"
}, - "login_recovery": {
- "challenge_type": "oob",
- "oob_channel": "sms"
}
}, - "verifications": {
- "phone_number": "sms"
}
}, - "auto_tokens": {
- "phone_number": [
- {
- "type": "SHA256"
}
], - "email": [
- {
- "type": "SHA256"
}
]
}, - "tokens": {
- "event_expiry": [
- {
- "status": "OPT_OUT",
- "time_to_live": 15780000
}
]
}, - "attributes": [
- {