Authentication
The Ivy API uses API Keys to authenticate requests. You can view and manage your API Key in the Ivy Dashboard.
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.
Type | Base URL | When to Use | How to Use |
---|---|---|---|
Sandbox | https://api.sand.getivy.de | Use 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. |
Production | https://api.getivy.de | Use 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
- Go to your Ivy Dashboard
- 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:
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