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

# Deposits API — track incoming payment deposits

> List and inspect NGN and crypto deposits received through your onramps. Simulate deposits in sandbox mode for integration testing.

A deposit is created automatically whenever funds arrive at one of your virtual accounts or onramps. You don't create deposits directly — instead, you query them to track the status of incoming payments as they move through the conversion and settlement pipeline. In sandbox mode, you can trigger simulated deposits yourself to test your integration end to end.

## Authentication

All endpoints require either a Bearer token or an API key.

```
Authorization: Bearer <access_token>
```

```
X-Api-Key: dubu_sk_live_...
```

***

## Deposit lifecycle

NGN deposits move through the following status sequence:

```
PENDING → COMPLETED
                  ↘ FAILED
                  ↘ FLAGGED
                  ↘ REVERSED
```

| Status      | Meaning                                       |
| ----------- | --------------------------------------------- |
| `PENDING`   | Funds received; FX conversion in progress.    |
| `COMPLETED` | Deposit fully settled and proceeds delivered. |
| `FAILED`    | Conversion or settlement failed.              |
| `FLAGGED`   | Deposit held for compliance review.           |
| `REVERSED`  | Funds returned to the sender.                 |

***

## List deposits

`GET https://api.dubupay.com/api/v1/payments/deposits`

Returns a paginated list of deposits. You can filter by type, status, associated onramp or offramp, and date range.

### Query parameters

<ParamField query="type" type="string">
  Filter by deposit type. One of `NGN_DEPOSIT` or `CRYPTO_DEPOSIT`.
</ParamField>

<ParamField query="status" type="string">
  Filter by status. One of `PENDING`, `COMPLETED`, `FAILED`, `FLAGGED`, `REVERSED`.
</ParamField>

<ParamField query="onramp_id" type="string">
  Filter deposits that arrived through a specific onramp.
</ParamField>

<ParamField query="offramp_id" type="string">
  Filter deposits associated with a specific offramp.
</ParamField>

<ParamField query="from" type="string">
  Start of the date range in ISO 8601 format with timezone offset (e.g., `2024-01-01T00:00:00+01:00`).
</ParamField>

<ParamField query="to" type="string">
  End of the date range in ISO 8601 format with timezone offset.
</ParamField>

<ParamField query="page" type="number">
  Page number (1-indexed).
</ParamField>

<ParamField query="per_page" type="number">
  Results per page. Up to 100.
</ParamField>

### Response

<ResponseField name="data" type="array">
  List of deposit objects.

  <Expandable title="deposit fields">
    <ResponseField name="id" type="string">
      Unique deposit ID.
    </ResponseField>

    <ResponseField name="type" type="string">
      `NGN_DEPOSIT` or `CRYPTO_DEPOSIT`.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Amount received as a decimal string.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code of the received amount (e.g., `NGN`).
    </ResponseField>

    <ResponseField name="status" type="string">
      Current deposit status. See lifecycle table above.
    </ResponseField>

    <ResponseField name="onramp_id" type="string">
      ID of the onramp that received this deposit.
    </ResponseField>

    <ResponseField name="customer" type="object">
      The customer associated with this deposit, if any.
    </ResponseField>

    <ResponseField name="virtual_account" type="object">
      The virtual account that received the funds.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the deposit was recorded.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of the last status change.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null}
curl "https://api.dubupay.com/api/v1/payments/deposits?status=COMPLETED&per_page=50" \
  -H "X-Api-Key: dubu_sk_live_..."
```

### Example — filter by date range

```bash theme={null}
curl "https://api.dubupay.com/api/v1/payments/deposits?from=2024-01-01T00:00:00%2B01:00&to=2024-01-31T23:59:59%2B01:00" \
  -H "X-Api-Key: dubu_sk_live_..."
```

***

## Get a deposit

`GET https://api.dubupay.com/api/v1/payments/deposits/:id`

Retrieves a single deposit by ID with full detail including settlement information.

### Path parameters

<ParamField path="id" type="string" required>
  The deposit ID.
</ParamField>

### Response

<ResponseField name="data" type="object">
  Full deposit object.

  <Expandable title="data fields">
    <ResponseField name="id" type="string">
      Unique deposit ID.
    </ResponseField>

    <ResponseField name="type" type="string">
      `NGN_DEPOSIT` or `CRYPTO_DEPOSIT`.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Received amount as a decimal string.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency of the received amount.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current deposit status.
    </ResponseField>

    <ResponseField name="onramp_id" type="string">
      ID of the receiving onramp.
    </ResponseField>

    <ResponseField name="customer" type="object">
      Associated customer object (id, email, name).
    </ResponseField>

    <ResponseField name="virtual_account" type="object">
      Virtual account that received the deposit (accountNumber, bankName).
    </ResponseField>

    <ResponseField name="settlement" type="object">
      Settlement details — asset received, amount, chain, destination address.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 last-updated timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null}
curl "https://api.dubupay.com/api/v1/payments/deposits/dep_01HXYZ" \
  -H "X-Api-Key: dubu_sk_live_..."
```

***

## Simulate a deposit (sandbox only)

`POST https://api.dubupay.com/api/v1/payments/sandbox/deposits`

Triggers a simulated NGN deposit on a given onramp. Only available in test/sandbox mode. Use this to test your webhook handlers and deposit processing logic without sending real bank transfers.

<Warning>
  This endpoint is only active when using a test API key (`dubu_sk_test_...`). Calling it with a live key returns an error.
</Warning>

### Request body

<ParamField body="onramp_id" type="string" required>
  The ID of the onramp to simulate the deposit against. The onramp must be in `ACTIVE` status.
</ParamField>

<ParamField body="should_flag" type="boolean">
  When set to `true`, the simulated deposit is created with a `FLAGGED` status to test your compliance-handling flows. Defaults to `false`.
</ParamField>

### Example — normal deposit

```bash theme={null}
curl -X POST https://api.dubupay.com/api/v1/payments/sandbox/deposits \
  -H "X-Api-Key: dubu_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "onramp_id": "onr_01HXYZ"
  }'
```

### Example — flagged deposit

```bash theme={null}
curl -X POST https://api.dubupay.com/api/v1/payments/sandbox/deposits \
  -H "X-Api-Key: dubu_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "onramp_id": "onr_01HXYZ",
    "should_flag": true
  }'
```