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

Send 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"
}
FieldRule
amountGreater than 0, at most two decimals, major units
currencyUSD, AED, EUR or GBP. Must match the receiving account
accountIdExactly one of accountId or receivingIban. Your accounts.id. Active, yours, and inside your read Account scope
receivingIbanThat account's vIBAN. Spaces and letter case are ignored. An IBAN that matches two of your accounts is refused as ambiguous
customerWritten out (customerReference, fullName, iban, optional swiftCode) or by id (customerId, and an optional reference)
externalReferenceOptional, up to 140 characters. Informational
expiresAtOptional. Defaults to 15 days ahead. Must be in the future and at most 30 days ahead, else 400 INVALID_EXPIRY
idempotencyKeyRequired. 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

StatusMeaning
openWaiting. It stays open until matchableUntil, even after expiresAt
matchedA payment of exactly the declared amount arrived on the named vIBAN
matched_amount_mismatchA different amount matched and was credited as it arrived
expiredNothing 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 before expiresAt;
  • 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.


Did this page help you?