Guides

Quickstart

Suggest Edits

🚧

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 via https://merchant.getivy.de/sign-up to retrieve your Ivy API Secret, configure your account and get sandbox access.

Step 2: Integrate Ivy Checkout Button

  1. Code Placement: Insert this code snippet in the <body> section of your HTML or before other script tags and replace X-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>

  2. 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>

  3. 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

  1. Press the checkout button.
  2. Select the bank Ivy Test Bank.
  3. Follow the Flow and enter random credentials to complete the payment.
  4. 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.

  1. Clone the project
  2. 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 about 1 month ago

What’s Next