Signature verification

Respond to signature verification requests and accept or decline payment.

Although only a small number of transactions will require signature verification, to be able to correctly support signature verification an endpoint including logic to handle these requests has been included as part of the Dojo API.

tip

You'll only need to complete this step when the terminal session status changes to SignatureVerificationRequired.

Step 1. Create a payment intent

First, make sure you've already created a payment intent. Visit the payment intents documentation for more information about configuration options. This is where important information like payment details, amount, and currency are stored.

Step 2: Check which terminals are available

GET /terminals

Main page: Retrieve all terminals

You can check which terminals are available by requesting a list of all terminals, or by requesting a filtered list of Available terminals.

Step 3: Create a terminal session

POST /terminal-sessions

Main page: Create session

Over the course of a single business day, a terminal might be associated with hundreds of sessions.

In your request, determine the terminal sessionType. Make sure you've already created your payment intent before creating a terminal session. You will have to specify the paymentIntentId in the request for Sale and MatchedRefund sessions. Dojo will initiate the payment intent automatically once you've linked them.

A session will end once the payment is complete, or once the refund has been fully processed.

Step 4: Respond to a signature verification request

PUT /terminal-sessions/{terminalSessionId}/signature

Main page: Signature verification

tip

The operator has 80 seconds to respond after the terminal session enters SignatureVerificationRequired.

If no signature decision is submitted within that window, Dojo finalizes the signature step as accepted and the payment continues through its normal successful flow. For example, an auto-capture sale proceeds to Captured, while a manual-capture sale proceeds to Authorized until you capture it later.

Respond to a signature verification request with true (to accept it) or false (to decline it). If you accept signature verification and send a request with the accepted field set to true, you will receive a detailed response object including both a customerReceipt and a merchantReceipt.

Step 5: Retrieve the original payment intent

Now that the customer has completed the payment on the terminal and the terminal has reached a final state, retrieve the original payment intent to ensure that the payment is complete.

GET /payment-intents/{paymentIntentId}

---

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

Introduction Return to the introduction page.

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

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 PUT 'https://api.dojo.tech/terminal-sessions/ts_sandbox_65aa64bf637e6374ac244115/signature' \
    --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 '{
        "accepted": true
}'

Python

import http.client
import json

conn = http.client.HTTPSConnection("api.dojo.tech")
payload = json.dumps({
    "accepted": True
})
headers = {
    'version': '2024-02-05',
    'software-house-id': 'softwareHouse1',
    'reseller-id': 'reseller1',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Basic sk_sandbox_1WYDtq7yAdqhmQ7KEUAvPlCCRBYc9HTY9KOPJKZtfWkzsSISj1L8c4GG5l4pBB5Bj85hkJgTL9vmOmki5QnQfQ'
}
conn.request("PUT", "/terminal-sessions/ts_sandbox_65aa64bf637e6374ac244115/signature", 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/ts_sandbox_65aa64bf637e6374ac244115/signature'`
    -Method PUT `
    -Headers @{
        "Version" = "2024-02-05"
        "Authorization" = "Basic $publicSandboxKey"
        "software-house-id" = "softwareHouse1"
        "reseller-id" = "reseller1"
    }`
    -ContentType 'application/json' `
    -Body '{
        "accepted": true
    }'

Test your integration

You can use your Dojo payment device to test your signature verification integration:

1. Start a new transaction on your EPOS.
2. Insert your test card into the payment device, wrong way round (not chip first).
3. Wait until the terminal tells you to remove card, then swipe it, too.
4. If successful, the signature verification process will commence.

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.