Skip to main content

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 user gets 80 seconds to respond from the point of SignatureVerificationRequired notification before the transaction is finalized. After this the payment intent status is updated and the POS can continue the normal flow.

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​

omni-payments/terminals/curl/respond-signature.sh
loading...

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.

Last updated on