Second Chance Widget with SMI Example
This guide will teach you how to implement the Second Chance Widget using Zip's Single Merchant Interface.
Overview
Zip's SMI API aims to provide partners with a single way to integrate with Zip in both the US and ANZ regions. This allows for greater flexibility for partners that operate globally to provide Zip as a payment option without the need to write custom code for each region.
The SMI API is documented here: https://developers.zip.co/v2/reference/getting-starteds
Pre-requisites
- Talk to the Zip Integrations team to set up an SMI account and receive your SMI API key.
- Have a backend service capable of receiving HTTP calls and responding appropriately
Backend Implementation
You'll need to expose an API endpoint that your frontend can call to retrieve a unique checkout URL from SMI. The reason you need to do this from your backend servers is that the SMI API is accessed via a secret API key. If you were to make the request to SMI from your frontend code, you'd expose the secret to bad actors who are looking through the browser's code.
Read the SMI /checkouts documentation here.
Frontend Implementation
You'll need to now call the new API endpoint that you exposed. After retrieving the checkout details, you can safely re-direct the client browser to the Zip checkout experience. After the checkout journey is completed, the browser will be redirected back to your configured redirect_uri
.
Make sure that you register the event with the click listener, shown in the JavaScript snippet below. You can read more details here.
<!DOCTYPE html>
<html>
<head>
<!-- Zip Library: https://docs.us.zip.co/docs/introduction -->
<script src="https://cdn.sand.us.zip.co/v1/zip.js"></script>
</head>
<body>
<!-- Second Chance Widget: https://docs.us.zip.co/docs/second-chance-widget -->
<zip-second-chance-widget
amount="100"
currency="USD"
backgroundColor="black"
borderStyle="curved"
integrationType="api">
</zip-second-chance-widget>
</body>
</html>
// create a callback that will respond when the second chance widget is clicked
function clickListener = () => {
const amount = apiPopupSecondChanceWidget.getAttribute("amount");
const currency = apiPopupSecondChanceWidget.getAttribute("currency");
// retrieve SMI url from your backend API, then redirect to the checkout
const request = new Request("[your API url]", {
body: JSON.stringify({
amount,
currency,
redirect_uri: "[your order confirmation url]",
reference: "[your order id]"
}),
method: "POST"
});
// parse the response from the API
const response = await fetch(request);
const body = await response.json();
// navigate the browser to the Zip checkout journey
window.location.assign(body.uri);
}
// register the callback with the widget event
apiPopupSecondChanceWidget.onClickCheckoutButton(clickListener);
Updated about 17 hours ago