Skip to main content

Step-by-step guide

Learn how to generate payment links automatically through the API.

In terms of implementation, the integration contains:

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

  • WebHooks: at least one server-side endpoint, to receive information about the payment.

The payment flow is:

  1. The merchant server-side sends the payment information to the Dojo server to create a payment intent.

  2. The merchant server-side generates a payment link and sends it to the customer.

  3. The customer opens the payment link, and they are redirected to the Prebuilt Checkout Page. This is hosted by Dojo.

  4. The Prebuilt Checkout Page collects the customer's payment details and sends them to Dojo servers, then redirects the customer to the result page.

  5. The merchant server receives a WebHook notification when the customer uses the payment link.

How to process a payment​

Step-by-step guide:

  1. Create a payment link.

  2. Send the payment link to your customer.

  3. Handle post-payment events.

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

To create a payment link, first call a server-side endpoint 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.

  • paymentSource: "payment-links": Information regarding the payment source type. Without this parameter, you won't be able to filter the transaction by type.

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

server.py
loading...

See the API reference for a complete list of parameters that can be used for payment intent creation.

After receiving the request, Dojo creates a payment intent and returns its unique ID:

{
    "id": "pi_sandbox_RBMHTJ4fIkmSppDILZVCGw",
    ...
}

Return this ID to the client-side and use it to create a link in the following format:

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

Send the link to your customer through chat or email. When the customer opens the link, they'll redirect to Dojo Prebuilt Checkout Page. After the customer fills in their payment information, Dojo processes the payment and redirects the customer to the success page.

Step 3. 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 4. Test and go live​

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

Card NameCard numberExpiry DateCVV3D securityStatus
Test Cardholder5200 0000 0000 100512/24020NoSuccessful
Test Cardholder5200 0000 0000 109612/240202.0Successful
Test Cardholder4456 5300 0000 101312/24341NoDecline

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

Next steps​

Set up notification WebHook Use WebHooks to receive updates related to your payments.

Configure Dojo Checkout Page Find out how to add another payment method or shipping address form to the page.

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