> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deposits

> The full deposit chain: fetch the receiving virtual account, have the customer wire the funds, get notified on arrival and reconcile the deposit records — deposit-info, the BANK_TRANSFER_INFO webhook and deposit-records.

## 📄 Guide

The funding side has one principle: fund first, spend second. Both the company pool and dedicated-balance cards are funded by the customer wiring money to their own receiving virtual account (VA): the company-level VA is created at onboarding, a card-level VA is opened per card on demand. The funding-owner concept is in [Holders and the funding model](../basic-concepts/identity-and-funding); the end-to-end funding picture is in [Funding · Overview](./funding-and-reconciliation).

The three deposit steps:

| Step                           | Action                                                     | Endpoint / event                          |
| ------------------------------ | ---------------------------------------------------------- | ----------------------------------------- |
| ① Get the receiving account    | Fetch the receiving VA details for that owner and currency | `GET /open-api-corp/fund/v1/deposit-info` |
| ② The customer wires the funds | The customer transfers to the VA using those details       | Bank-side action, no API                  |
| ③ Arrival notification         | DCS pushes a webhook when the deposit arrives              | `BANK_TRANSFER_INFO`                      |

Once arrived, the funds land on the owner's balance (queries and onward transfers are in [Balances and Transfers](./balances-and-transfers)); for day-to-day reconciliation pull the deposit history with `deposit-records` and match it against bank advice.

## Get the receiving account

`GET /open-api-corp/fund/v1/deposit-info` returns the receiving account (VA) details for depositing funds, for the customer to wire against.

**Request parameters**

| Field         | Type   | Required | Description                |
| ------------- | ------ | -------- | -------------------------- |
| `subjectType` | String | Yes      | `ORGANIZATION` / `CARD`    |
| `subjectId`   | String | Yes      | ≤20; company ID or card ID |
| `currency`    | String | Yes      | `USD` / `HKD`              |

**Response data**

| Field                | Type   | Description                                                   |
| -------------------- | ------ | ------------------------------------------------------------- |
| `currency`           | String | `USD` / `HKD`                                                 |
| `payeeAccountNumber` | String | Receiving virtual account number                              |
| `payeeBankCode`      | String | Bank code, `SCB` / `DBS`                                      |
| `payeeBankName`      | String | Bank name                                                     |
| `payeeAccountName`   | String | Receiving account name (beneficiary account name)             |
| `payeeSwiftCode`     | String | SWIFT/BIC (required for cross-border wires)                   |
| `payeeBankAddress`   | String | Bank address                                                  |
| `payeeAddress`       | String | Recipient address                                             |
| `remark`             | String | Required transfer reference (e.g. quote the `organizationId`) |

**Request example**

```http theme={null}
GET /open-api-corp/fund/v1/deposit-info?subjectType=COMPANY&subjectId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&currency=USD
```

**Response example**

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "currency": "USD",
    "payeeAccountNumber": "74012345678901",
    "payeeBankCode": "SCB",
    "payeeBankName": "Standard Chartered Bank (Hong Kong) Limited",
    "payeeAccountName": "EXAMPLE COMPANY LIMITED",
    "payeeSwiftCode": "SCBLHKHH",
    "payeeBankAddress": "4-4A Des Voeux Road Central, Hong Kong",
    "payeeAddress": "Unit 1001, 10/F, Tower 1, Harbour City, Tsim Sha Tsui, Hong Kong",
    "remark": "Quote organizationId e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f in the transfer reference"
  }
}
```

**Error codes**

| Code              | Description                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `SUBJECT_INVALID` | The company / card does not exist or is invalid, or the owner has no VA bound for that currency |

<Tip>
  Make sure the paying customer fills in the transfer reference exactly as `remark` requires; for cross-border wires, hand the customer the `payeeSwiftCode` together with the bank and recipient addresses.
</Tip>

## Arrival notification: BANK\_TRANSFER\_INFO

When a deposit arrives, DCS pushes the webhook event `BANK_TRANSFER_INFO`; success and failure are distinguished by `status` (`SUCCESS` means success). Payload example:

```json theme={null}
{
  "webhookId": "7800000000000000951", "webhookType": "BANK_TRANSFER_INFO",
  "businessId": "5185740066240791001", "notificationTime": "2026-08-25T02:30:00Z",
  "data": { "depositId": "DEP20260731000000455", "amount": "20000.00", "currency": "USD",
    "payeeAccountNumber": "8613300012345678", "payerName": "EXAMPLE HOLDINGS PTE LTD",
    "payerAccountNumber": "1234567890", "payerBankCode": "003",
    "referenceCode": "REF20260731000455", "status": "SUCCESS",
    "errorCode": null, "errorMessage": null }
}
```

`data` fields:

| Field                 | Description                             |
| --------------------- | --------------------------------------- |
| `depositId`           | Deposit record ID                       |
| `amount` / `currency` | Deposit amount and currency             |
| `payeeAccountNumber`  | Deposit account number                  |
| `payerName`           | Sender account name                     |
| `status`              | Arrival status; `SUCCESS` means success |
| `detail`              | Related ledger detail reference         |

The outer layer is the site-wide webhook envelope: `webhookId`, `webhookType`, `businessId` (the `depositId` for this event) and `notificationTime`.

<Warning>
  Judge success or failure by `status` — receiving the event itself does not mean the deposit succeeded.
</Warning>

## Query deposit records

`GET /open-api-corp/fund/v1/deposit-records` returns the deposit (VA inbound) records, paginated, for reconciliation.

**Request parameters**

| Field         | Type    | Required | Description                                          |
| ------------- | ------- | -------- | ---------------------------------------------------- |
| `subjectType` | String  | No       | `ORGANIZATION` / `CARD` (paired with `subjectId`)    |
| `subjectId`   | String  | No       | ≤20; company ID or card ID                           |
| `currency`    | String  | No       | `USD` / `HKD`                                        |
| `startTime`   | String  | No       | ≤32; range start, ISO-8601 (filters by arrival time) |
| `endTime`     | String  | No       | ≤32; range end, ISO-8601                             |
| `page`        | Integer | No       | From 1, default 1                                    |
| `pageSize`    | Integer | No       | 1\~100, default 20                                   |

**Response data** is a page object: `page` (current page), `pageSize` (page size), `total` (total count) and `result` (the deposit records). Fields of each record:

| Field                       | Description                                                              |
| --------------------------- | ------------------------------------------------------------------------ |
| `depositId`                 | Deposit record ID                                                        |
| `subjectType` / `subjectId` | Funding owner the deposit belongs to: `ORGANIZATION` / `CARD` and its ID |
| `payeeAccountNumber`        | The receiving virtual account number credited                            |
| `amount` / `currency`       | Deposit amount and currency                                              |
| `status`                    | Arrival status: `SUCCESS` (arrived) / `PENDING` (processing)             |
| `payerName`                 | Sender account name                                                      |
| `payerAccountNumber`        | Sender account number                                                    |
| `payerBankCode`             | Sender bank                                                              |
| `completeTime`              | Arrival time, ISO-8601 (what `startTime` / `endTime` filter on)          |

**Request example**

```http theme={null}
GET /open-api-corp/fund/v1/deposit-records?subjectType=COMPANY&subjectId=e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f&currency=USD&startTime=2026-08-01T00:00:00&endTime=2026-08-19T23:59:59&page=1&pageSize=20
```

**Response example**

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "page": 1,
    "pageSize": 20,
    "total": 2,
    "result": [
      {
        "depositId": "5185740066240790533",
        "subjectType": "ORGANIZATION",
        "subjectId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
        "payeeAccountNumber": "74012345678901",
        "amount": "1000.00",
        "currency": "USD",
        "status": "SUCCESS",
        "payerName": "EXAMPLE COMPANY LIMITED",
        "payerAccountNumber": "12345678901234",
        "payerBankCode": "HSBC",
        "completeTime": "2026-08-18T15:20:00Z"
      },
      {
        "depositId": "5185740066240790534",
        "subjectType": "ORGANIZATION",
        "subjectId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
        "payeeAccountNumber": "74012345678901",
        "amount": "500.00",
        "currency": "USD",
        "status": "PENDING",
        "payerName": "EXAMPLE COMPANY LIMITED",
        "payerAccountNumber": "12345678901234",
        "payerBankCode": "HSBC",
        "completeTime": "2026-08-19T10:30:00Z"
      }
    ]
  }
}
```

<Note>
  On statements, deposits count into the repayments / top-ups total (`totalRepaymentAmount`, transactions of type `REPAYMENT`); the statement conventions are in [Statements and Transactions](./statements-and-transactions). Configuring the pool low-balance alert (`LOW_BALANCE`) is covered in [Managing companies](./managing-companies).
</Note>

## Next steps

* Query balances after arrival and move funds between the company pool and dedicated-balance cards: [Balances and Transfers](./balances-and-transfers)
* How deposits show up on statements and in transaction records, and how they offset the amount due: [Statements and Transactions](./statements-and-transactions)