Deposits

For real-time notifications when a deposit arrives, use Webhooks. 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.

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

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

Response

{
  "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.

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

Example

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

Response

{
  "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:

{
  "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.

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

Example

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

Response — deposit found and successful

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

Response — deposit not found

{
  "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:

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.
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.
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 — receive real-time deposit notifications
Collections — set up virtual accounts to receive payments
Customers — manage customer profiles linked to virtual accounts