Skip to main content

Step-by-step guide

Learn how to accept payments in your Android app using our mobile SDK. This guide explains the process of integrating the checkout experience in your app.

Checkout experience flow​

The following explains the flow of a user's journey in the checkout experience.

info
  • The term user used in this document refers to a customer trying to make a payment through your mobile application.
  • This guide assumes you named the button on your checkout screen as Checkout.

  1. A user visits your app and taps Checkout.

  2. Your mobile app sends the user's purchase information to your backend, your backend sends this information to Dojo's backend to create a payment intent.

  3. Your mobile app starts the checkout process using the mobile SDK.

  4. The mobile SDK collects the user payment details, sends them to the Dojo backend, and presents a result screen to the user. The mobile SDK then notifies the hosting application of the payment result.

  5. Your backend receives a webhook notification when the payment is completed.

How to process a payment​

This is a step-by-step guide that demonstrates how to process payments with Dojo's backend and your backend into your mobile app using Dojo's mobile SDK.

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

This guide contains the following steps:

  1. Create a payment intent.

  2. Start the checkout process.

  3. Handle post-payment events.

  4. Test and go live.

Step 1. Create a payment intent​

With the checkout button in your app, call your backend and then call Dojo's backend endpoint to create a payment intent.

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, like the order number.

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

server.py
loading...

See the API reference for a complete list of parameters that can be used for payment intent creation. For configurations that apply to our mobile SDK, go to Configurations.

Step 2. Start checkout process​

Once you've created the payment intent, pass the payment intent ID to your payment flow code.

info

To start the checkout process, ensure you have installed the latest SDK.

capture-card.kts
loading...

After the user fills in their payment information on the checkout screen, Dojo processes the payment and redirects the user to the result screen. The app receives a result code.

info

For additional configurations that apply to our mobile SDK, go to configurations.

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

Result codes​

When you make a payment using an SDK integration, your app will receive a result code. Refer to the following result codes for more information.

Result codeResultDescription
0SuccessfulThe transaction was successful.
3AuthorizingThe card holder hasn't completed 3DS, this status will only be seen on the REST API.
4ReferredThe card issuer has parked the transaction awaiting contact with the customer before proceeding to authorize or decline the transaction.
5DeclinedThe transaction was declined by the card issuer or acquiring bank.
20Duplicate TransactionThe transaction which was processed was a duplicate. Ensure each transaction has a unique OrderId.
30FailedError executing transaction.
400Invalid RequestThe request has failed validation by our servers and the transaction hasn't been submitted to the gateway. Possible causes for this are invalid transaction type or other data in the request.
401Issue with Access TokenThe access token being used isn't valid, the transaction hasn't been submitted to the gateway. This can be caused if the token has already been used or the 30 minute expiry time has elapsed.
404No Access Token SuppliedNo access token has been supplied. Transaction hasn't been submitted to the gateway.
500Internal Server ErrorThere's been an error submitting the transaction, please check the REST API for the status of the transaction.
7770SDK Internal ErrorThere's a problem on the SDK side. Contact Dojo for more information.
Last updated on