Skip to main content

Card

Learn how you can embed the prebuilt Dojo Card Component into your checkout page.

The Dojo Card Component is a prebuilt JavaScript component for accepting payments on your checkout page. Use this integration option when you want full control over the payment flow and the look of your checkout page. This solution is PCI-compliant, so you are only required to submit Self-Assessment Questionnaire A in order to be able to use it.

In terms of implementation, the integration contains:

  • Server-side: one API request to create a payment intent.

  • Client-side: set up Dojo Card Component, which securely sends payment data to our server.

  • Webhooks: server-side endpoint to receive information about the payment.

The payment flow is:

  1. The customer visits the merchant's site and clicks the Checkout button.

  2. The merchant client-side sends the customer's purchase information to the merchant server-side, and the merchant server-side sends this information to Dojo server to create a payment intent.

  3. The merchant client-side creates an instance of the card component using the clientSessionSecret.

  4. The customer enters payment details directly on the merchant checkout page to the card component.

  5. The card component collects the customer's payment details, sends them to the Dojo servers, and redirects the customer to the result page.

  6. The merchant server receives a webhook notification when the payment is completed.

info

If you’re looking for a low-code option, take a look at our pre-built checkout.

How to process a payment​

Step-by-step guide:

  1. Add the component to your checkout page.

  2. Set up Dojo Card Component.

  3. Create a payment intent.

  4. Handle post-payment events.

  5. Test and go live.

Before you start​

Before you begin to integrate, make sure you have followed the Getting started guide and got your API keys. For the test environment, use your secret key with the prefix sk_sandbox_.

Step 1. Add the component to your checkout page​

Include Dojo client.js script on your checkout page. This script must always load directly from cdn.dojo.tech to remain PCI compliant—you can’t include it in a bundle or host a copy of it yourself.

index.html
loading...

Add empty placeholders div to your checkout page to create a payment form. For example:

index.html
loading...

Step 2. Set up Dojo card component​

Next, in your JavaScript file, create an instance of Dojo:

script.js
loading...

You can add an optional callback to display validation errors, such as invalid CVV or card number:

script.js
loading...

See the Optional configuration for a complete list of parameters that you can use.

Step 3. Create a payment intent​

Call a server-side endpoint to create a payment intent, for example:

script.js
loading...

To create a payment intent, 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.

  • paymentMethods: "Card": The payment method that customers can use to pay.

Here's an example of how to create a payment intent on your server-side:

server.py
loading...

See the API reference for a complete list parameters that you can use.

Step 4. Handle post-payment events​

Use webhooks to receive information about the payment. We send a payment_intent.status_updated event when the payment is completed (captured, refunded, released, reversed, canceled).

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

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

If you haven't set up webhooks yet, review our webhooks guide.

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_.

Next steps​

Set up notification webhooks Use webhooks to receive updates related to your payments.

Configure Dojo Components Find out how you can configure the Dojo Components.

Check your integration Check off these steps before launching your integration in production.

Manage payments Learn how to capture or reverse payments, retrieve payment details or change payments amount.

Last updated on