Skip to main content
API docs by Redocly

Dojo API (2024-02-05)

Download OpenAPI specification:Download

Terms of Service

Introduction

The Dojo API is a REST API, using HTTP response codes to convey status, including successful responses and errors. Additionally, it accepts and returns JSON in the HTTP body. For information on the latest development progress, visit the changelog.

Base URLs

Use the following base URL when making requests to the API: https://api.dojo.tech/

Authentication

The Dojo API uses Basic HTTP authentication. You can generate API keys in the Developer Portal. Secret keys for the test environment use the prefix sk_sandbox_. Production keys use the prefix sk_prod_.

You must include your secret API key in the header of all requests, for example:

  --header 'content-type: application/json' \
  --header 'Authorization: Basic sk_prod_your_key' \

API requests without authentication will fail.

Additional Required Headers

The following headers are required on Terminal and Terminal Sessions API requests, requests without them will fail.

  • reseller-id - Identifies the reseller who sells software on behalf of the EPOS company. This value will be unique and provided by Dojo to each reseller.
  • software-house-id - Identifies the EPOS company whose software is generating the request. This value shouldn't be configurable, as it will remain the same for all customers using particular EPOS software. This value will be provided by Dojo.

HTTP Responses

The API returns standard HTTP response codes RFC 7231 on each request to indicate the success or otherwise of API requests. Summaries for each HTTP code are listed below:

  • 200 OK—The request was successful.

  • 201 Created—The request was successful, and a new resource was created as a result.

  • 204 No Content—The request was successful, but there is no content to send.

  • 400 Bad Request—Bad request, probably due to a syntax error.

  • 401 Unauthorized—Authentication required.

  • 403 Forbidden—The API key doesn't have permissions.

  • 404 Not Found—The resource doesn't exist.

  • 405 Method Not Allowed—The request method is known by the server but isn't supported by the target resource.

  • 409 Conflict—The request couldn't be completed because it conflicted with another request or the server's configuration.

  • 500, 502, 503, 504 Server Errors—An error occurred with our API.

Errors

Dojo follows the error response format proposed in RFC 7807, also known as Problem Details for HTTP APIs. All errors are returned in the form of JSON.

Error Schema

In case of an error, the response object contains the following fields:

  • errors [object]—A human-readable explanation of errors.

  • type [string]— A URI reference RFC 3986 that identifies the problem type.

  • title [string]—A short, human-readable summary of the error.

  • status [integer]—The HTTP status code.

  • detail [string]—A human-readable message giving more details about the error. Not always present.

  • traceId [string]—The unique identifier of the failing request.

The following example shows a possible error response:

{
    "errors": {
        "Reference": [
            "The Reference field is required."
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-a405f077df056a498323ffbcec05923f-aa63e6f4dbbc734a-01",
}

Versioning

Dojo APIs use the yyyy-mm-dd API version-naming scheme. You have to pass the version as the version header in all API calls, for example:

  --header 'content-type: application/json' \
  --header 'Authorization: Basic sk_prod_your_key' \
  --header 'version: 2024-02-05' \

When we make breaking changes to the API, we release new dated versions.

The current version is 2024-02-05.

SDKs

Use our PHP, .NET, and mobile client libraries to build your integration.

Code Samples

Get help in building your integration with our code samples.

Payment intents

Allows you to take and manage payments.

Documentation: Payment intents

Create a payment intent

Creates a payment intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Request Body schema: application/json
required
captureMode
string
Default: "Auto"
Enum: "Auto" "Manual"

The type of capture for the payment, where:

  • Auto payments are captured automatically, once authorization is complete.
  • Manual payments are captured only when a capture request is made.
required
object

The amount intended to be collected by this payment intent excluding tipsAmount and cashbackAmount.

(Money (object or null))

The tip amount.

reference
required
string [ 1 .. 60 ] characters

A unique identifier for the payment. For example, Order 236.

description
string or null <= 4096 characters

The payment description.

(PaymentCustomerDetails (object or null))

Details about the customer.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

cardHolderNotPresent
boolean or null

Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the Present Card screen and goes directly into Key Card Number

(PaymentIntentConfigRequest (object or null))

Details about the payment intent configuration.

(RequestSecurity (object or null))

Customer's device information.

Array of objects or null

The line items purchased by the customer.

Array of objects or null

The taxes applied to the items.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(ActionLink (object or null))

The link to the payment's associated actions.

expireAt
string or null <date-time>

The timestamp and date of when a payment intent will be voided, in ISO 8601 UTC format. This occurs when a payment intent is created and not yet authorized. If null, the payment intent is voided after 30 days.

autoExpireIn
string or null <timespan>

The time interval after which a Manual payment intent will be captured or reversed, in dd.hh:MM:ss format. The timestamp value must be more than 30 seconds and less than 7 days.

(AutoExpireAction (string or null))
object or null

A set of key-value pairs that you can use to store additional information.

setupIntentId
string or null

The unique identifier for the setup intent.

(OrderDetails (object or null))

Details about the order including the type and the details.

(Money (object or null))

The amount of cashback applied.

(Money (object or null))

The amount of service charge applied.

generateRemoteToken
boolean

Set to true to start accepting online payments immediately. Defaults to false.

Responses

Response Schema: application/json
id
string or null

The unique identifier of the payment intent.

captureMode
string
Default: "Auto"
Enum: "Auto" "Manual"

The type of capture for the payment, where:

  • Auto payments are captured automatically, once authorization is complete.
  • Manual payments are captured only when a capture request is made.
cardHolderNotPresent
boolean

Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the Present Card screen and goes directly into Key Card Number

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string <date-time>

The expiration date of clientSessionSecret.

(PaymentDetails (object or null))

These details about the payment will only populate once the status of the transaction is finalized.

status
string
Enum: "Created" "Authorized" "Captured" "Reversed" "Refunded" "Canceled"

Current status of the payment intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Money (object or null))

The amount intended to be collected by this payment intent excluding tipsAmount and cashbackAmount.

(Money (object or null))

The tip amount.

(Money (object or null))

The amount that was requested by this payment intent.

(Money (object or null))

The total amount after applying discounts and taxes.

refundedAmount
integer or null <int64>

The amount that was refunded.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(Money (object or null))

The total amount after applying discounts and taxes.

Array of objects or null

The line items purchased by the customer.

Array of objects or null

The taxes applied to the items.

(ActionLink (object or null))

The link to the payment's associated actions.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

(AutoExpireAction (string or null))
expireAt
string or null <date-time>

The timestamp and date of when a payment intent will be voided, in ISO 8601 UTC format. This occurs when a payment intent is created and not yet authorized. If null, the payment intent is voided after 30 days.

autoExpireIn
string or null <timespan>

The time interval after which a Manual payment intent will be captured or reversed, in dd.hh:MM:ss format. The timestamp value must be more than 30 seconds and less than 7 days.

object or null

A set of key-value pairs that you can use to store additional information.

(OrderDetails (object or null))

Details about the order including the type and the details.

setupIntentId
string or null

The unique identifier for the setup intent.

(Money (object or null))

The amount of cashback applied.

(Money (object or null))

The amount of service charge applied.

paymentLink
string or null <uri>

The URL of the generated payment link. The customer will be redirected to this URL in order to complete the payment.

Array of objects or null

The past events of the terminal session.

Array of objects or null

Details of captured payments.

Request samples

Content type
application/json
Example
{
  • "amount": {
    },
  • "reference": "Order 234",
  • "description": "Demo payment intent",
  • "captureMode": "Auto"
}

Response samples

Content type
application/json
Example
{
  • "id": "pi_sandbox_G_FeegU8WESxtY_Nct8jqw",
  • "captureMode": "Auto",
  • "cardHolderNotPresent": false,
  • "clientSessionSecretExpirationDate": "0001-01-01T00:00:00Z",
  • "status": "Created",
  • "paymentMethods": [
    ],
  • "amount": {
    },
  • "totalAmount": {
    },
  • "refundedAmount": 0,
  • "createdAt": "2024-04-07T23:25:44.802258Z",
  • "updatedAt": "2024-04-07T23:25:44.802258Z",
  • "reference": "Order 234",
  • "description": "Demo payment intent",
  • "itemLines": [ ],
  • "taxLines": [ ],
  • "merchantConfig": {
    },
  • "config": {
    },
  • "paymentSource": "api",
  • "expireAt": "2024-05-07T23:25:44.8023189Z",
  • "metadata": {
    },
  • "paymentEvents": [ ],
  • "paymentLink": "https://pay.dojo.tech:443/checkout/pi_sandbox_G_FeegU8WESxtY_Nct8jqw",
  • "terminalSessionHistory": [ ]
}

Retrieve a payment intent

Retrieves the details of a payment intent.

path Parameters
paymentIntentId
required
string or null
Example: pi_sandbox_RBMHTJ4fIkmSppDILZVCGw

The unique identifier of the payment intent.

query Parameters
returnCanceled
boolean

If the value is true, and the payment intent being retrieved has a status of Canceled, the payment intent will be returned in the response. Otherwise a 404 (not found) status code will be returned.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
id
string or null

The unique identifier of the payment intent.

captureMode
string
Default: "Auto"
Enum: "Auto" "Manual"

The type of capture for the payment, where:

  • Auto payments are captured automatically, once authorization is complete.
  • Manual payments are captured only when a capture request is made.
cardHolderNotPresent
boolean

Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the Present Card screen and goes directly into Key Card Number

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string <date-time>

The expiration date of clientSessionSecret.

(PaymentDetails (object or null))

These details about the payment will only populate once the status of the transaction is finalized.

status
string
Enum: "Created" "Authorized" "Captured" "Reversed" "Refunded" "Canceled"

Current status of the payment intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Money (object or null))

The amount intended to be collected by this payment intent excluding tipsAmount and cashbackAmount.

(Money (object or null))

The tip amount.

(Money (object or null))

The amount that was requested by this payment intent.

(Money (object or null))

The total amount after applying discounts and taxes.

refundedAmount
integer or null <int64>

The amount that was refunded.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(Money (object or null))

The total amount after applying discounts and taxes.

Array of objects or null

The line items purchased by the customer.

Array of objects or null

The taxes applied to the items.

(ActionLink (object or null))

The link to the payment's associated actions.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

(AutoExpireAction (string or null))
expireAt
string or null <date-time>

The timestamp and date of when a payment intent will be voided, in ISO 8601 UTC format. This occurs when a payment intent is created and not yet authorized. If null, the payment intent is voided after 30 days.

autoExpireIn
string or null <timespan>

The time interval after which a Manual payment intent will be captured or reversed, in dd.hh:MM:ss format. The timestamp value must be more than 30 seconds and less than 7 days.

object or null

A set of key-value pairs that you can use to store additional information.

(OrderDetails (object or null))

Details about the order including the type and the details.

setupIntentId
string or null

The unique identifier for the setup intent.

(Money (object or null))

The amount of cashback applied.

(Money (object or null))

The amount of service charge applied.

paymentLink
string or null <uri>

The URL of the generated payment link. The customer will be redirected to this URL in order to complete the payment.

Array of objects or null

The past events of the terminal session.

Array of objects or null

Details of captured payments.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/payment-intents/pi_sandbox_RBMHTJ4fIkmSppDILZVCGw?returnCanceled=SOME_BOOLEAN_VALUE", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "id": "pi_sandbox_S_zeCMipQkSG9fFmqS-ceQ",
  • "captureMode": "Auto",
  • "cardHolderNotPresent": false,
  • "clientSessionSecret": "bHte6dGrBuOoMwOgKGG3X3s2HFKERz3rbZ2SLD-H_BU_1wy-b3IgRCIUtgm7pZXh1QJC70slbaaNvm0XUcZ7T3UL8LRUMz5HK529D23ITvv_QaeIbrV8nI6Y-pxeDuqn444VqHAEok7Ue0Wsg5HgXz327lXV_A==",
  • "clientSessionSecretExpirationDate": "2024-07-25T09:19:10Z",
  • "paymentDetails": {
    },
  • "status": "Captured",
  • "paymentMethods": [
    ],
  • "amount": {
    },
  • "totalAmount": {
    },
  • "refundedAmount": 0,
  • "billingAddress": {
    },
  • "shippingDetails": {
    },
  • "createdAt": "2024-07-25T08:48:38.497Z",
  • "updatedAt": "2024-07-25T08:49:24.761Z",
  • "reference": "Order 234",
  • "description": "Demo payment intent",
  • "itemLines": [ ],
  • "taxLines": [ ],
  • "merchantConfig": {
    },
  • "config": {
    },
  • "paymentSource": "api",
  • "expireAt": "2024-08-24T08:48:38.498Z",
  • "metadata": {
    },
  • "paymentEvents": [
    ],
  • "paymentLink": "https://pay.dojo.tech:443/checkout/pi_sandbox_S_zeCMipQkSG9fFmqS-ceQ",
  • "terminalSessionHistory": [ ],
  • "captures": [ ]
}

Cancel a payment intent

Cancels a payment intent. If a payment intent's status is Created, it can be canceled. After cancellation, the payment intent status will change to Canceled and any operations will fail with an error.

path Parameters
paymentIntentId
required
string or null
Example: pi_sandbox_RBMHTJ4fIkmSppDILZVCGw

The unique identifier of the payment intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
id
string or null

The unique identifier of the payment intent.

captureMode
string
Default: "Auto"
Enum: "Auto" "Manual"

The type of capture for the payment, where:

  • Auto payments are captured automatically, once authorization is complete.
  • Manual payments are captured only when a capture request is made.
cardHolderNotPresent
boolean

Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the Present Card screen and goes directly into Key Card Number

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string <date-time>

The expiration date of clientSessionSecret.

(PaymentDetails (object or null))

These details about the payment will only populate once the status of the transaction is finalized.

status
string
Enum: "Created" "Authorized" "Captured" "Reversed" "Refunded" "Canceled"

Current status of the payment intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Money (object or null))

The amount intended to be collected by this payment intent excluding tipsAmount and cashbackAmount.

(Money (object or null))

The tip amount.

(Money (object or null))

The amount that was requested by this payment intent.

(Money (object or null))

The total amount after applying discounts and taxes.

refundedAmount
integer or null <int64>

The amount that was refunded.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(Money (object or null))

The total amount after applying discounts and taxes.

Array of objects or null

The line items purchased by the customer.

Array of objects or null

The taxes applied to the items.

(ActionLink (object or null))

The link to the payment's associated actions.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

(AutoExpireAction (string or null))
expireAt
string or null <date-time>

The timestamp and date of when a payment intent will be voided, in ISO 8601 UTC format. This occurs when a payment intent is created and not yet authorized. If null, the payment intent is voided after 30 days.

autoExpireIn
string or null <timespan>

The time interval after which a Manual payment intent will be captured or reversed, in dd.hh:MM:ss format. The timestamp value must be more than 30 seconds and less than 7 days.

object or null

A set of key-value pairs that you can use to store additional information.

(OrderDetails (object or null))

Details about the order including the type and the details.

setupIntentId
string or null

The unique identifier for the setup intent.

(Money (object or null))

The amount of cashback applied.

(Money (object or null))

The amount of service charge applied.

paymentLink
string or null <uri>

The URL of the generated payment link. The customer will be redirected to this URL in order to complete the payment.

Array of objects or null

The past events of the terminal session.

Array of objects or null

Details of captured payments.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("DELETE", "/payment-intents/pi_sandbox_RBMHTJ4fIkmSppDILZVCGw", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{}

Charge a card

Allows you to charge a card later. This is available for merchant-initiated transactions only.

path Parameters
paymentIntentId
required
string or null
Example: pi_sandbox_RBMHTJ4fIkmSppDILZVCGw

The unique identifier of the payment intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
paymentIntentId
string or null

The unique identifier of the payment intent.

status
string
Enum: "Created" "Successful" "Declined" "Failed"

Current capture status.

message
string or null

The description of the operation.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("POST", "/payment-intents/pi_sandbox_RBMHTJ4fIkmSppDILZVCGw/charge", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "paymentIntentId": "pi_sandbox_TRVit9jxx0KLSVW48a-K_w",
  • "status": "Successful",
  • "message": "DEPOSITED"
}

Update a client session secret

Updates a client session secret if the current secret key has been consumed or expired. These tokens are one-time use only. If you need to retry a payment, you must generate a new token.

path Parameters
paymentIntentId
required
string or null
Example: pi_sandbox_RBMHTJ4fIkmSppDILZVCGw

The unique identifier of the payment intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
id
string or null

The unique identifier of the payment intent.

captureMode
string
Default: "Auto"
Enum: "Auto" "Manual"

The type of capture for the payment, where:

  • Auto payments are captured automatically, once authorization is complete.
  • Manual payments are captured only when a capture request is made.
cardHolderNotPresent
boolean

Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the Present Card screen and goes directly into Key Card Number

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string <date-time>

The expiration date of clientSessionSecret.

(PaymentDetails (object or null))

These details about the payment will only populate once the status of the transaction is finalized.

status
string
Enum: "Created" "Authorized" "Captured" "Reversed" "Refunded" "Canceled"

Current status of the payment intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Money (object or null))

The amount intended to be collected by this payment intent excluding tipsAmount and cashbackAmount.

(Money (object or null))

The tip amount.

(Money (object or null))

The amount that was requested by this payment intent.

(Money (object or null))

The total amount after applying discounts and taxes.

refundedAmount
integer or null <int64>

The amount that was refunded.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(Money (object or null))

The total amount after applying discounts and taxes.

Array of objects or null

The line items purchased by the customer.

Array of objects or null

The taxes applied to the items.

(ActionLink (object or null))

The link to the payment's associated actions.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

(AutoExpireAction (string or null))
expireAt
string or null <date-time>

The timestamp and date of when a payment intent will be voided, in ISO 8601 UTC format. This occurs when a payment intent is created and not yet authorized. If null, the payment intent is voided after 30 days.

autoExpireIn
string or null <timespan>

The time interval after which a Manual payment intent will be captured or reversed, in dd.hh:MM:ss format. The timestamp value must be more than 30 seconds and less than 7 days.

object or null

A set of key-value pairs that you can use to store additional information.

(OrderDetails (object or null))

Details about the order including the type and the details.

setupIntentId
string or null

The unique identifier for the setup intent.

(Money (object or null))

The amount of cashback applied.

(Money (object or null))

The amount of service charge applied.

paymentLink
string or null <uri>

The URL of the generated payment link. The customer will be redirected to this URL in order to complete the payment.

Array of objects or null

The past events of the terminal session.

Array of objects or null

Details of captured payments.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("POST", "/payment-intents/pi_sandbox_RBMHTJ4fIkmSppDILZVCGw/refresh-client-session-secret", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{}

Change tips amount

Changes tip amount for a payment intent. Available if you enabled tipping when creating the payment intent.

Parameters
paymentIntentId
required
string or null
Example: pi_sandbox_RBMHTJ4fIkmSppDILZVCGw

The unique identifier of the payment intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Request Body schema: application/json
required
required
object

The amount intended to be collected by this payment intent excluding tipsAmount and cashbackAmount.

value
required
integer <int64>

The amount in ISO 4217 minor units, for example, "100" for 1.00 GBP.

currencyCode
required
string [ 1 .. 10 ] characters

Three-letter currency code in ISO 4217 alpha-3 format. Accepts GBP and EUR.

Responses

Response Schema: application/json
id
string or null

The unique identifier of the payment intent.

captureMode
string
Default: "Auto"
Enum: "Auto" "Manual"

The type of capture for the payment, where:

  • Auto payments are captured automatically, once authorization is complete.
  • Manual payments are captured only when a capture request is made.
cardHolderNotPresent
boolean

Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the Present Card screen and goes directly into Key Card Number

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string <date-time>

The expiration date of clientSessionSecret.

(PaymentDetails (object or null))

These details about the payment will only populate once the status of the transaction is finalized.

status
string
Enum: "Created" "Authorized" "Captured" "Reversed" "Refunded" "Canceled"

Current status of the payment intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Money (object or null))

The amount intended to be collected by this payment intent excluding tipsAmount and cashbackAmount.

(Money (object or null))

The tip amount.

(Money (object or null))

The amount that was requested by this payment intent.

(Money (object or null))

The total amount after applying discounts and taxes.

refundedAmount
integer or null <int64>

The amount that was refunded.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(Money (object or null))

The total amount after applying discounts and taxes.

Array of objects or null

The line items purchased by the customer.

Array of objects or null

The taxes applied to the items.

(ActionLink (object or null))

The link to the payment's associated actions.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

(AutoExpireAction (string or null))
expireAt
string or null <date-time>

The timestamp and date of when a payment intent will be voided, in ISO 8601 UTC format. This occurs when a payment intent is created and not yet authorized. If null, the payment intent is voided after 30 days.

autoExpireIn
string or null <timespan>

The time interval after which a Manual payment intent will be captured or reversed, in dd.hh:MM:ss format. The timestamp value must be more than 30 seconds and less than 7 days.

object or null

A set of key-value pairs that you can use to store additional information.

(OrderDetails (object or null))

Details about the order including the type and the details.

setupIntentId
string or null

The unique identifier for the setup intent.

(Money (object or null))

The amount of cashback applied.

(Money (object or null))

The amount of service charge applied.

paymentLink
string or null <uri>

The URL of the generated payment link. The customer will be redirected to this URL in order to complete the payment.

Array of objects or null

The past events of the terminal session.

Array of objects or null

Details of captured payments.

Request samples

Content type
application/json
{
  • "value": 500,
  • "currencyCode": "GBP"
}

Response samples

Content type
application/json
{
  • "id": "pi_sandbox_G_FeegU8WESxtY_Nct8jqw",
  • "captureMode": "Auto",
  • "cardHolderNotPresent": false,
  • "clientSessionSecretExpirationDate": "0001-01-01T00:00:00Z",
  • "status": "Created",
  • "paymentMethods": [
    ],
  • "amount": {
    },
  • "totalAmount": {
    },
  • "refundedAmount": 0,
  • "createdAt": "2024-04-07T23:25:44.802258Z",
  • "updatedAt": "2024-04-07T23:25:44.802258Z",
  • "reference": "Order 234",
  • "description": "Demo payment intent",
  • "itemLines": [ ],
  • "taxLines": [ ],
  • "merchantConfig": {
    },
  • "config": {
    },
  • "paymentSource": "api",
  • "expireAt": "2024-05-07T23:25:44.8023189Z",
  • "metadata": {
    },
  • "paymentEvents": [ ],
  • "paymentLink": "https://pay.dojo.tech:443/checkout/pi_sandbox_G_FeegU8WESxtY_Nct8jqw",
  • "terminalSessionHistory": [ ]
}

Change a payment intent amount

Changes the payment intent's amount. Available if you allow amount changes when creating the intent.

path Parameters
paymentIntentId
required
string or null
Example: pi_sandbox_RBMHTJ4fIkmSppDILZVCGw

The unique identifier of the payment intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Request Body schema: application/json
required
required
object

The amount intended to be collected by this payment intent excluding tipsAmount and cashbackAmount.

Array of objects or null

The line items purchased by the customer.

Array of objects or null

The taxes applied to the items.

Responses

Response Schema: application/json
id
string or null

The unique identifier of the payment intent.

captureMode
string
Default: "Auto"
Enum: "Auto" "Manual"

The type of capture for the payment, where:

  • Auto payments are captured automatically, once authorization is complete.
  • Manual payments are captured only when a capture request is made.
cardHolderNotPresent
boolean

Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the Present Card screen and goes directly into Key Card Number

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string <date-time>

The expiration date of clientSessionSecret.

(PaymentDetails (object or null))

These details about the payment will only populate once the status of the transaction is finalized.

status
string
Enum: "Created" "Authorized" "Captured" "Reversed" "Refunded" "Canceled"

Current status of the payment intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Money (object or null))

The amount intended to be collected by this payment intent excluding tipsAmount and cashbackAmount.

(Money (object or null))

The tip amount.

(Money (object or null))

The amount that was requested by this payment intent.

(Money (object or null))

The total amount after applying discounts and taxes.

refundedAmount
integer or null <int64>

The amount that was refunded.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(Money (object or null))

The total amount after applying discounts and taxes.

Array of objects or null

The line items purchased by the customer.

Array of objects or null

The taxes applied to the items.

(ActionLink (object or null))

The link to the payment's associated actions.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

(AutoExpireAction (string or null))
expireAt
string or null <date-time>

The timestamp and date of when a payment intent will be voided, in ISO 8601 UTC format. This occurs when a payment intent is created and not yet authorized. If null, the payment intent is voided after 30 days.

autoExpireIn
string or null <timespan>

The time interval after which a Manual payment intent will be captured or reversed, in dd.hh:MM:ss format. The timestamp value must be more than 30 seconds and less than 7 days.

object or null

A set of key-value pairs that you can use to store additional information.

(OrderDetails (object or null))

Details about the order including the type and the details.

setupIntentId
string or null

The unique identifier for the setup intent.

(Money (object or null))

The amount of cashback applied.

(Money (object or null))

The amount of service charge applied.

paymentLink
string or null <uri>

The URL of the generated payment link. The customer will be redirected to this URL in order to complete the payment.

Array of objects or null

The past events of the terminal session.

Array of objects or null

Details of captured payments.

Request samples

Content type
application/json
{
  • "amount": {
    }
}

Response samples

Content type
application/json
{}

Send a receipt

Sends a receipt to the email addresses you specified.

path Parameters
paymentIntentId
required
string or null
Example: pi_sandbox_RBMHTJ4fIkmSppDILZVCGw

The unique identifier of the payment intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Request Body schema: application/json
required

The email receipt request body.

emails
required
Array of strings

The list of email addresses to which the receipt should be sent.

Responses

Request samples

Content type
application/json
{
  • "emails": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "extensions": {
    }
}

Refunds

Allows you to create a reversal for payments.

Documentation: Refunds

Create a refund

Creates a refund. Refund allows you to return a payment that has previously been created as long as there have been no incremental payments or payment attempts, including unsuccessful payment attempts. You can refund the full amount or a partial amount.

path Parameters
paymentIntentId
required
string or null

The unique identifier of the payment intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

idempotencyKey
required
string or null <= 100 characters

An idempotency key is used to recognize subsequent retries of the same request. How you generate the idempotency key is up to you. The key must be unique for each new refund processed on the payment intent.

Request Body schema: application/json
required
amount
required
integer <int64>

The refund amount.

previousTransactionId
string or null <= 100 characters

The unique identifier for the previous transaction.

refundReason
string or null <= 1024 characters

The reason for the refund.

notes
string or null <= 4096 characters

A description for the refund, if applicable.

Responses

Response Schema: application/json
paymentIntentId
string or null

The unique identifier of the payment intent.

refundId
string or null

A unique identifier for the refund. It will be used to reference this refund in all operations. It is recommended to use a UUID.

refundReason
string or null

The reason for the refund.

notes
string or null

A description for the refund, if applicable.

Request samples

Content type
application/json
{
  • "amount": 1000,
  • "refundReason": "Demo refund"
}

Response samples

Content type
application/json
{
  • "paymentIntentId": "pi_sandbox_RBMHTJ4fIkmSppDILZVCGw",
  • "refundId": "rfnd_127usj",
  • "refundReason": "Demo refund",
  • "notes": null
}

Retrieve a refund

Retrieves the details of a refund that has previously been created.

path Parameters
refundId
required
string or null <= 50 characters

A unique identifier for the refund. It will be used to reference this refund in all operations. It is recommended to use a UUID.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
paymentIntentId
string or null

The unique identifier of the payment intent.

refundId
string or null

A unique identifier for the refund. It will be used to reference this refund in all operations. It is recommended to use a UUID.

refundReason
string or null

The reason for the refund.

notes
string or null

A description for the refund, if applicable.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/payment-intents/refunds/%7BrefundId%7D", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "paymentIntentId": "pi_sandbox_RBMHTJ4fIkmSppDILZVCGw",
  • "refundId": "rfnd_127usj",
  • "refundReason": "Demo refund",
  • "notes": null
}

Reversal

Allows you to create a reversal for payments.

Documentation: Reversal

Create a reversal

Reverses a payment intent.

path Parameters
paymentIntentId
required
string or null

The unique identifier of the payment intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
message
string or null

The description of the operation.

reversalId
string or null

The unique identifier for the reversal.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("POST", "/payment-intents/%7BpaymentIntentId%7D/reversal", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "id": "rvs_127usj"
}

Captures

Allows you to capture the full payment amount or part of the amount.

Documentation: Captures

Captures a payment

Captures a payment intent that has previously been created but not yet refunded or reversed. You can capture the full amount or a partial amount.

path Parameters
paymentIntentId
required
string or null
Example: pi_sandbox_RBMHTJ4fIkmSppDILZVCGw

The unique identifier of the payment intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Request Body schema: application/json
required
amount
required
integer <int64>

The capture amount. You can capture a full or partial amount. Multiple partial captures can be made on the same total.

tipsAmount
integer or null <int64>

The tip amount.

Responses

Response Schema: application/json
message
string or null

The description of the operation.

captureId
string or null

The unique identifier for the capture.

Request samples

Content type
application/json
{
  • "amount": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Demo capture",
  • "captureId": "cp_itIiJMEAvES3ynYF_Yhs2g"
}

Webhooks

Webhooks notify you when a specific event has occurred.

Documentation: Webhooks

List all events

Retrieves a list of all events.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
Array
model
string

The Webhook type.

events
Array of strings

The list of events.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/webhooks/events", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

List all subscriptions

Retrieves a list of all subscriptions.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
Array
id
string

The unique identifier for the subscription.

accountId
string or null

The unique identifier for the account.

events
Array of strings

The list of events.

url
string <uri> non-empty ^https://*.+

The URL of the Webhook endpoint.

description
string or null

The subscription description.

Array of objects

The list of secrets associated with the subscription. Used to generate signatures.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/webhooks", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "id": "ws_aNkU6yob0vOMxUlghg2oynUw",
  • "accountId": "acc_4z3k2xP17e1JQY",
  • "events": [
    ],
  • "url": "https://example.com.com/incoming-events",
  • "description": "Demo Webhooks",
  • "secrets": [
    ],
  • "createdAt": "2023-03-30T12:21:04.143Z",
  • "updatedAt": "2023-03-30T12:21:04.143Z"
}

Subscribe to an event

Creates a new subscription.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Request Body schema: application/json
required
events
required
Array of strings

The list of events.

url
required
string <uri> non-empty ^https://*.+

The URL of the Webhook endpoint.

description
string or null

The subscription description.

Responses

Response Schema: application/json
id
string

The unique identifier for the subscription.

accountId
string or null

The unique identifier for the account.

events
Array of strings

The list of events.

url
string <uri> non-empty ^https://*.+

The URL of the Webhook endpoint.

description
string or null

The subscription description.

Array of objects

The list of secrets associated with the subscription. Used to generate signatures.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "ws_aNkU6yob0vOMxUlghg2oynUw",
  • "accountId": "acc_4z3k2xP17e1JQY",
  • "events": [
    ],
  • "url": "https://example.com.com/incoming-events",
  • "description": "Demo Webhooks",
  • "secrets": [
    ],
  • "createdAt": "2023-03-30T12:21:04.143Z",
  • "updatedAt": "2023-03-30T12:21:04.143Z"
}

List all secrets

Retrieves a list of all secrets.

path Parameters
subscriptionId
required
string

The unique identifier for the subscription.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
id
string

The unique identifier for the subscription.

Array of objects

The list of secrets associated with the subscription. Used to generate signatures.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/webhooks/%7BsubscriptionId%7D/secrets", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "id": "ws_lgQzejyXb0SD8oIDE2zcqA",
  • "secrets": [
    ]
}

Generate a secret

Generates a new secret.

path Parameters
subscriptionId
required
string

The unique identifier for the subscription.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
id
string

The unique identifier for the subscription.

Array of objects

The list of secrets associated with the subscription. Used to generate signatures.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("POST", "/webhooks/%7BsubscriptionId%7D/secrets", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "secrets": [
    ]
}

Activate a secret

Activates a secret.

path Parameters
subscriptionId
required
string

The unique identifier for the subscription.

secretId
required
string

The unique identifier for the secret.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("PUT", "/webhooks/%7BsubscriptionId%7D/secrets/%7BsecretId%7D/activate", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "errors": {
    },
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "traceId": "string",
  • "detail": "string"
}

Delete a secret

Deletes a secret.

path Parameters
subscriptionId
required
string

The unique identifier for the subscription.

secretId
required
string

The unique identifier for the secret.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("DELETE", "/webhooks/%7BsubscriptionId%7D/secrets/%7BsecretId%7D", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "errors": {
    },
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "traceId": "string",
  • "detail": "string"
}

Update a subscription

Updates your subscription details. You can change the URL or the list of events.

path Parameters
subscriptionId
required
string

The unique identifier for the subscription.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Request Body schema: application/json
required
events
Array of strings or null

The list of events.

url
string or null <uri> ^https://*.+

The URL of the Webhook endpoint.

description
string or null

The subscription description.

Responses

Response Schema: application/json
id
string

The unique identifier for the subscription.

accountId
string or null

The unique identifier for the account.

events
Array of strings

The list of events.

url
string <uri> non-empty ^https://*.+

The URL of the Webhook endpoint.

description
string or null

The subscription description.

Array of objects

The list of secrets associated with the subscription. Used to generate signatures.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

Request samples

Content type
application/json
{
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "ws_aNkU6yob0vOMxUlghg2oynUw",
  • "accountId": "acc_4z3k2xP17e1JQY",
  • "events": [
    ],
  • "url": "https://example.com.com/incoming-events",
  • "description": "Demo Webhooks",
  • "secrets": [
    ],
  • "createdAt": "2023-03-30T12:21:04.143Z",
  • "updatedAt": "2023-03-30T12:21:04.143Z"
}

Delete a subscription

Deletes a subscription.

path Parameters
subscriptionId
required
string

The unique identifier for the subscription.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("DELETE", "/webhooks/%7BsubscriptionId%7D", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "errors": {
    },
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "traceId": "string",
  • "detail": "string"
}

Customers

Allows to create and manage a customer of your business.

Create a customer

Creates a new customer.

header Parameters
version
required
string or null
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Request Body schema: application/json
required
name
string or null <= 100 characters

The customer's name.

(Address (object or null))

The recipient's shipping address.

(Address (object or null))

The recipient's invoicing address.

emailAddress
string or null <= 254 characters

The customer's email address.

phoneNumber
string or null [ 5 .. 50 ] characters

The customer's phone number.

vatNumber
string or null <= 50 characters

The customer's VAT number.

Responses

Response Schema: application/json
id
string or null

The unique identifier of the customer.

name
string or null

The customer's name.

(Address (object or null))

The recipient's shipping address.

(Address (object or null))

The recipient's invoicing address.

emailAddress
string or null

The customer's email address.

phoneNumber
string or null

The customer's phone number.

vatNumber
string or null

The customer's VAT number.

createdAt
string or null <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string or null <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

documentVersion
integer <int32>

The version of the customer's data updated with every change.

Request samples

Content type
application/json
{
  • "name": "Alex",
  • "emailAddress": "alex@dojo.com"
}

Response samples

Content type
application/json
{
  • "id": "cust_sandbox_MJj8Flgfik25x47R4LFbxQ",
  • "name": "Alex",
  • "emailAddress": "alex@dojo.com",
  • "createdAt": "2024-02-15T02:46:21.8232496Z",
  • "updatedAt": "2024-02-15T02:46:21.8232496Z",
  • "documentVersion": 0
}

Delete a customer

Deletes a customer.

path Parameters
customerId
required
string or null <= 100 characters
Example: cust_qNkU6yob0vOMxUlb2oynUw

The unique identifier of the customer.

header Parameters
version
required
string or null
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("DELETE", "/customers/cust_qNkU6yob0vOMxUlb2oynUw", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "extensions": {
    }
}

Update information about a customer

Updates information about a customer.

path Parameters
customerId
required
string or null <= 100 characters
Example: cs_qNkU6yob0vOMxUlb2oynUw

The unique identifier of the customer.

header Parameters
version
required
string or null
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Request Body schema: application/json
required
name
string or null

The customer's name.

(Address (object or null))

The recipient's invoicing address.

(Address (object or null))

The recipient's shipping address.

emailAddress
string or null

The customer's email address.

phoneNumber
string or null

The customer's phone number.

vatNumber
string or null

The customer's VAT number.

Responses

Response Schema: application/json
id
string or null

The unique identifier of the customer.

name
string or null

The customer's name.

(Address (object or null))

The recipient's shipping address.

(Address (object or null))

The recipient's invoicing address.

emailAddress
string or null

The customer's email address.

phoneNumber
string or null

The customer's phone number.

vatNumber
string or null

The customer's VAT number.

createdAt
string or null <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string or null <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

documentVersion
integer <int32>

The version of the customer's data updated with every change.

Request samples

Content type
application/json
{
  • "phoneNumber": "078976534161"
}

Response samples

Content type
application/json
{
  • "id": "cs_qNkU6yob0vOMxUlb2oynUw",
  • "name": "Alex",
  • "emailAddress": "alex@dojo.com",
  • "phoneNumber": "078976534161",
  • "documentVersion": 1,
  • "createdAt": "2023-08-24T14:15:22Z",
  • "updatedAt": "2023-09-24T14:15:22Z"
}

Retrieve a customer

Retrieves the details of a customer.

path Parameters
customerId
required
string or null <= 100 characters

Unique identifiers for the customers you want to get information about, separated by commas.

header Parameters
version
required
string or null
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
Array
id
string or null

The unique identifier of the customer.

name
string or null

The customer's name.

(Address (object or null))

The recipient's shipping address.

(Address (object or null))

The recipient's invoicing address.

emailAddress
string or null

The customer's email address.

phoneNumber
string or null

The customer's phone number.

vatNumber
string or null

The customer's VAT number.

createdAt
string or null <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string or null <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

documentVersion
integer <int32>

The version of the customer's data updated with every change.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/customers/%7BcustomerId%7D", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
[
  • {
    }
]

Create a customer secret

Creates a unique customer secret key valid within a scope of time.

path Parameters
customerId
required
string or null <= 100 characters
Example: cust_qNkU6yob0vOMxUlb2oynUw

The unique identifier of the customer.

header Parameters
version
required
string or null
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
secret
string or null

The unique identifier for the secret.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

expireAt
string <date-time>

The timestamp at which the customer secret expires, in ISO 8601 UTC format.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("POST", "/customers/cust_qNkU6yob0vOMxUlb2oynUw/create-secret", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "secret": "cs_qNkU6yob0vOMxUlb2oynUw",
  • "createdAt": "2022-10-31T10:15:00Z",
  • "expireAt": "2022-10-31T10:30:22Z"
}

Retrieve payment method

Retrieves available payment methods for a customer.

path Parameters
customerId
required
string or null <= 100 characters
Example: cust_qNkU6yob0vOMxUlb2oynUw

The unique identifier of the customer.

header Parameters
version
required
string or null
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

authorization
required
string or null <= 500 characters
Example: Authorization: Basic cs_generated-customer-secret

Basic HTTP authentication to grant access to customer-owned resources.

Responses

Response Schema: application/json
customerId
string or null

The unique identifier of the customer.

merchantId
string or null

A unique identifier for the merchant. A single merchant can be associated with multiple terminals, point-of-sale machines, and waiters.

Array of objects or null

List of the customer saved payment methods.

(SupportedPaymentMethods (object or null))

Supported payment methods.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = {
    'authorization': "SOME_STRING_VALUE",
    'Authorization': "REPLACE_KEY_VALUE"
    }

conn.request("GET", "/customers/public/cust_qNkU6yob0vOMxUlb2oynUw/payment-methods", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "customerId": "cust_qNkU6yob0vOMxUlb2oy123",
  • "merchantId": "123456789",
  • "savedPaymentMethods": [
    ],
  • "supportedPaymentMethods": {
    }
}

Remove payment method

Delete a customer payment method.

path Parameters
customerId
required
string or null <= 100 characters
Example: cust_qNkU6yob0vOMxUlb2oynUw

The unique identifier of the customer.

paymentMethodId
required
string or null <= 100 characters
Example: pm_otRL98WURbaAKs0sdy7_5w

The unique identifier of the customer payment method.

header Parameters
version
required
string or null
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

authorization
required
string or null <= 500 characters
Example: Authorization: Basic cs_generated-customer-secret

Basic HTTP authentication to grant access to customer-owned resources.

Responses

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = {
    'authorization': "SOME_STRING_VALUE",
    'Authorization': "REPLACE_KEY_VALUE"
    }

conn.request("DELETE", "/customers/public/cust_qNkU6yob0vOMxUlb2oynUw/payment-methods/pm_otRL98WURbaAKs0sdy7_5w", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "extensions": {
    }
}

Setup intents

Allows you to setup a card for future payments.

Documentation: Setup intent

Create a setup intent

Creates a setup intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Request Body schema: application/json
required
reference
required
string [ 1 .. 60 ] characters

A unique identifier for the payment. For example, Order 236.

description
string or null <= 4096 characters

The payment description.

(Customer (object or null))

Details about the customer.

captureMode
string
Default: "Auto"
Enum: "Auto" "Manual"

The type of capture for the payment, where:

  • Auto payments are captured automatically, once authorization is complete.
  • Manual payments are captured only when a capture request is made.
paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

(PaymentIntentConfigRequest (object or null))

Details about the payment intent configuration.

object or null

A set of key-value pairs that you can use to store additional information.

(Money (object or null))

The amount intended to be collected by this setup intent.

merchantInitiatedTransactionType
required
string
Enum: "NoShow" "Unscheduled"

Details about the merchant-initiated transaction type.

terms
required
string [ 1 .. 10240 ] characters

The terms that customers are required to review before adding a card to the setup intent.

(OrderDetails (object or null))

Details about the order including the type and the details.

expireAt
string or null <date-time>

The timestamp and date of when a setup intent will be voided, in ISO 8601 format. This occurs when a setup intent is created and not yet authorized.

Responses

Response Schema: application/json
id
string or null

The unique identifier for the setup intent.

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string or null <date-time>

The expiration date of clientSessionSecret.

status
string
Enum: "Created" "Authorized" "Canceled" "Completed" "Expired" "CardExpired" "Closed"

Current status of the setup intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

expireAt
string or null <date-time>

The timestamp and date of when a setup intent will be voided, in ISO 8601 format. This occurs when a setup intent is created and not yet authorized.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

object or null

A set of key-value pairs that you can use to store additional information.

(PaymentDetails (object or null))
(Money (object or null))

The amount intended to be collected by this setup intent.

merchantInitiatedTransactionType
string
Enum: "NoShow" "Unscheduled"

Details about the merchant-initiated transaction type.

terms
string or null

The terms that customers are required to review before adding a card to the setup intent.

paymentSource
string or null

Information about a single payment source type. Invalid if used along with paymentSources parameter.

Array of objects or null

Updates related to the setup intent's status.

Request samples

Content type
application/json
{
  • "reference": "Dojo Cafe | Booking request for Table 4",
  • "merchantInitiatedTransactionType": "NoShow",
  • "terms": "In case of no-show, the customer authorizes us to charge their card with table booking fee.",
  • "intendedAmount": {
    }
}

Response samples

Content type
application/json
{}

Retrieve a setup intent

Get a setup intent by ID.

path Parameters
setupIntentId
required
string or null

The unique identifier for the setup intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
id
string or null

The unique identifier for the setup intent.

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string or null <date-time>

The expiration date of clientSessionSecret.

status
string
Enum: "Created" "Authorized" "Canceled" "Completed" "Expired" "CardExpired" "Closed"

Current status of the setup intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

expireAt
string or null <date-time>

The timestamp and date of when a setup intent will be voided, in ISO 8601 format. This occurs when a setup intent is created and not yet authorized.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

object or null

A set of key-value pairs that you can use to store additional information.

(PaymentDetails (object or null))
(Money (object or null))

The amount intended to be collected by this setup intent.

merchantInitiatedTransactionType
string
Enum: "NoShow" "Unscheduled"

Details about the merchant-initiated transaction type.

terms
string or null

The terms that customers are required to review before adding a card to the setup intent.

paymentSource
string or null

Information about a single payment source type. Invalid if used along with paymentSources parameter.

Array of objects or null

Updates related to the setup intent's status.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/setup-intents/%7BsetupIntentId%7D", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientSessionSecret": "string",
  • "clientSessionSecretExpirationDate": "2019-08-24T14:15:22Z",
  • "status": "Created",
  • "paymentMethods": [
    ],
  • "customer": {
    },
  • "requestSecurity": {
    },
  • "billingAddress": {
    },
  • "shippingDetails": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expireAt": "2019-08-24T14:15:22Z",
  • "reference": "string",
  • "description": "string",
  • "merchantConfig": {
    },
  • "config": {
    },
  • "metadata": {
    },
  • "paymentDetails": {
    },
  • "intendedAmount": {
    },
  • "merchantInitiatedTransactionType": "NoShow",
  • "terms": "string",
  • "paymentSource": "string",
  • "setupEvents": [
    ]
}

Cancel a setup intent

Cancels a setup intent.

path Parameters
setupIntentId
required
string or null <= 50 characters

The unique identifier for the setup intent.

header Parameters
version
required
string <date>

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
id
string or null

The unique identifier for the setup intent.

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string or null <date-time>

The expiration date of clientSessionSecret.

status
string
Enum: "Created" "Authorized" "Canceled" "Completed" "Expired" "CardExpired" "Closed"

Current status of the setup intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

expireAt
string or null <date-time>

The timestamp and date of when a setup intent will be voided, in ISO 8601 format. This occurs when a setup intent is created and not yet authorized.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

object or null

A set of key-value pairs that you can use to store additional information.

(PaymentDetails (object or null))
(Money (object or null))

The amount intended to be collected by this setup intent.

merchantInitiatedTransactionType
string
Enum: "NoShow" "Unscheduled"

Details about the merchant-initiated transaction type.

terms
string or null

The terms that customers are required to review before adding a card to the setup intent.

paymentSource
string or null

Information about a single payment source type. Invalid if used along with paymentSources parameter.

Array of objects or null

Updates related to the setup intent's status.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = {
    'version': "SOME_STRING_VALUE",
    'Authorization': "REPLACE_KEY_VALUE"
    }

conn.request("DELETE", "/setup-intents/%7BsetupIntentId%7D", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientSessionSecret": "string",
  • "clientSessionSecretExpirationDate": "2019-08-24T14:15:22Z",
  • "status": "Created",
  • "paymentMethods": [
    ],
  • "customer": {
    },
  • "requestSecurity": {
    },
  • "billingAddress": {
    },
  • "shippingDetails": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expireAt": "2019-08-24T14:15:22Z",
  • "reference": "string",
  • "description": "string",
  • "merchantConfig": {
    },
  • "config": {
    },
  • "metadata": {
    },
  • "paymentDetails": {
    },
  • "intendedAmount": {
    },
  • "merchantInitiatedTransactionType": "NoShow",
  • "terms": "string",
  • "paymentSource": "string",
  • "setupEvents": [
    ]
}

Retrieve a setup intent (no auth)

Get a setup intent by ID.

path Parameters
setupIntentId
required
string or null

The unique identifier for the setup intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
id
string or null

The unique identifier for the setup intent.

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string or null <date-time>

The expiration date of clientSessionSecret.

status
string
Enum: "Created" "Authorized" "Canceled" "Completed" "Expired" "CardExpired" "Closed"

Current status of the setup intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

expireAt
string or null <date-time>

The timestamp and date of when a setup intent will be voided, in ISO 8601 format. This occurs when a setup intent is created and not yet authorized.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

object or null

A set of key-value pairs that you can use to store additional information.

(PaymentDetails (object or null))
(Money (object or null))

The amount intended to be collected by this setup intent.

merchantInitiatedTransactionType
string
Enum: "NoShow" "Unscheduled"

Details about the merchant-initiated transaction type.

terms
string or null

The terms that customers are required to review before adding a card to the setup intent.

paymentSource
string or null

Information about a single payment source type. Invalid if used along with paymentSources parameter.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/setup-intents/public/%7BsetupIntentId%7D", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientSessionSecret": "string",
  • "clientSessionSecretExpirationDate": "2019-08-24T14:15:22Z",
  • "status": "Created",
  • "paymentMethods": [
    ],
  • "customer": {
    },
  • "requestSecurity": {
    },
  • "billingAddress": {
    },
  • "shippingDetails": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expireAt": "2019-08-24T14:15:22Z",
  • "reference": "string",
  • "description": "string",
  • "merchantConfig": {
    },
  • "config": {
    },
  • "metadata": {
    },
  • "paymentDetails": {
    },
  • "intendedAmount": {
    },
  • "merchantInitiatedTransactionType": "NoShow",
  • "terms": "string",
  • "paymentSource": "string"
}

Update a client session secret

Updates a client session secret.

path Parameters
setupIntentId
required
string or null

The unique identifier for the setup intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
id
string or null

The unique identifier for the setup intent.

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string or null <date-time>

The expiration date of clientSessionSecret.

status
string
Enum: "Created" "Authorized" "Canceled" "Completed" "Expired" "CardExpired" "Closed"

Current status of the setup intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

expireAt
string or null <date-time>

The timestamp and date of when a setup intent will be voided, in ISO 8601 format. This occurs when a setup intent is created and not yet authorized.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

object or null

A set of key-value pairs that you can use to store additional information.

(PaymentDetails (object or null))
(Money (object or null))

The amount intended to be collected by this setup intent.

merchantInitiatedTransactionType
string
Enum: "NoShow" "Unscheduled"

Details about the merchant-initiated transaction type.

terms
string or null

The terms that customers are required to review before adding a card to the setup intent.

paymentSource
string or null

Information about a single payment source type. Invalid if used along with paymentSources parameter.

Array of objects or null

Updates related to the setup intent's status.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("POST", "/setup-intents/%7BsetupIntentId%7D/refresh-client-session-secret", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientSessionSecret": "string",
  • "clientSessionSecretExpirationDate": "2019-08-24T14:15:22Z",
  • "status": "Created",
  • "paymentMethods": [
    ],
  • "customer": {
    },
  • "requestSecurity": {
    },
  • "billingAddress": {
    },
  • "shippingDetails": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expireAt": "2019-08-24T14:15:22Z",
  • "reference": "string",
  • "description": "string",
  • "merchantConfig": {
    },
  • "config": {
    },
  • "metadata": {
    },
  • "paymentDetails": {
    },
  • "intendedAmount": {
    },
  • "merchantInitiatedTransactionType": "NoShow",
  • "terms": "string",
  • "paymentSource": "string",
  • "setupEvents": [
    ]
}

Update a client session secret (no auth)

Updates a client session secret.

path Parameters
setupIntentId
required
string or null

The unique identifier for the setup intent.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

Responses

Response Schema: application/json
id
string or null

The unique identifier for the setup intent.

clientSessionSecret
string or null

The client secret.

clientSessionSecretExpirationDate
string or null <date-time>

The expiration date of clientSessionSecret.

status
string
Enum: "Created" "Authorized" "Canceled" "Completed" "Expired" "CardExpired" "Closed"

Current status of the setup intent.

paymentMethods
Array of strings or null
Enum: "Card" "Wallet" "SavedCard"

The payment methods that customers can use to pay.

(Customer (object or null))

Details about the customer.

(RequestSecurity (object or null))

Customer's device information.

(Address (object or null))

The recipient's invoicing address.

(ShippingDetails (object or null))

The recipient's shipping address.

createdAt
string <date-time>

The creation date, in ISO 8601 UTC format.

updatedAt
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

expireAt
string or null <date-time>

The timestamp and date of when a setup intent will be voided, in ISO 8601 format. This occurs when a setup intent is created and not yet authorized.

reference
string or null

A unique identifier for the payment. For example, Order 236.

description
string or null

The payment description.

(MerchantConfig (object or null))

Details about payment intent merchant configuration.

(PaymentIntentConfigResponse (object or null))

Details about the payment intent configuration.

object or null

A set of key-value pairs that you can use to store additional information.

(PaymentDetails (object or null))
(Money (object or null))

The amount intended to be collected by this setup intent.

merchantInitiatedTransactionType
string
Enum: "NoShow" "Unscheduled"

Details about the merchant-initiated transaction type.

terms
string or null

The terms that customers are required to review before adding a card to the setup intent.

paymentSource
string or null

Information about a single payment source type. Invalid if used along with paymentSources parameter.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("POST", "/setup-intents/public/%7BsetupIntentId%7D/refresh-client-session-secret", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "id": "string",
  • "clientSessionSecret": "string",
  • "clientSessionSecretExpirationDate": "2019-08-24T14:15:22Z",
  • "status": "Created",
  • "paymentMethods": [
    ],
  • "customer": {
    },
  • "requestSecurity": {
    },
  • "billingAddress": {
    },
  • "shippingDetails": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expireAt": "2019-08-24T14:15:22Z",
  • "reference": "string",
  • "description": "string",
  • "merchantConfig": {
    },
  • "config": {
    },
  • "metadata": {
    },
  • "paymentDetails": {
    },
  • "intendedAmount": {
    },
  • "merchantInitiatedTransactionType": "NoShow",
  • "terms": "string",
  • "paymentSource": "string"
}

Terminals

Allows you to manage payments on the terminal. Documentation: Terminals

Retrieve all terminals

Allows you to retrieve details of all terminals.

query Parameters
statuses
Array of strings
Items Enum: "Available" "Offline" "InUse"

A machine-readable value describing the state of the terminal. Terminals with any of the statuses provided in this parameter will be listed.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

software-house-id
required
string
Example: softwareHouse1

This field shows the EPOS company whose software is generating the request. This value should not be configurable as it will remain the same for all customers using particular EPOS software.

reseller-id
string
Example: reseller1

This identifies the reseller of the EPOS. This may be the same as the software-house-id if they are also the seller.

Responses

Response Schema: application/json
Array
id
required
string

The unique identifier for the terminal.

required
object

Properties related to the terminal.

status
required
string
Enum: "Available" "Offline" "InUse"

A machine-readable value describing the state of the terminal.

updatedAt
required
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/terminals?statuses=SOME_ARRAY_VALUE", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Retrieve a terminal

Retrieve a terminal by using its ID.

path Parameters
terminalId
required
string
Example: tm_sandbox_65c5fe8a104a12xxxxxxxxxx

The unique identifier for the terminal.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

software-house-id
required
string
Example: softwareHouse1

This field shows the EPOS company whose software is generating the request. This value should not be configurable as it will remain the same for all customers using particular EPOS software.

reseller-id
string
Example: reseller1

This identifies the reseller of the EPOS. This may be the same as the software-house-id if they are also the seller.

Responses

Response Schema: application/json
id
required
string

The unique identifier for the terminal.

required
object

Properties related to the terminal.

status
required
string
Enum: "Available" "Offline" "InUse"

A machine-readable value describing the state of the terminal.

updatedAt
required
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/terminals/tm_sandbox_65c5fe8a104a12xxxxxxxxxx", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "id": "tm_sandbox_65c5fe8a104a1222b2d8b968",
  • "properties": {
    },
  • "status": "Available",
  • "updatedAt": "2024-02-09T10:29:30.213Z"
}

Terminal sessions

Allows you to manage sessions on the terminal.

Create a session on a terminal

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

software-house-id
required
string
Example: softwareHouse1

This field shows the EPOS company whose software is generating the request. This value should not be configurable as it will remain the same for all customers using particular EPOS software.

reseller-id
string
Example: reseller1

This identifies the reseller of the EPOS. This may be the same as the software-house-id if they are also the seller.

Request Body schema: application/json
required
terminalId
required
string

The unique identifier for the terminal.

required
Sale (object) or Unlinked Refund (object) or Matched Refund (object)

Details about the terminal session, including which type of transaction it is associated with.

Responses

Response Schema: application/json
terminalId
required
string

The unique identifier for the terminal.

createdAt
required
string <date-time>

This is when the terminal session was created, in ISO 8601 UTC format.

updatedAt
required
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

id
required
string

The unique identifier of the terminal session.

required
TerminalSessionStatus (string)

The current status of the terminal session. A finalized, successful session will be Captured.

expireAt
required
string <date-time>

The timestamp and date of when a terminal session will be marked as Expired, in ISO 8601 UTC format. This changes throughout the life cycle of a terminal session as it moves to different states.

required
Array of objects

When a notification is issued, a notification event is created to record when it occurred.

required
Array of objects

Status events include the capture, cancellation, and refund of payments.

object

The receipt object is a record of the transactions associated with a terminal session.

Sale (object) or Unlinked Refund (object) or Matched Refund (object)

Details about the terminal session, including which type of transaction it is associated with.

(PaymentDetails (object or null))

These details about the payment will only populate once the status of the transaction is finalized.

Request samples

Content type
application/json
Example
{
  • "terminalId": "tm_sandbox_65c5fe8a104a1222b2d8b968",
  • "details": {
    }
}

Response samples

Content type
application/json
{
  • "createdAt": "2024-02-15T00:48:10.756Z",
  • "details": {
    },
  • "expireAt": "2024-02-15T00:48:20.756Z",
  • "id": "ts_sandbox_65cd5f4a57ba13ad7424acd0",
  • "notificationEvents": [ ],
  • "status": "InitiateRequested",
  • "statusEvents": [
    ],
  • "terminalId": "tm_sandbox_65c5fe8a104a1222b2d8b968",
  • "updatedAt": "2024-02-15T00:48:10.756Z"
}

Retrieve a terminal session

path Parameters
terminalSessionId
required
string

The unique identifier of the terminal session.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

software-house-id
required
string
Example: softwareHouse1

This field shows the EPOS company whose software is generating the request. This value should not be configurable as it will remain the same for all customers using particular EPOS software.

reseller-id
string
Example: reseller1

This identifies the reseller of the EPOS. This may be the same as the software-house-id if they are also the seller.

Responses

Response Schema: application/json
terminalId
required
string

The unique identifier for the terminal.

createdAt
required
string <date-time>

This is when the terminal session was created, in ISO 8601 UTC format.

updatedAt
required
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

id
required
string

The unique identifier of the terminal session.

required
TerminalSessionStatus (string)

The current status of the terminal session. A finalized, successful session will be Captured.

expireAt
required
string <date-time>

The timestamp and date of when a terminal session will be marked as Expired, in ISO 8601 UTC format. This changes throughout the life cycle of a terminal session as it moves to different states.

required
Array of objects

When a notification is issued, a notification event is created to record when it occurred.

required
Array of objects

Status events include the capture, cancellation, and refund of payments.

object

The receipt object is a record of the transactions associated with a terminal session.

Sale (object) or Unlinked Refund (object) or Matched Refund (object)

Details about the terminal session, including which type of transaction it is associated with.

(PaymentDetails (object or null))

These details about the payment will only populate once the status of the transaction is finalized.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/terminal-sessions/%7BterminalSessionId%7D", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "createdAt": "2024-02-15T00:48:10.756Z",
  • "customerReceipt": {
    },
  • "details": {
    },
  • "expireAt": "2024-02-15T00:49:40.756Z",
  • "id": "ts_sandbox_65cd5f4a57ba13ad7424acd0",
  • "merchantReceipt": {
    },
  • "notificationEvents": [
    ],
  • "status": "Captured",
  • "statusEvents": [
    ],
  • "terminalId": "tm_sandbox_65c5fe8a104a1222b2d8b968",
  • "updatedAt": "2024-02-15T00:48:19.448Z"
}

Request the cancellation of a terminal session

path Parameters
terminalSessionId
required
string

The unique identifier of the terminal session.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

software-house-id
required
string
Example: softwareHouse1

This field shows the EPOS company whose software is generating the request. This value should not be configurable as it will remain the same for all customers using particular EPOS software.

reseller-id
string
Example: reseller1

This identifies the reseller of the EPOS. This may be the same as the software-house-id if they are also the seller.

Responses

Response Schema: application/json
terminalId
required
string

The unique identifier for the terminal.

createdAt
required
string <date-time>

This is when the terminal session was created, in ISO 8601 UTC format.

updatedAt
required
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

id
required
string

The unique identifier of the terminal session.

required
TerminalSessionStatus (string)

The current status of the terminal session. A finalized, successful session will be Captured.

expireAt
required
string <date-time>

The timestamp and date of when a terminal session will be marked as Expired, in ISO 8601 UTC format. This changes throughout the life cycle of a terminal session as it moves to different states.

required
Array of objects

When a notification is issued, a notification event is created to record when it occurred.

required
Array of objects

Status events include the capture, cancellation, and refund of payments.

object

The receipt object is a record of the transactions associated with a terminal session.

Sale (object) or Unlinked Refund (object) or Matched Refund (object)

Details about the terminal session, including which type of transaction it is associated with.

(PaymentDetails (object or null))

These details about the payment will only populate once the status of the transaction is finalized.

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("PUT", "/terminal-sessions/%7BterminalSessionId%7D/cancel", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "terminalId": "tm_sandbox_amxm22C23",
  • "createdAt": "2024-02-12T14:15:22Z",
  • "updatedAt": "2024-02-12T14:16:22Z",
  • "id": "ts_sandbox_RBMHTJ4fIkmSppDILZVCGw",
  • "status": "CancelRequested",
  • "expireAt": "2024-02-12T14:15:22Z",
  • "notificationEvents": [
    ],
  • "statusEvents": [
    ],
  • "details": {
    }
}

Respond to a signature verification request

path Parameters
terminalSessionId
required
string

The unique identifier of the terminal session.

header Parameters
version
required
string <date>
Example: 2024-02-05

The API version with format yyyy-mm-dd. The current version is 2024-02-05.

software-house-id
required
string
Example: softwareHouse1

This field shows the EPOS company whose software is generating the request. This value should not be configurable as it will remain the same for all customers using particular EPOS software.

reseller-id
string
Example: reseller1

This identifies the reseller of the EPOS. This may be the same as the software-house-id if they are also the seller.

Request Body schema: application/json
required
accepted
required
boolean

True/false. Failed signature verification requests will be false.

Responses

Response Schema: application/json
terminalId
required
string

The unique identifier for the terminal.

createdAt
required
string <date-time>

This is when the terminal session was created, in ISO 8601 UTC format.

updatedAt
required
string <date-time>

The timestamp of the update date, in ISO 8601 UTC format.

id
required
string

The unique identifier of the terminal session.

required
TerminalSessionStatus (string)

The current status of the terminal session. A finalized, successful session will be Captured.

expireAt
required
string <date-time>

The timestamp and date of when a terminal session will be marked as Expired, in ISO 8601 UTC format. This changes throughout the life cycle of a terminal session as it moves to different states.

required
Array of objects

When a notification is issued, a notification event is created to record when it occurred.

required
Array of objects

Status events include the capture, cancellation, and refund of payments.

object

The receipt object is a record of the transactions associated with a terminal session.

Sale (object) or Unlinked Refund (object) or Matched Refund (object)

Details about the terminal session, including which type of transaction it is associated with.

(PaymentDetails (object or null))

These details about the payment will only populate once the status of the transaction is finalized.

Request samples

Content type
application/json
{
  • "accepted": true
}

Response samples

Content type
application/json
{
  • "createdAt": "2024-02-15T00:48:10.756Z",
  • "customerReceipt": {
    },
  • "details": {
    },
  • "expireAt": "2024-02-15T00:49:40.756Z",
  • "id": "ts_sandbox_65cd5f4a57ba13ad7424acd0",
  • "merchantReceipt": {
    },
  • "notificationEvents": [
    ],
  • "status": "SignatureVerificationAccepted",
  • "statusEvents": [
    ],
  • "terminalId": "tm_sandbox_65c5fe8a104a1222b2d8b968",
  • "updatedAt": "2024-02-15T01:47:28.85Z"
}

Capabilities

Register your REST and WebSockets endpoints.

Get all registered integrations

Responses

Response Schema: application/json
required
Array of objects

All the WS integrations currently registered and active for this account.

required
Array of objects

All the WS integrations currently registered and active for this account.

Array of objects

All the integrations managed by Dojo

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/epos/integrations", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
{
  • "wsIntegrations": [
    ],
  • "restIntegrations": [
    ]
}

Get registered REST integrations

Responses

Response Schema: application/json
Array
url
required
string
required
Array of objects

Receive a response to a REST request

required
object

The authentication details for REST adapters.

createdAt
required
string <date-time>

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/epos/integrations/rest", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
[
  • {
    }
]

Register a new REST integration

Request Body schema: application/json
required
url
required
string
required
Array of objects

Send a REST request

required
object

The authentication details for REST adapters

Responses

Response Schema: application/json
Array
url
required
string
required
Array of objects

Receive a response to a REST request

required
object

The authentication details for REST adapters.

createdAt
required
string <date-time>

Request samples

Content type
application/json
{
  • "capabilities": [
    ],
  • "url": "https://my-epos.com/orders",
  • "auth": {
    }
}

Response samples

Content type
application/json
[
  • {
    }
]

Get registered WebSocket integrations

Responses

Response Schema: application/json
Array
required
Array of objects

Receive a response to a WS request

createdAt
required
string <date-time>

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/epos/integrations/ws", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
[
  • {
    }
]

Register a new WebSocket integration

Request Body schema: application/json
required

Register a new WebSocket integration

required
Array of objects

Send a WS request

Array
name
required
string
Enum: "CancelOrderById" "CreateOrder" "ListAreas" "GetOrderById" "SearchTables" "HandleEvent:payment_intent.created" "HandleEvent:payment_intent.status_updated" "SearchOrders" "GetPartyById" "DeletePartyById" "SearchParties" "UpdatePartyById" "CreateParty" "GetReservationById" "SearchReservations" "UpdateReservationById" "DeleteReservationById" "CreateReservation"

The name of a capability.

version
required
string

Responses

Response Schema: application/json
Array
required
Array of objects

Receive a response to a WS request

createdAt
required
string <date-time>

Request samples

Content type
application/json
{
  • "capabilities": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

/epos/integrations/dojo

Responses

Response Schema: application/json
Array
required
Array of objects
createdAt
required
string <date-time>

Request samples 

import http.client

conn = http.client.HTTPSConnection("api.dojo.tech")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/epos/integrations/dojo", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response samples

Content type
application/json
[
  • {
    }
]

Events

Submit an event

Request Body schema: application/json
required
eventType
required
string
Enum: "OrderUpdated" "PartyUpdated" "ReservationUpdated"
required
OrderEvent (object) or PartyEvent (object) or ReservationEvent (object)

Responses

Response Schema: application/json
eventType
required
string
Enum: "OrderUpdated" "PartyUpdated" "ReservationUpdated"
required
OrderEvent (object) or PartyEvent (object) or ReservationEvent (object)

Request samples

Content type
application/json
{
  • "eventType": "OrderUpdated",
  • "event": {
    }
}

Response samples

Content type
application/json
{
  • "eventType": "OrderUpdated",
  • "event": {
    }
}