Skip to main content

Step-by-step guide

Step-by-step guide to set up your own virtual terminal.

Setup flow​

To set up a virtual terminal for your web app, do the following:

info

Step 1. Create a payment intent​

To create a payment intent, call a server-side endpoint. For that, the following parameters are required:

  • amount: This includes the currency and value, in minor units, for example, "1000" for 10.00 GBP.
  • reference: Your unique reference for the payment intent.
  • cardHolderNotPresent: "true": Confirms that the card holder is not present during the transaction.
info
  • When cardHolderNotPresent is set to true, it means payments are made through the mail or over the telephone. They are a common use case for virtual terminals.
  • To process these transactions, you must have a virtual terminal to accept payments over the phone, fax, email, or by mail. This type of transaction is common for businesses that operate remotely or have a significant online presence.
  • Using cardHolderNotPresent, you can implement a virtual terminal in components and Mobile integration.

Here's an example of how to create a virtual terminal payment for 10 GBP:

virtual-terminal.py
loading...

Step 2. Redirect to Dojo Checkout Page​

  1. After receiving the request, Dojo creates a payment intent and returns its unique ID:
{
    "id": "pi_sandbox_RBMHTJ4fIkmSppDILZVCGw",
    ...
}
  1. Return this id to the client-side and use it to create a link in the following format:

https://pay.dojo.tech/checkout/{{id}}

  1. Share the link with your merchant. Clicking this link will render the checkout page at the merchant's end.
warning

Do not share this link with your customer. This link is for the merchant use only.

Step 3. Request card details from the customer​

Next, the merchant requests card details from the customer over a call, email, or mail order. When the customer authorizes the merchant to make the payment, the merchant fills in the customer's card details on the checkout page. Dojo processes the payment and redirects to the success page. Finally, the customer is notified via email about the successful payment.

Step 4. Handle post-payment events​

After a user completes a payment, we recommend using webhooks to update the backend result and receive information about the payment. Set up endpoints to receive and handle webhook requests. By using webhooks, your application can receive updates about payment events and you can ensure that you don't lose any information about the payment. To handle these events, configure your backend for incoming webhook notifications and process these notifications accordingly. Dojo's backend sends a payment_intent.status_updated event when the payment is completed (captured, refunded, reversed, canceled).

To set up webhooks, review our webhooks guide.

info

Ensure you validate the transaction result by either using a webhook or making a direct API call on your backend. The result code received on the application front-end might not be reliable as you might receive delayed responses.

Here's an example of how to subscribe to the payment_intent.status_updated event:

webhooks/curl/enable-webhooks.sh
loading...

Step 5. Test and go live​

Before going live, test your integration using the test card numbers:

Card NameCard numberExpiry DateCVV3D securityStatus
Test CardholderCopy
5200 0000 0000 1005Copy
12/29Copy
020Copy
NoSuccessful
Test CardholderCopy
5200 0000 0000 1096Copy
12/29Copy
020Copy
2.0Successful
Test CardholderCopy
4456 5300 0000 1013Copy
12/29Copy
341Copy
NoDecline

When you are ready to go live, switch your secret key to production one with the prefix sk_prod_.

Last updated on