Skip to main content

Step-by-step guide

Learn how to create a setup intent and charge the card using the API.

During its lifecycle, the Setup Intent goes through a combination of the following statuses, depending upon your requirements.

StatusDescription
CreatedThe setup intent is created.
AuthorizedThe customer adds their card details and authorizes the setup intent.
ExpiredThe setup intent expired after creation.
CardExpiredThe card entered has passed the expiry date and is no longer usable.
CanceledThe setup intent in created state is deleted.
CompletedThe setup intent cycle is complete and the merchant has charged the customer's card.
ClosedThe authorized setup intent is also deleted. This is applicable when you set includeAuthorized to true using the DELETE /setup-intents endpoint.

Flow diagram​

Setup Intent Flow

Step 1: Capture customer card details​

Firstly, the customer's card details must be entered, such as into an i-frame, and securely captured by the client server.

note

In order to handle and store cardholder data, you will need to be able to provide evidence of attestation for PCI DSS SAQ-D, indicating that you are compliant with industry requirements with regard to the safe handling of this data.

A certificate of compliance must be provided to Dojo annually for continued useage of our tokenization services.

Step 2: Create a setup intent and authorize the card​

To authorize and tokenize the captured cardholder data for a future payment, you must create a setup intent via a POST to the unique URL and endpoint below:

POST pci-api.dojo.tech/setup-intents

info

The creation of the initial setup intent for tokenization is the only instance in which the pci-api.dojo.tech URL is invoked. Follow-up setup intent calls referencing the created intent must be made to api.dojo.tech.

Dojo will attempt to authorize against the card details provided and then respond by confirming in the response body the details of the setup intent and attempted authorization, such as the status, time of creation and an id to be referenced in future calls. If the returned status is "Authorized", the card can then be charged by creating a payment intent.

Once you've created a setup intent, the status is updated to ⦿ created.

Step 3: Create a payment intent and charge the card​

After a setup intent has been created and authorized, you can use the setupIntentId (created in step 2) to create a payment intent and charge the card. When you are ready to charge the card, create a payment intent and then use the payment intent charge endpoint.

info
  • You can charge the full amount only.
  • You can only charge a card once.

Charge a card using the Dojo API​

To complete the process of charging a card, ensure you do the following:

  1. Create a payment intent and pass the setupIntentId to the request.

    POST /payment-intents

    { ...
       "setupIntentId": "si_sandbox_<secret-key>",
    }

    Request example

    The following code sample demonstrates creating a payment intent of 10.00 GBP using the setup intent ID:

    setup-intent/curl/create-payment-intent.sh
    loading...

    Once you create a payment intent to charge the card, the setup intent status is still ⦿ authorized.

  2. Initiate a charge to complete the process:

    POST /payment-intents/{paymentIntentId}/charge

    In your request, include:

    paymentIntentId: This identifies the payment intent to be charged.

    Request example

    The following code sample demonstrates initiating a charge of 10.00 GBP against the payment intent ID created in the above step:

    setup-intent/curl/charge-card.sh
    loading...

    Once you charge the card successfully, the setup intent status is updated to ⦿ completed.

Step 4: Check setup intent status​

GET /setup-intents/{setupIntentId}

Every time you perform an action with the Setup IntentAPI, it transitions through a state. We recommend that you subscribe to notifications to check the current status of your setup intent.

In your request, include:

setupIntentId: identifies the setup intent you want to track.

For the full API specification, see the API reference.

Request example​

The following example shows how to check the status of the setup intent:

setup-intent/curl/retrieve.sh
loading...

The response will return information about the setup intent and its status.

Last updated on