​
Overview

The Ivy API uses API Keys to authenticate requests. You can view and manage your API Key in the Ivy Dashboard. To request access to the Ivy Dashboard, please contact our support team.

​
Your API Key carries many privileges, so be sure to keep it secure!

Do not share your secret API Keys in publicly accessible areas such as GitHub, client-side code, and so forth.

​
API Keys

Ivy authenticates your API requests using your account’s API Key. To authenticate each request to the Ivy API, set your API Key in the X-Ivy-Api-Key header.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. Ivy returns an authentication error 401 if the key is incorrect or outdated.

You can use the Ivy Dashboard to rotate your API Key. If you’re setting up Ivy through a Third-Party Platform (3PP), copy and paste your API Key in live mode to begin processing payments.

​
Sandbox and Production Modes

All Ivy API requests occur in either Sandbox or Production Mode. API objects in one mode aren’t accessible in the other. For instance, a Sandbox User object cannot be part of a Production-Mode Checkout Session.

TypeBase URLWhen to UseHow to Use
Sandboxhttps://api.sand.getivy.deUse this mode as you build your app. In Sandbox Mode, payments will not be processed.Integrate Ivy as you would in Production Mode. You will automatically be redirected to test payment flows.
Productionhttps://api.getivy.deUse this mode when you’re ready to launch the checkout. In Production Mode, payments will be processed.Use valid bank accounts. Use actual payment authorizations and payment flows.

​
Generate a New API Key

  1. Go to your Ivy Dashboard
  2. Click on the Generate API Key button

​
By generating a new API Key, all previously generated API Keys will be revoked

​
Code Example

Here’s an example of an authenticated request to the Ivy Sandbox API:

curl https://api.sand.getivy.de/api/service/ping \
    -H 'Content-Type: application/json'
    -H 'X-IVY-API-KEY: <api-key>'
    -d '{}'

​
Webhooks

Ivy may send requests to endpoints that you set up, for example, as Webhooks.

​
Security & Signature

All requests sent to your endpoints will include the X-Ivy-Signature header. Verify this value to ensure the request is coming from Ivy and not from a third party.

To validate incoming requests:

  • Obtain the Webhook Signing Secret from the Ivy Dashboard
  • Check the X-Ivy-Signature Header against a newly calculated Signature for every incoming request
  • Calculate the signature using the request body and the Webhook Signing Secret with HMAC & SHA-256 Hash

​
Code Examples

const { createHmac } = require('crypto')
const config = require('../config')

/*
This middleware validates the request body against the X-Ivy-Signature header.
If the signature is invalid, an error is thrown.
If the signature is valid, the next middleware is called.
*/
function validateRequest(req, res, next) {
  const secret = config.IVY_WEBHOOK_SIGNING_SECRET
  const data = req.body
  const expectedSignature = sign(data, secret)

  const signature = req.get('X-Ivy-Signature')

  if (signature !== expectedSignature) throw new Error('Invalid signature!')

  next()
}

/*
Parameter "data" is the request/response body.
The response is the X-IVY-SIGNATURE.
*/
function sign(data, secret) {
  const hmac = createHmac('sha256', secret)
  hmac.update(JSON.stringify(data))
  return hmac.digest('hex')
}