Skip to main content

Checkouts & Payments

Payment Intent - A gateway-specific attempt to complete a transaction.

Checkout Intent - An optional, gateway-agnostic, attempt to complete a transaction.

A Checkout Intent can only be created from the API and is typically created from your back-end before a user selects a specific gateway, it also returns to you a list of gateways that are relevant to this checkout, given that many gateways have restrictions on amounts or cart items.

A Payment Intent can be spawn out of an existing Checkout Intent, or it can be created as a stand-alone object. You must specify a gateway to create a Payment Intent and you usually create them once your user has selected a gateway.

Both payment Intents and Checkout Intents follow a similar Lifecycle.

Connected Mutability​

All Payment Intents that are created from a Checkout Intent share the same mutability in case of success: if 1 payment intent is marked as successful, all other Payment Intents created from that Checkout Intent will be automatically cancelled to avoid duplicate transactions.

If any other Payment Intent succeeds at the same time, it will be refunded automatically.

Timeouts​

You can specify a timeout in seconds to both a Payment Intent and a Checkout Intent, however they behave differently.

A Payment Intent will die after the specific timeout is lapsed from its creation. Any successful payments that may happen afterwards will automatically be refunded.

A Checkout Intent never dies, the timeout that you give it will be used as a default timeout when spawning new Payment Intents.

Workflow​

  1. From your back-end, generate a Checkout Intent ID as soon as your customer starts the checkout process. You can safely pass this Checkout Intent ID to your front-end.
  2. Display the list of gateways to your users and let them select which gateway they wish to transact with.
  3. When a gateway is selected, either embed the UI or redirect the user.
  4. Once the user has completed or failed their checkout with that gateway, they will be redirected to your success/failure URL.

Create a Checkout Intent​

The only way to create a Checkout Intent is to call the Checkout Intent API.

Create a Payment Intent​

There are 3 ways to create a Payment Intent:

1. From your back-end​

You can use the Payment Intent API to create a Payment Intent, either to be spawn out of a Checkout Intent or as a stand-alone.

You can then either redirect the customer or embed the UI using that Payment Intent ID.

2. From your front-end​

Using a standard XHR call to the Payment Intent API to fetch a Payment Intent ID. Because this is assumed unsafe, this spawns the Payment Intent out of the Checkout Intent and it only works if you provide a Checkout Intent ID.

You can then either redirect the customer or embed the UI using that Payment Intent ID.

You can directly redirect the customer to /payment-intents/<payment-intent-id>/redirect which will create a Payment Intent on the fly. You will instantaneously receive a Payment Intent ID by webhooks.

This is the preferred route to reduce latency in the checkout process.