---
updatedAt: 2026-06-05T16:04:58.000Z
agentTools:
  projectIndex: https://capera.readme.io/llms.txt
---

# Deposits

The Deposits API gives you a queryable history of all money received into your business account — from dynamic virtual accounts, static virtual accounts, and any other inflow source.  > <br />

> For real-time notifications when a deposit arrives, use [Webhooks](../../docs/webhooks.md). The Deposits API is for querying history and validating specific transactions.

***

## List deposits

Returns a paginated list of all deposits for your business, ordered by most recent first.

```http
GET /v1/deposits
Authorization: Bearer <api-key>
```

**Query parameters**

| Parameter | Type    | Default | Description                |
| --------- | ------- | ------- | -------------------------- |
| `page`    | integer | `1`     | Page number                |
| `limit`   | integer | `20`    | Results per page (max 100) |

**Example**

```bash
curl "https://api.withcapera.com/b2b/v1/deposits?page=1&limit=20" \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

**Response**

```json
{
  "success": true,
  "data": {
    "deposits": [
      {
        "id": "dep_abc123",
        "amount": 500000,
        "reference": "CAPERA-DEP-123",
        "status": "SUCCESSFUL",
        "currency": "NGN",
        "senderAccountName": "Jane Doe",
        "senderAccountNumber": "9876543210",
        "senderBankName": "GTBank",
        "recipientAccountName": "Your Business",
        "recipientAccountNumber": "1234567890",
        "recipientBankName": "Providus Bank",
        "narration": "Payment for invoice",
        "fee": 50,
        "createdAt": "2024-01-15T12:00:00Z",
        "updatedAt": "2024-01-15T12:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 87,
      "totalPage": 5,
      "hasNext": true,
      "hasPrev": false
    }
  }
}
```

**Deposit object fields**

| Field                    | Type    | Description                                           |
| ------------------------ | ------- | ----------------------------------------------------- |
| `id`                     | string  | Unique deposit identifier                             |
| `amount`                 | integer | Deposit amount in kobo                                |
| `reference`              | string  | Capera-assigned reference for this deposit            |
| `status`                 | string  | Deposit status — see statuses below                   |
| `currency`               | string  | Currency code (`NGN`)                                 |
| `senderAccountName`      | string  | Name on the sending account                           |
| `senderAccountNumber`    | string  | Sending account number                                |
| `senderBankName`         | string  | Sending bank name                                     |
| `recipientAccountName`   | string  | Name on your virtual account                          |
| `recipientAccountNumber` | string  | Your virtual account number that received the deposit |
| `recipientBankName`      | string  | Bank of the virtual account                           |
| `narration`              | string  | Transfer narration from the sender                    |
| `fee`                    | integer | Collection fee deducted in kobo                       |
| `createdAt`              | string  | ISO 8601 timestamp when the deposit was recorded      |
| `updatedAt`              | string  | ISO 8601 timestamp of the last status update          |

**Deposit statuses**

| Status       | Meaning                                     |
| ------------ | ------------------------------------------- |
| `SUCCESSFUL` | Deposit settled — funds are in your balance |
| `PENDING`    | Deposit received but not yet settled        |
| `FAILED`     | Deposit processing failed                   |

***

## Get a deposit by reference

Retrieve a specific deposit using its Capera reference.

```http
GET /v1/deposits/{reference}
Authorization: Bearer <api-key>
```

**Example**

```bash
curl https://api.withcapera.com/b2b/v1/deposits/CAPERA-DEP-123 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

**Response**

```json
{
  "success": true,
  "data": {
    "id": "dep_abc123",
    "amount": 500000,
    "reference": "CAPERA-DEP-123",
    "status": "SUCCESSFUL",
    "currency": "NGN",
    "senderAccountName": "Jane Doe",
    "senderAccountNumber": "9876543210",
    "senderBankName": "GTBank",
    "recipientAccountName": "Your Business",
    "recipientAccountNumber": "1234567890",
    "recipientBankName": "Providus Bank",
    "narration": "Payment for invoice",
    "fee": 50,
    "createdAt": "2024-01-15T12:00:00Z",
    "updatedAt": "2024-01-15T12:00:00Z"
  }
}
```

**Error response** — if the reference does not exist:

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Deposit not found"
  }
}
```

***

## Validate a deposit

Checks whether a deposit with the given reference exists and whether it has settled successfully. Useful for confirming payment before fulfilling an order, without needing to handle the full deposit object.

```http
GET /v1/deposits/validate/{reference}
Authorization: Bearer <api-key>
```

**Example**

```bash
curl https://api.withcapera.com/b2b/v1/deposits/validate/CAPERA-DEP-123 \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

**Response — deposit found and successful**

```json
{
  "success": true,
  "data": {
    "exists": true,
    "reference": "CAPERA-DEP-123",
    "status": "SUCCESSFUL",
    "amount": 500000,
    "currency": "NGN",
    "valid": true
  }
}
```

**Response — deposit not found**

```json
{
  "success": true,
  "data": {
    "exists": false,
    "reference": "CAPERA-DEP-123",
    "message": "Deposit not found"
  }
}
```

The `valid` field is `true` only when the deposit exists and has a `SUCCESSFUL` status. Use this field as the single signal for whether to fulfil an order or unlock a feature.

***

## Reconciliation workflow

A common pattern for matching incoming deposits to your own records:

1. **On webhook receipt** — when you receive a `deposit.success` or `customer.deposit.success` event, extract the `reference` from the payload and match it against your pending orders.

2. **On doubt** — if a webhook was missed or you are unsure of a payment's status, call `GET /v1/deposits/validate/{reference}` and check `valid`.

3. **For reporting** — use `GET /v1/deposits` with pagination to pull deposit history for reconciliation runs or dashboard display.

***

## Error handling

| Error                   | Description                                                  |
| ----------------------- | ------------------------------------------------------------ |
| `Deposit not found`     | The `reference` does not match any deposit for your business |
| `Reference is required` | The `reference` path parameter was empty                     |
| `Session not found`     | Missing or invalid API key                                   |

***

## What's next

* [Webhooks](../../docs/webhooks.md) — receive real-time deposit notifications
* [Collections](./collections.md) — set up virtual accounts to receive payments
* [Customers](./customers.md) — manage customer profiles linked to virtual accounts