Embedded Checkouts

Recurrente Checkout is a JavaScript library that lets you embed a responsive, secure checkout directly on your website. It renders an iframe with your payment session and handles callbacks for key events like success, failure, or pending payments.

For the most up-to-date version of this guide and sample code, visit the repo: github.com/recurrente/recurrente-checkout

Video tutorial

See it in action: https://youtu.be/OUIYVcrnPr0

Prerequisites

To use this library, you need to create a checkout in Recurrente. See the checkout creation docs to get your checkout URL.

Installation

NPM (Recommended)

$ npm install @recurrente/checkout

CDN

1 <script src="https://cdn.jsdelivr.net/npm/@recurrente/checkout/dist/recurrente-checkout.min.js"></script>

Usage

1 import RecurrenteCheckout from "@recurrente/checkout";
2 
3 const checkout = new RecurrenteCheckout({
4   url: "https://app.recurrente.com/checkout-session/ch_abc123",
5   container: "#checkout-container",
6   onSuccess: (data) => {
7     console.log("Payment successful", data);
8   },
9   onFailure: (data) => {
10     console.log("Payment failed", data);
11   },
12   onPending: (data) => {
13     console.log("Payment pending", data);
14   },
15 });
16 
17 checkout.open();

Parameters

Parameter	Type	Description
`url`	string	The checkout session URL (obtained when creating a checkout via API)
`container`	string	CSS selector of the element where the iframe will be mounted
`onSuccess`	function	Callback when payment succeeds
`onFailure`	function	Callback when payment fails
`onPending`	function	Callback when payment is pending (e.g. bank transfer)

Full flow

Create a checkout via the Recurrente API (POST /api/checkouts)
Use the URL from the checkout (checkout_url) to initialize RecurrenteCheckout
Mount the checkout in an HTML container on your page
Handle callbacks for success, failure, or pending payments

1 // 1. Create checkout from your backend
2 const response = await fetch("/api/create-checkout", { method: "POST" });
3 const { checkout_url } = await response.json();
4 
5 // 2-4. Mount and initialize
6 const checkout = new RecurrenteCheckout({
7   url: checkout_url,
8   container: "#payment-form",
9   onSuccess: () => window.location.href = "/thank-you",
10   onFailure: () => alert("Payment failed. Please try again."),
11 });
12 
13 checkout.open();

For the most up-to-date version of this guide and sample code, visit the repo: github.com/recurrente/recurrente-checkout

Video tutorial

See it in action: https://youtu.be/OUIYVcrnPr0

Prerequisites

To use this library, you need to create a checkout in Recurrente. See the checkout creation docs to get your checkout URL.

Installation

NPM (Recommended)

$ npm install @recurrente/checkout

CDN

1 <script src="https://cdn.jsdelivr.net/npm/@recurrente/checkout/dist/recurrente-checkout.min.js"></script>

Usage

1 import RecurrenteCheckout from "@recurrente/checkout";
2 
3 const checkout = new RecurrenteCheckout({
4   url: "https://app.recurrente.com/checkout-session/ch_abc123",
5   container: "#checkout-container",
6   onSuccess: (data) => {
7     console.log("Payment successful", data);
8   },
9   onFailure: (data) => {
10     console.log("Payment failed", data);
11   },
12   onPending: (data) => {
13     console.log("Payment pending", data);
14   },
15 });
16 
17 checkout.open();

Parameters

Parameter	Type	Description
`url`	string	The checkout session URL (obtained when creating a checkout via API)
`container`	string	CSS selector of the element where the iframe will be mounted
`onSuccess`	function	Callback when payment succeeds
`onFailure`	function	Callback when payment fails
`onPending`	function	Callback when payment is pending (e.g. bank transfer)

Full flow

Create a checkout via the Recurrente API (POST /api/checkouts)
Use the URL from the checkout (checkout_url) to initialize RecurrenteCheckout
Mount the checkout in an HTML container on your page
Handle callbacks for success, failure, or pending payments

1 // 1. Create checkout from your backend
2 const response = await fetch("/api/create-checkout", { method: "POST" });
3 const { checkout_url } = await response.json();
4 
5 // 2-4. Mount and initialize
6 const checkout = new RecurrenteCheckout({
7   url: checkout_url,
8   container: "#payment-form",
9   onSuccess: () => window.location.href = "/thank-you",
10   onFailure: () => alert("Payment failed. Please try again."),
11 });
12 
13 checkout.open();

1	import RecurrenteCheckout from "@recurrente/checkout";
2
3	const checkout = new RecurrenteCheckout({
4	url: "https://app.recurrente.com/checkout-session/ch_abc123",
5	container: "#checkout-container",
6	onSuccess: (data) => {
7	console.log("Payment successful", data);
8	},
9	onFailure: (data) => {
10	console.log("Payment failed", data);
11	},
12	onPending: (data) => {
13	console.log("Payment pending", data);
14	},
15	});
16
17	checkout.open();

1	// 1. Create checkout from your backend
2	const response = await fetch("/api/create-checkout", { method: "POST" });
3	const { checkout_url } = await response.json();
4
5	// 2-4. Mount and initialize
6	const checkout = new RecurrenteCheckout({
7	url: checkout_url,
8	container: "#payment-form",
9	onSuccess: () => window.location.href = "/thank-you",
10	onFailure: () => alert("Payment failed. Please try again."),
11	});
12
13	checkout.open();