Create session

Create a new session on an available terminal.

You can create a terminal session on any Available terminal. If, as part of your integration, you need to develop logic for finding out which terminals are available, use one of the GET /terminals endpoint. A payment intent is automatically initiated on the terminal when you create a terminal session.

Path

POST /terminal-sessions

Session types

There are three Terminal session types:

• a sale, which is associated with a payment intent and therefore requires a paymentIntentId.
• a matchedRefund, which also requires a paymentIntentId.
• an unlinkedRefund, which is a refund that has not yet been associated with a payment intent.

For an unlinkedRefund, you will have to specify the amount (the value in minor units, and the currencyCode) when you post the request to create a terminal session. For a matchedRefund, you will have to specify the paymentIntentId as well.

Matched refund

A matched refund requires the card and the customer to be physically present on the premises. The request references a payment intent and uses a terminal to process a negative transaction, which is the movement of funds to the card from the merchant account.

Unlinked refund

An unlinked refund also requires the card and the customer to be physically present, but it contains no reference to a payment intent. An unlinked refund theoretically allows for any amount of money to be refunded to anyone. This is ideal for EPOS systems which do not store previous transaction data, where refunds are processed without reference to the original sale's paymentIntentId.

tip

Use Authorization: Basic <api_key> on these requests. Basic is a literal prefix in Dojo's auth scheme, so do not base64-encode api_key:.

Sandbox and production both use https://api.dojo.tech; the API key determines the environment. In sandbox, use your assigned software-house-id and reseller-id if you have them; otherwise use the literal values softwareHouse1 and reseller1. Production integrations always use values assigned by Dojo.

Sample requests

cURL

# The sandbox API key passed in 'authorization' is public.
# Don't submit any personally identifiable information in any requests made with this key.
# Sign in to developer.dojo.tech to create your own private sandbox key and use that instead
# for secure testing.

curl --location --request POST 'https://api.dojo.tech/terminal-sessions' \
    --header 'version: 2024-02-05' \
    --header 'software-house-id: softwareHouse1' \
    --header 'reseller-id: reseller1' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Basic sk_sandbox_1WYDtq7yAdqhmQ7KEUAvPlCCRBYc9HTY9KOPJKZtfWkzsSISj1L8c4GG5l4pBB5Bj85hkJgTL9vmOmki5QnQfQ' \
    --data-raw '{
        "terminalId": "tm_65a7e8c0bee9b6390862337c",
        "details": {
            "sale": {
                "paymentIntentId": "pi_sandbox_81Q7HAZSGkWLKFx_DFEe9Q"
        },
            "sessionType": "Sale"
        }
    }'

Python

import http.client
import json

conn = http.client.HTTPSConnection("api.dojo.tech")
payload = json.dumps({
    "terminalId": "tm_65a7e8c0bee9b6390862337c",
    "details": {
        "sale": {
            "paymentIntentId": "pi_sandbox_bwCK9L2q8kOq7QV1N5aPyQ"
        },
        "sessionType": "Sale"
    }
})
headers = {
    'Content-Type': "application/json",
    'version': '2024-02-05',
    'software-house-id': 'softwareHouse1',
    'reseller-id': 'reseller1',
    'Accept': 'application/json',
    'Authorization': 'Basic sk_sandbox_1WYDtq7yAdqhmQ7KEUAvPlCCRBYc9HTY9KOPJKZtfWkzsSISj1L8c4GG5l4pBB5Bj85hkJgTL9vmOmki5QnQfQ'
}
conn.request("POST", "/terminal-sessions", payload, headers)
res = conn.getresponse()
data = res.read()
json_data = json.loads(data.decode("utf-8"))
pretty_json = json.dumps(json_data, indent=2)
print(pretty_json)

conn.close()

PowerShell

# The sandbox API key passed in '$publicSandboxKey' is public.
# Don't submit any personally identifiable information in any requests made with this key.
# Sign in to developer.dojo.tech to create your own private sandbox key and use that instead
# for secure testing.

$publicSandboxKey = "sk_sandbox_1WYDtq7yAdqhmQ7KEUAvPlCCRBYc9HTY9KOPJKZtfWkzsSISj1L8c4GG5l4pBB5Bj85hkJgTL9vmOmki5QnQfQ"

Invoke-WebRequest `
    -Uri 'https://api.dojo.tech/terminal-sessions' `
    -Method POST `
    -Headers @{
        "Version" = "2024-02-05"
        "Authorization" = "Basic $publicSandboxKey"
        "software-house-id" = "softwareHouse1"
        "reseller-id" = "reseller1"
    } `
    -ContentType 'application/json' `
    -Body '{
        "terminalId": "tm_65a7e8c0bee9b6390862337c",
        "details": {
            "sale": {
                "paymentIntentId": "pi_sandbox_bwCK9L2q8kOq7QV1N5aPyQ"
            },
            "sessionType": "Sale"
        }
    }'

API reference Learn about the API and integrate with API endpoints.

Introduction Return to the introduction page.

Step-by-step guide See the new terminals endpoints in practice.

Support Our support team is always happy to help with any questions you have.