Skip to main content

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.

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
StatusMeaning
PENDINGFunds received; FX conversion in progress.
COMPLETEDDeposit fully settled and proceeds delivered.
FAILEDConversion or settlement failed.
FLAGGEDDeposit held for compliance review.
REVERSEDFunds 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).
​
to
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.

​
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

​
id
string
required
The deposit ID.

​
Response

​
data
object
Full deposit object.

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