Quickstart
Ivy API calls
Call the Ivy-API only server-side, never client-side.
This is only a quick start to test locally and should not be used in production.
Step 1: Create your Ivy account
Create your Ivy account by requesting access via [email protected] to retrieve your Ivy API Secret.
Step 2: Integrate Ivy Checkout Button
-
Code Placement: Insert this code snippet in the
<body>
section of your HTML or before other script tags and replaceX-Ivy-Api-Key
with your Ivy API key.<!-- Ivy sandbox bundle, for production use https://cdn.getivy.de/button.js --> <script src="https://cdn.sand.getivy.de/button.js"></script> <script> function createCheckout() { return fetch( // Sandbox API, for production use https://api.getivy.de "https://api.sand.getivy.de/api/service/checkout/session/create", { headers: { "content-type": "application/json", // Never use your Ivy API key on client side. This is only for demo purposes. "X-Ivy-Api-Key": "REPLACE_WITH_YOUR_IVY_API_KEY", }, method: "POST", body: JSON.stringify({ referenceId: self.crypto.randomUUID(), // Your unique identifier for the order/reference price: { total: 1, currency: "EUR", }, guest: true, // Indicates a guest checkout, user does not need to log in locale: "en", // Checkout window language. Options: de, nl, en, fr, es, it, pt, sv successCallbackUrl: "https://www.success-url.com", // Redirect URL on successful payment errorCallbackUrl: "https://www.error-url.com", // Redirect URL on payment failure/error }), } ) .then((result) => result.json()) .then((data) => { // Opens the Ivy checkout web modal startIvyCheckout(data.redirectUrl); }) .catch((e) => console.error("Checkout failed", e)); } </script>
-
Code Placement: For integrating the Ivy Checkout Button, place this snippet where you want the button to appear in your HTML.
<button class="ivy-checkout-button" onClick="{createCheckout()}" data-locale="en" // Checkout button language. Options: de, nl, en, fr, es, it, pt, sv ></button>
-
Code Placement: Ensure to place the entire HTML structure, including the above code snippets, within the
<body>
tag of your HTML file.
Step 3: Test the checkout-flow
- Press the checkout button.
- Select the bank
Ivy Test Bank
. - Follow the Flow and enter random credentials to complete the payment.
- Complete the flow and be redirected to the
successCallbackUrl
.
Finished, now you're all set
Full Example combined
<!DOCTYPE html>
<html>
<body>
<button
class="ivy-checkout-button"
onClick="{createCheckout()}"
data-locale="en" // Checkout button language. Options: de, nl, en, fr, es, it, pt, sv
></button>
<!-- Ivy sandbox bundle, for production use https://cdn.getivy.de/button.js -->
<script src="https://cdn.sand.getivy.de/button.js"></script>
<script>
function createCheckout() {
return fetch(
// Sandbox API, for production use https://api.getivy.de
"https://api.sand.getivy.de/api/service/checkout/session/create",
{
headers: {
"content-type": "application/json",
// Never use your Ivy API key on client side. This is only for demo purposes.
"X-Ivy-Api-Key": "REPLACE_WITH_YOUR_IVY_API_KEY",
},
method: "POST",
body: JSON.stringify({
referenceId: self.crypto.randomUUID(), // Your unique identifier for the order/reference
price: {
total: 1,
currency: "EUR",
},
guest: true, // Indicates a guest checkout, user does not need to log in
locale: "en", // Checkout window language. Options: de, nl, en, fr, es, it, pt, sv
successCallbackUrl: "https://www.success-url.com", // Redirect URL on successful payment
errorCallbackUrl: "https://www.error-url.com", // Redirect URL on payment failure/error
}),
}
)
.then((result) => result.json())
.then((data) => {
// Opens the Ivy checkout web modal
startIvyCheckout(data.redirectUrl);
})
.catch((e) => console.error("Checkout failed", e));
}
</script>
</body>
</html>
Sample Shop
For a comprehensive example integrating Ivy API with a full-stack application, check out our Ivy Docs Sample Shop project on GitHub to see how Ivy API can be implemented.
- Clone the project
- Follow the README for step-by-step instructions on running the client and server
# Clone the repository
git clone https://github.com/getivy/ivy-docs-sample-shop.git
# Navigate to the `server` directories,
# copy the .env.example file to .env,
# then fill out IVY_API_KEY in .env
cd ./ivy-docs-sample-shop/server && cp .env.example .env
# To install the dependencies for this project,
# navigate to both the `client` and `server` directories in your terminal and run:
yarn && cd ../client && yarn
# Start the client and server in parallel
cd ../server && yarn start &
cd ../client && yarn dev &
# Clone the repository
git clone https://github.com/getivy/ivy-docs-sample-shop.git
# Navigate to the repo-folder
cd ./ivy-docs-sample-shop
# This project includes a docker-compose.yml file
# that allows you to run the client and server in Docker containers.
# To start the containers, run:
docker-compose up
Updated 3 months ago