Deposits API — track incoming payment deposits

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

string

Filter by deposit type. One of NGN_DEPOSIT or CRYPTO_DEPOSIT.

string

Filter by status. One of PENDING, COMPLETED, FAILED, FLAGGED, REVERSED.

string

Filter deposits that arrived through a specific onramp.

string

Filter deposits associated with a specific offramp.

string

Start of the date range in ISO 8601 format with timezone offset (e.g., 2024-01-01T00:00:00+01:00).

string

End of the date range in ISO 8601 format with timezone offset.

number

Page number (1-indexed).

number

Results per page. Up to 100.

Response

array

List of deposit objects.

Show deposit fields

string

Unique deposit ID.

string

NGN_DEPOSIT or CRYPTO_DEPOSIT.

string

Amount received as a decimal string.

string

Currency code of the received amount (e.g., NGN).

string

Current deposit status. See lifecycle table above.

string

ID of the onramp that received this deposit.

object

The customer associated with this deposit, if any.

object

The virtual account that received the funds.

string

ISO 8601 timestamp of when the deposit was recorded.

string

ISO 8601 timestamp of the last status change.

Example

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

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

string

required

The deposit ID.

Response

object

Full deposit object.

Show data fields

string

Unique deposit ID.

string

NGN_DEPOSIT or CRYPTO_DEPOSIT.

string

Received amount as a decimal string.

string

Currency of the received amount.

string

Current deposit status.

string

ID of the receiving onramp.

object

Associated customer object (id, email, name).

object

Virtual account that received the deposit (accountNumber, bankName).

object

Settlement details — asset received, amount, chain, destination address.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

Example

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.

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

Request body

string

required

The ID of the onramp to simulate the deposit against. The onramp must be in ACTIVE status.

boolean

When set to true, the simulated deposit is created with a FLAGGED status to test your compliance-handling flows. Defaults to false.

Example — normal deposit

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

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
  }'

Overview

Auth

Payments

Trading

Commerce

Webhooks

Deposits API — track incoming payment deposits

Authentication

Deposit lifecycle

List deposits

Query parameters

Response

Example

Example — filter by date range

Get a deposit

Path parameters

Response

Example

Simulate a deposit (sandbox only)

Request body

Example — normal deposit

Example — flagged deposit

​Authentication

​Deposit lifecycle

​List deposits

​Query parameters

​Response

​Example

​Example — filter by date range

​Get a deposit

​Path parameters

​Response

​Example

​Simulate a deposit (sandbox only)

​Request body

​Example — normal deposit

​Example — flagged deposit

Authentication

Deposit lifecycle

List deposits

Query parameters

Response

Example

Example — filter by date range

Get a deposit

Path parameters

Response

Example

Simulate a deposit (sandbox only)

Request body

Example — normal deposit

Example — flagged deposit