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

type

string

Filter by deposit type. One of NGN_DEPOSIT or CRYPTO_DEPOSIT.

status

string

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

onramp_id

string

Filter deposits that arrived through a specific onramp.

offramp_id

string

Filter deposits associated with a specific offramp.

from

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.

page

number

Page number (1-indexed).

per_page

number

Results per page. Up to 100.

Response

data

array

List of deposit objects.

Show deposit fields

string

Unique deposit ID.

type

string

NGN_DEPOSIT or CRYPTO_DEPOSIT.

amount

string

Amount received as a decimal string.

currency

string

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

status

string

Current deposit status. See lifecycle table above.

onramp_id

string

ID of the onramp that received this deposit.

customer

object

The customer associated with this deposit, if any.

virtual_account

object

The virtual account that received the funds.

created_at

string

ISO 8601 timestamp of when the deposit was recorded.

updated_at

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

data

object

Full deposit object.

Show data fields

string

Unique deposit ID.

type

string

NGN_DEPOSIT or CRYPTO_DEPOSIT.

amount

string

Received amount as a decimal string.

currency

string

Currency of the received amount.

status

string

Current deposit status.

onramp_id

string

ID of the receiving onramp.

customer

object

Associated customer object (id, email, name).

virtual_account

object

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

settlement

object

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

created_at

string

ISO 8601 creation timestamp.

updated_at

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

onramp_id

string

required

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

should_flag

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