​
Overview

Deposits allow you to accept incoming transfers directly to your dedicated Ivy IBAN without requiring a Checkout Session or Order. With Deposit enabled, your account accepts all incoming transfers; you decide how to handle them.

​
Use Cases

Choose whether you want to have depoists as a way to handle mis-matched Manual Bank Transfers, or receive all payments as Deposits.

​
Option 1: Order‑based Deposits

Keep the current order flow with more control. Continue using orders and checkout sessions. If a customer enters the wrong amount or reference, the payment appears as an unmatched deposit. You can reconcile it to the corresponding order in your system or return the funds via API or dashboard. Integration: Create an order via /order/create and display the IBAN, BIC and reference to the customer. If the transfer matches the order amount and reference, Ivy reconciles it automatically. If there is a mismatch, the payment is recorded as a deposit.

​
Option 2: Direct IBAN Deposits

Simplified IBAN flow. Show your Ivy IBAN directly in your payment instructions. Customers can transfer funds without a reference. Each incoming transfer triggers a webhook event; you reconcile the deposit yourself. Integration: Expose your Ivy IBAN to customers without creating an order. For each incoming transfer, Ivy generates a deposit.received webhook event.
By default, Ivy automatically returns unmatched payments to the sender. To enable deposits (which prevents automatic returns and gives you control), contact our support team.

​
Integration Flow

​
1. Subscribe to Webhook Events

Ivy’s webhook system notifies you whenever a deposit or return changes state. Create a webhook subscription for the following events:
  • deposit.received – triggered when a new deposit arrives
  • return.initiated – triggered when you initiate a return via the API
  • return.succeeded – triggered when the return is processed successfully
  • return.failed – triggered if the return cannot be completed
  • return.returned – triggered when funds from a return are credited back to the sender
Each webhook notification contains a unique ID, event type and payload with deposit or return details. Validate the signature using your webhook signing secret. Example deposit webhook payload: 
{
  "id": "evt_deposit_123",
  "type": "deposit.received",
  "payload": {
    "depositId": "f60a15ef-78e6-4355-96f2-351f04931d20",
    "value": {
      "currency": "EUR",
      "amount": "100"
    },
    "bankStatementReference": "My Purchase",
    "receivedAt": "2025-08-07T12:33:56Z"
  },
  "date": "2025-08-07T12:34:56Z"
}

​
2. Retrieve a Deposit

Use the /deposit/retrieve endpoint to fetch the details of a specific deposit. Request: 
GET https://api.getivy.de/api/service/deposit/retrieve?id=dep_abc123
ParameterTypeRequiredDescription
idstringYesThe deposit ID you want to retrieve
Example response: 
{
  "id": "dep_abc123",
  "payer": {
    "iban": "DE44888888888888888888",
    "accountHolderName": "John Doe"
  },
  "payee": {
    "iban": "DE89123456781234567890",
    "accountHolderName": "Your Company"
  },
  "amount": 100.00,
  "currency": "EUR",
  "bankStatementReference": "optional reference",
  "receivedAt": "2025-08-07T12:34:56Z",
  "rail": "sepa_instant",
  "status": "received",
  "returns": []
}

​
3. Create a Return

If you decide to send the funds back to the sender, create a return via the /return/create endpoint. A return links to the original deposit and triggers the return.initiated and return.succeeded (or return.failed) webhook events. Request: 
POST https://api.getivy.de/api/service/return/create
Content-Type: application/json
X-Ivy-Api-Key: YOUR_API_KEY

{
  "depositId": "dep_abc123"
}
Response: 
{
  "id": "ret_xyz789",
  "depositId": "dep_abc123",
  "amount": 100.00,
  "currency": "EUR",
  "createdAt": "2025-08-07T14:00:00Z",
  "status": "initiated"
}

​
4. Retrieve a Return

Retrieve return details via the /return/retrieve endpoint. You can poll this endpoint to confirm whether the return has succeeded. Request: 
GET https://api.getivy.de/api/service/return/retrieve?id=ret_xyz789
ParameterTypeRequiredDescription
idstringYesThe return ID you want to retrieve
Example response: 
{
  "id": "ret_xyz789",
  "depositId": "dep_abc123",
  "amount": 100.00,
  "currency": "EUR",
  "createdAt": "2025-08-07T14:00:00Z",
  "succeededAt": "2025-08-07T15:10:00Z",
  "failedAt": null,
  "status": "succeeded"
}

​
Merchant Dashboard

Your Ivy Dashboard now includes two tables for incoming payments:
  • Payin Table – lists payments successfully matched to an order (correct amount and reference provided). Order statuses transition from authorised to paid when a payment is reconciled.
  • Deposits Table – lists payments that could not be matched automatically. From here you can return unmatched deposits.

​
FAQ

With manual bank transfer, mismatched payments are automatically rejected and returned. Deposits prevent automatic returns: the funds are accepted and recorded as an unmatched deposit. You can decide whether to match or refund.
Yes. When using the order‑based flow, provide the IBAN, BIC and unique reference to the customer. Deposits simply give you control over mismatched transfers.
Deposits immediately increase your available balance. You can retrieve balances through the /balance/retrieve endpoint or view them in the Settlements section of the Dashboard.
Currently, you are only able to initiate full returns. To partially return funds, you’ll have to use the payout API.