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.

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.

Flow diagram: Flow Card

sequenceDiagram
    actor C as Customer
    participant MC as Merchant Client-side
    participant MS as Merchant Server-side
    participant D as dojo

    C->>MC: Clicks "Checkout"
    MC->>MS: Sends information about customer purchases
    MS->>D: POST /payment-intents
    D-->>MS: PaymentIntent object
    MS-->>MC: Returns clientSessionSecret
    C->>MC: Enters payment details and clicks "Pay"
    MC->>D: 
    D-->>MC: Redirects to the result page
    D->>MS: Sends webhooks
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
<head>
    <link rel="stylesheet" href="static/styles.css">
    <script src="https://cdn.dojo.tech/payments/v1/client.js"></script>
    <script src="static/script.js"></script>
</head>

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

index.html

<body>
    <h1>Card component</h1>
    <div id="demo-payment"></div>
    <div id="errors"></div>
    <button id="testPay" class="btn-primary btn pull-right" data-loading-text="Processing...">Pay</button>
    <div id="demo-result" hidden>
        <h5>Payment Complete</h5>
        <dl>
            <dt>Status Code</dt>
            <dd id="status-code"></dd>
            <dt>Auth Code</dt>
            <dd id="auth-code"></dd>
        </dl>
    </div>
</body>

Step 2. Set up Dojo card component​

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

script.js
    .then(response => response.json())
    .then(function (data) {
        const config = {
            paymentDetails: {
                paymentToken: data.clientSessionSecret,
            },
            containerId: "demo-payment",
            fontCss: ['https://fonts.googleapis.com/css?family=Do+Hyeon'],
            styles: {
                base: {},
            }    
        }

        // intialising connection
        const card = new Dojo.Payment(config, displayErrorsCallback);

        // sending payment on button click and processing the response
        const btnTestPay = document.getElementById("testPay");

        btnTestPay.onclick = () => {
            btnTestPay.innerText = 'loading';
            btnTestPay.setAttribute("disabled", "true");
            card.executePayment()
                .then(function (data) {
                    document.getElementById("demo-payment").hidden = true;
                    btnTestPay.remove();
                    document.getElementById("demo-result").hidden = false;
                    document.getElementById("status-code").innerText = data.statusCode;
                    document.getElementById("auth-code").innerText = data.authCode;
                }).catch(function (data) {
                    console.log('Payment Request failed: ' + data);
                    btnTestPay.innerText = 'Pay';
                    btnTestPay.removeAttribute("disabled");
                    if (typeof data === 'string') {
                        document.getElementById("errors").innerText = data;
                    }
                    if (data && data.message) {
                        document.getElementById("errors").innerText = data.message;
                    }
                }
                );
        };

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

script.js
        function displayErrorsCallback(errors) {
            const errorsDiv = document.getElementById('errors');
            errorsDiv.innerHTML = '';
            if (errors && errors.length) {
                const list = document.createElement("ul");
                for (const error of errors) {
                    const item = document.createElement("li");
                    item.innerText = error.message;
                    list.appendChild(item);
                }
                errorsDiv.appendChild(list);
            }
        }

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
fetch('/checkout', {

    // Declare what type of data we're sending
    headers: {
        'Content-Type': 'application/json'
    },
    // Specify the method
    method: 'POST',
    mode: 'no-cors',

    // A JSON payload
    body: JSON.stringify({
        "greeting": ""
    })
})

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
        payload = json.dumps({
          "amount": {
            "value": 1000,
            "currencyCode": "GBP"
          },
          "reference": "Order 245",
          "paymentMethods": ["Card"]
          })
        headers = {
            'Content-Type': "application/json",
            'Version': "2024-02-05",
            'Authorization': "Basic sk_sandbox_c8oLGaI__msxsXbpBDpdtwJEz_eIhfQoKHmedqgZPCdBx59zpKZLSk8OPLT0cZolbeuYJSBvzDVVsYvtpo5RkQ" # <-- Change to your secret key
            }
        conn.request("POST", "/payment-intents/", payload, headers)

        # handling the response from POST
        res = conn.getresponse()
        data = res.read()
        resp_data = {}
        resp_data['clientSessionSecret'] = json.loads(data)["clientSessionSecret"]
        print(resp_data)
        json_data = json.dumps(resp_data)
        resp = app.response_class(
          response=json_data,
          mimetype='application/json'
          )
        return resp

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:

# 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 -v --request POST \
  --url https://api.dojo.tech/webhooks \
  --header 'Authorization: Basic sk_sandbox_c8oLGaI__msxsXbpBDpdtwJEz_eIhfQoKHmedqgZPCdBx59zpKZLSk8OPLT0cZolbeuYJSBvzDVVsYvtpo5RkQ' \
  --header 'Content-Type: application/json' \
  --header 'Version: 2024-02-05' \
  --data '{
    "events": ["payment_intent.status_updated"],
    "url": "https://example.com/incoming-events"
  }'

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