Deposit declarations
A declaration says a customer will pay this amount, from this IBAN, in this currency, onto one of your vIBANs, before a date. When the payment arrives it is credited as usual, then matched to the declaration. Declaring is optional. A payment with no declaration is credited and reported unmatched.
Declaring needs create Deposit. Reading needs read Deposit.
POST /v1/deposits
POST /v1/depositsSend exactly one of accountId or receivingIban, and name the payer in customer.
By account id, payer written out:
{
"amount": 500.00,
"currency": "AED",
"accountId": "6f1c8a2e-0000-4000-8000-000000000001",
"customer": {
"customerReference": "CRM-42",
"fullName": "Layla Haddad",
"iban": "AE07 0331 2345 6789 0123 456",
"swiftCode": "BOMLAEAD"
},
"externalReference": "INV-2026-0042",
"expiresAt": "2026-11-09T12:00:00Z",
"idempotencyKey": "dep-inv-2026-0042"
}By the account's vIBAN, and a customer you already saved:
{
"amount": 500.00,
"currency": "AED",
"receivingIban": "AE070331234567890123456",
"customer": { "customerId": "00000000-0000-4000-8000-0000000000b1" },
"idempotencyKey": "dep-inv-2026-0043"
}| Field | Rule |
|---|---|
amount | Greater than 0, at most two decimals, major units |
currency | USD, AED, EUR or GBP. Must match the receiving account |
accountId | Exactly one of accountId or receivingIban. Your accounts.id. Active, yours, and inside your read Account scope |
receivingIban | That account's vIBAN. Spaces and letter case are ignored. An IBAN that matches two of your accounts is refused as ambiguous |
customer | Written out (customerReference, fullName, iban, optional swiftCode) or by id (customerId, and an optional reference) |
externalReference | Optional, up to 140 characters. Informational |
expiresAt | Optional. Defaults to 15 days ahead. Must be in the future and at most 30 days ahead, else 400 INVALID_EXPIRY |
idempotencyKey | Required. Same key and same content, including the same receiving account, returns the original with 200. Different content, including a different account, is 409 IDEMPOTENCY_KEY_REUSED |
201 Created returns depositId, status: "open", expiresAt, matchableUntil, accountId, accountIban (left out when your account read hides iban) and customer.
A missing, inactive or wrong-currency account is 400. An account outside your scope is 403 CONDITION_FAILED. A refused declaration leaves nothing behind.
Reads
GET /v1/deposits is newest first, paged. Response: { "data": [Declaration], "meta": { "limit", "offset", "total" } }. total counts the rows your credential may see. limit defaults to 10 (maximum 100). Filter with status (open, matched, matched_amount_mismatch, expired), customerReference, customerId, createdFrom and createdTo.
GET /v1/deposits/:id returns one declaration. Another merchant's id, an unknown id, and an id outside a scoped credential's currency limit are 404.
A list or get includes accountId. accountIban is the receiving vIBAN.
Statuses
| Status | Meaning |
|---|---|
open | Waiting. It stays open until matchableUntil, even after expiresAt |
matched | A payment of exactly the declared amount arrived on the named vIBAN |
matched_amount_mismatch | A different amount matched and was credited as it arrived |
expired | Nothing matched before matchableUntil (expiryReason: "expired"), or the customer was rebound or deleted ("rebound", "deleted") |
How a payment is matched
A payment matches when all of these hold:
- it arrives on the vIBAN the declaration named (
accountId); - the remitter IBAN, normalised, is the declaration's IBAN, and the currency is the same;
- the declaration is
open, was created no later than five minutes after the payment's timestamp, and the payment's timestamp is beforeexpiresAt; - the payment is booked before
matchableUntil; - the declaration's reference is still the customer's, and the customer is still active.
When several qualify, the one with exactly the payment's amount goes first, then the oldest. A payment that lands on a different vIBAN of yours is credited, reported unmatched, and leaves the declaration open. Local-rail payments have no remitter IBAN, so they are unmatched.
Matching never holds up or undoes a credit. A short payment closes that declaration; a later payment takes the next open one. Instalments are not added together.
matchableUntil is expiresAt plus a grace period of at least 49 hours with today's settings, fixed when the declaration is created.
While the declaration is open it also appears on GET /v1/transactions as a pending incoming line, for a credential that may read Deposit.
A matched or short payment is reported on transaction.incoming (matchStatus, depositId, customer). deposit.expired is the only deposit event. See Webhooks.
Updated 3 days ago
