Go-live checklist
To ensure you have a smooth onboarding with face-to-face payments on your EPOS, Dojo has prepared a comprehensive testing checklist that you can follow before going live with your integration.
Please note that we mandate that at least one method of refunding is achievable through your integration to our API. This can be achieved directly through the Payment Intent to refund to the original card used for payment, or by creating a terminal session either matched to a Payment Intent, or unmatched.
Configuration
These tests relate to how your EPOS is setup to interact with the Dojo API, taking into account authorization flow, user experience, and versioning.
| Scenario | Steps to Reproduce | Expected Outcome |
|---|---|---|
| Authorization | See where these details are configured. This might not need to be in the UI of the EPOS software itself, but it could be in a configuration file, a database elsewhere, or even in a back-office system that end-users log in to. Also, record who is expected to enter the Cloud credentials: yourself, an installer, or the merchant. | POS allows configuring different API Keys. The API Key should never be hard-coded. |
| Incorrect authorization credentials | Input an invalid API Key. | The EPOS should display an error prompting the user to check authentication credentials. |
| Retrieve terminal(s) | EPOS must be able to check for available terminals, preferably using the GET /terminals endpoint, or at a bare minimum offer the ability to manually enter the required TID. | POS should be able to check for available terminals or enable you to configure preferred TID. This should never be hard-coded. |
| API version | Note which version of the API you are testing | This data is to be provided during QA. |
| POS version | For our records, we prefer to keep a note of the minimum version of your POS which is compatible with this API - this allows us to track historic versions which may be incompatible. If this isn't providable (such as in the instance where only one version of the POS exists) then this step can be omitted. | Data to be provided during QA completion. |
Payment intents
These tests concern the creation of and management of payment intents, as well as additional features like itemLines and Webhooks.
| Scenario | Steps to Reproduce | Expected Outcome |
|---|---|---|
| [Create] Payment intent (Auto) | Initiate a sale using capture mode AUTO | Payment intent created successfully with the capture mode set to AUTO |
| [Create] Payment intent (Manual) [Optional] | Initiate a sale using captureMode: Manual | Payment intent created successfully with the capture mode set to Manual (Optional) |
| [Retrieve] Payment intent | GET /terminals the final result/transaction details from the Payment IntentsAPI after the terminal session has concluded. | The POS recognizes the status of the intent and records the sale on the POS |
| [Change] Payment intent amount [Optional] | Using the payment intent from a successful pre-authorization, use the POST /payment-intents/{paymentIntentId}/amount endpoint - This is before any pre-authorization or terminal session has taken place | Payment intent amount successfully updated |
| [Cancel] Payment intent [Optional] | Cancel a payment that has not yet been authorized by using DELETE /payment-intents/{paymentIntentId} | Payment intent is successfully cancelled |
| [List] All Payment intents [Optional] | List all payment intents by posting to POST /payment-intents/search. | Retrieves a list of payment intents. Results are paginated. By default, the method returns up to 50 payment intents. |
| Create Payment intent - MOTO (CNP) | Initiate a transaction with cardHolderNotPresent set to true. | The card machine should skip the Present Card screen and go directly into Key Card Number |
| itemLines | Use item lines to define checkout/bill items, and modifiers where applicable | Item lines should be correctly displayed and if discounts are present, these discounts should correctly display as modifiers. |
| Webhooks | Subscribe to Webhook events to be notified of specific events. | List of all events subscribed to by sending a GET request to Dojo's webhooks endpoints. |
Refunds
These tests concern the refunding of payments by directly invoking the Payment Intent, avoiding the need for a card to be re-presented.
| Scenario | Steps to Reproduce | Expected Outcome |
|---|---|---|
| Create a full refund | Initiate a refund of a previously completed Payment Intent by POSTing to the refunds endpoint. | A 200 response is returned containing a refundId. The POS should then call GET on the Payment Intent ID, parse the final result of the intent (Refunded), and display that the payment was refunded. |
| Create a partial refund | Initiate a refund of a previously completed Payment Intent by POSTing to the refunds endpoint. Select an amount lower than the original Payment Intent value. | A 200 response is returned containing a refundId. The POS should then call GET on the Payment Intent ID, parse the final result of the intent (Captured), and display that the payment was partially refunded. |
[Auto] Create Terminal Session - Sale
These tests cover the sales flow of terminal sessions created using CaptureMode: Auto, meaning that the transaction will be completed immediately. We look to cover as many possible transaction outcomes, including less common but still crucial flows such as Expired and Signature Verification.
| Scenario | Steps to reproduce | Expected outcome |
|---|---|---|
| Create terminal session - Successful while inserting card | Complete a transaction by inserting a card and using PIN entry or by using a Virtual Machine with TID ending in SIP0. | Must display transaction status of Captured. |
| Create terminal session - Successful with cashback | Complete a transaction with cashback amount specified. | Cashback should be applied to the amount displayed on the card machine and recorded by the POS. |
| Create terminal session - Successful with gratuity | Complete a transaction with gratuity amount specified. | Gratuity amount should be recorded by the POS. |
| Create terminal session - Successful with contactless | Complete a transaction by presenting card to contactless reader. | POS should display result of Captured. |
| Create terminal session - Successful with signature | Initiate a transaction by using a Virtual Machine with TID ending in SIP0. | POS should provide user with a dialogue box specifying that signature verification is required, and give the user an option to either accept or reject the signature. Selecting the accept option should send a PUT /terminals of accepted: true to the signature endpoint and lead to a successful payment. |
| Create terminal session - Successful with signature after 80 seconds | Initiate a transaction by using a Virtual Machine with TID ending in SIP0. At the status "SignatureVerificationRequired" the user should not select an option for 80s, allowing the sale to roll over to a successful state. The user should then either select to accept the signature, or the POS should gain the result from continued polling. Regardless, the status should be Captured. | POS should display result of Captured. |
| Create terminal session - Declined | Initiate a transaction by using a Virtual Machine with TID ending in DIP0. | POS should display status Declined. POS should re-use Payment Intent if transaction is re-attempted. |
| Create terminal session - Unsuccessful with signature rejection | Initiate a transaction by using a Virtual Machine with TID ending in SIP0. | POS should provide user with a dialogue box specifying that signature verification is required, and give the user an option to either accept or reject the signature. Selecting the accept option should send a PUT /terminals of accepted: false to the signature endpoint and lead to a declined payment. |
| Create terminal session - Successful with signature - rejection after 80 seconds | Initiate a transaction by using a Virtual Machine with TID ending in SIP0. At the status SignatureVerificationRequired the user should not select an option for 80s, allowing the sale to roll over to a successful state. The user should then either select to reject the signature, or the POS should gain the result from continued polling. Regardless, the status should be Captured. | POS should display result of Captured. |
| Create terminal session - Failure with busy terminal | Initiate a sale while PDQ is in menu. | POS should display that PDQ is not available. |
| Create terminal session - Cancel transaction from PDQ | Initiate a sale and cancel by selecting the X at the top of the PDQ screen before the card has been presented. | POS should display a result of Canceled. |
| Create terminal session - Cancel transaction from POS - Successful | Initiate a sale and cancel by sending a PUT /terminals to the cancel endpoint before the card has been presented. | POS should confirm status via polling and display a result of Canceled. |
| Create terminal session - Cancel transaction from POS - Unsuccessful | Initiate a sale and cancel by sending a PUT /terminals to the cancel endpoint after the card has been presented. | POS should confirm status via polling and transaction flow should be unaffected. |
| Create terminal session - Expired | Initiate a transaction by using a Virtual Machine with TID ending in TIP0 to retrieve a final status of Expired. | POS should display a dialogue advising that the result of the transaction cannot be confirmed and provide an option to manually record the sale on the POS as successful or retry if unsuccessful. |
| Terminal session - polling rate | POS should call GET on terminal session regularly (once per second) to receive notificationEvents and TerminalSessionStatus updates | Polling should occur regularly enough that status updates are captured and displayed appropriately. |
| Terminal session - display notifications | Complete several transactions invoking successful results, cancelation requests and signature verification to ensure relevant statuses are recorded effectively. | Terminal should display relevant notificationEvents and TerminalSessionStatus messages to the user to confirm the current state of the card machine. |
[Manual] Create Terminal Session - Preauth
These tests cover the sales flow of terminal sessions created using captureMode: Manual, meaning that the transactions will be pre-authorized and then captured subsequently. We will also look to cover behaviours such as incrementing the pre-authorized amount to ensure that the user experience is consistent.
| Scenario | Steps to Reproduce | Expected Outcome |
|---|---|---|
| Create terminal session - Successful with inserting card | Create a payment intent with capture mode set to manual. Create a terminal session and successfully authorize the payment using Chip and Pin or device verification. | Must display transaction status of Authorized. |
| Create terminal session - Successful with contactless | Create a payment intent with capture mode set to manual. Create a terminal session and successfully authorize the payment using device verification. | Must display transaction status of Authorized. |
| Create terminal session - Successful with different card type | Create a Payment intent with capture mode set to manual. Create a terminal session and successfully authorise the payment using a different card type to that used previously. | Must display transaction status of Authorized. |
| Create terminal session - Declined | Initiate a transaction by by using a Virtual machine with TID ending "DIP0". | POS should display status Declined. POS should re-use Payment Intent if transaction is re-attempted. |
| Update intent - Successful with increasing amount | Using the payment intent from a successful pre authorisation, use the "change payment intent amount" endpoint to increase the pre-authorized amount. | POS should receive a response with “Authorized” and display this. |
| Update intent - Unsuccessful amount change | Try to update a previously captured payment intent. | The POS would display the error returned from the Dojo API, such as Invalid request for payment with id pi_sandbox_EaaC8tw2fUKVVoSUt5JgJQ. The status Captured does not allow this change. |
| Update intent - Failure with non-existing payment intent id | Try to update an intent which does not exist. | The POS would ideally protect the user from this use case ever happening. |
| Update intent - Failure when updating amount to zero | Try to update an intent to an amount 0. | The POS would ideally protect the user from this use case ever happening. The POS would error with amount must be higher than 0. |
[Auto] Create Terminal Session - Refund
These tests cover the refund flow of terminal sessions created using captureMode: Auto, meaning that the refunds will be completed immediately.
| Scenario | Steps to Reproduce | Expected Outcome |
|---|---|---|
| Create terminal session [Unlinked Refund - Successful] | Initiate an unlinked refund which is then authorized successfully. | The POS should parse the status of Captured returned in the terminal-session object and display that the refund was successful. |
| Create terminal session [Unlinked Refund - Declined] | Initiate an unlinked refund which fails to authorize. | The POS should display that the refund was declined. |
| Create terminal session [Unlinked Refund - Expired] | Initiate an unlinked refund and remove the battery during the authorization, allowing the transaction to expire after several seconds, or by using a Virtual Machine ending in "TIP0" to retrieve a final status of Expired. | POS should display a dialogue advising that the result of the refund cannot be confirmed, Please check the card machine screen for the result and provide an option to manually record the refund on the POS as successful or retry if unsuccessful. |
| Create terminal session [Unlinked Refund - Cancelled] | Initiate an unlinked refund and cancel by selecting the X at the top of the PDQ screen before the card has been presented. | POS should display a result of Canceled. |
| Create terminal session [Unlinked Refund - Successful with signature accepted] | Initiate an unlinked refund by by using a Virtual machine with TID ending "SIS0". | POS should provide user with a dialogue box specifying that signature verification is required, and give the user an option to either accept or reject the signature. Selecting the accept option should send a PUT of "accepted": true to the signature endpoint and lead to a successful refund. |
| Create terminal session [Unlinked Refund - Unsuccessful with signature rejected] | Initiate an unlinked refund by by using a Virtual machine with TID ending "SIS0". | POS should provide user with a dialogue box specifying that signature verification is required, and give the user an option to either accept or reject the signature. Selecting the Decline option should send a PUT of "accepted": false to the signature endpoint and lead to a declined payment. |
| Create terminal session [Matched Refund - Successful] | Initiate a matched refund which is then authorized successfully. | The POS should call GET on the Payment Intent, retrieve the status of Refunded and confirm this to the user. |
| Create terminal session [Matched Refund - Declined] | Initiate a matched refund which fails to authorize. | The POS should display that the refund was declined. |
| Create terminal session [Matched Refund - Expired] | Initiate a transaction by by using a Virtual machine with TID ending "TIP0" to retrieve a final status of Expired. | POS should display a dialogue advising that the result of the refund cannot be confirmed, Please check the card machine screen for the result and provide an option to manually record the refund on the POS as successful or retry if unsuccessful. |
| Create terminal session [Matched Refund - Cancelled] | Initiate a matched refund and cancel by selecting the X at the top of the PDQ screen before the card has been presented. | POS should display a result of Canceled. |
| Create terminal session [Matched Refund - Successful with signature accepted] | Initiate a matched refund by by using a Virtual machine with TID ending "SIS0". | POS should provide user with a dialogue box specifying that signature verification is required, and give the user an option to either accept or reject the signature. Selecting the accept option should send a PUT of "accepted": true to the signature endpoint and lead to a successful refund. |
| Create terminal session [Matched Refund - Unsuccessful with signature rejected] | Initiate an unlinked refund by by using a Virtual machine with TID ending "SIS0". | POS should provide user with a dialogue box specifying that signature verification is required, and give the user an option to either accept or reject the signature. Selecting the Decline option should send a PUT of "accepted": false to the signature endpoint and lead to a declined payment. |
Error testing
These tests ensure that the POS is able to handle errors which will be returned from our API, ensuring that a valid error message and call to action is always displayed to the user.
| Error testing | Description / Steps |
|---|---|
| HTTP status code 400 - Bad Request | Occurs in the instance that a bad request is provided - this should be addressed prior to release by resolving the bad request. |
| HTTP status code 401 - Unauthorized | Occurs when an invalid API Key is submitted. It's important, particularly in customer-driven installations, to provide clear user error-messaging here to ask that the credentials submitted by checked. |
| HTTP status code 404 - Not found (TID unavailable) | In the event that the terminal is unavailable (offline, or powered off), the POS should advise the user accordingly and ask that they check the device status. |
| HTTP status code 422 - Unprocessable Entity | This can be tested by attempting to cancel a payment outside of the "Insert Card" screen. The POS should respond and carry on with the previous request, and ideally advise the user of why the error occurred (eg: Payment can only be cancelled during the "Initiated" phase). |