Deposits

Accept payments from your users via crypto (NOWPayments) or fiat (Chapa). Phoenix Pay automatically selects the appropriate PSP based on your tenant's configuration and the requested currency.

Create Deposit

POST /api/deposits

Creates a new deposit and returns payment details from the selected PSP. The response includes either a pay_address (for crypto) or checkout_url (for fiat redirect flow) that you present to your user.

Request Body

Field	Type	Required	Description
`reference_id`	string	Yes	Your unique identifier for this payment. Must be unique within your tenant. Use this to correlate with your own system (e.g., order ID).
`amount`	string	Yes	Payment amount as a decimal string (e.g., `"50.00"`, `"0.001"`).
`currency`	string	Yes	Currency code. Must match a currency supported by one of your configured PSPs (e.g., `USDT`, `BTC`, `ETH`, `ETB`).

Create a crypto deposit

curl -X POST https://pay.phoenixverse.io/api/deposits \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "order-12345",
    "amount": "50.00",
    "currency": "USDT"
  }'

Response

201 Created

{
  "id": "01912e4a-7b3c-7def-8a90-1234567890ab",
  "reference_id": "order-12345",
  "type": "deposit",
  "status": "awaiting_payment",
  "psp": "nowpayments",
  "requested_amount": "50.00",
  "received_amount": null,
  "currency": "USDT",
  "pay_currency": "usdttrc20",
  "pay_amount": "50.00",
  "checkout_url": null,
  "pay_address": "TXrk4d5x7Bj3e6g7Y8Zw9AbCdEf1234567",
  "expires_at": "2026-03-11T14:30:00Z",
  "inserted_at": "2026-03-11T12:30:00Z",
  "updated_at": "2026-03-11T12:30:00Z"
}

For crypto deposits, display the pay_address and pay_amount to your user. They need to send exactly pay_amount in pay_currency to the pay_address before expires_at.

201 Created

{
  "id": "01912e4b-8c4d-7def-9b01-2345678901bc",
  "reference_id": "order-12346",
  "type": "deposit",
  "status": "awaiting_payment",
  "psp": "chapa",
  "requested_amount": "1000.00",
  "received_amount": null,
  "currency": "ETB",
  "pay_currency": null,
  "pay_amount": null,
  "checkout_url": "https://checkout.chapa.co/checkout/payment/abc123xyz",
  "pay_address": null,
  "expires_at": "2026-03-11T13:30:00Z",
  "inserted_at": "2026-03-11T12:30:00Z",
  "updated_at": "2026-03-11T12:30:00Z"
}

For fiat deposits, redirect your user to checkout_url where they will complete the payment through Chapa's hosted checkout page.

Response Fields

Field	Type	Description
`id`	string (UUID v7)	Unique payment identifier
`reference_id`	string	Your reference ID from the request
`type`	string	Always `"deposit"` for deposits
`status`	string	Initial status, typically `"awaiting_payment"`
`psp`	string	The PSP that was selected (`"nowpayments"` or `"chapa"`)
`requested_amount`	string	The amount you requested
`received_amount`	string or null	Amount received so far (null until payment is detected)
`currency`	string	The requested currency code
`pay_currency`	string or null	Specific currency the user should pay in (crypto only, e.g., `"usdttrc20"`)
`pay_amount`	string or null	Exact amount the user should send (crypto only)
`checkout_url`	string or null	Redirect URL for fiat payments
`pay_address`	string or null	Crypto address to send payment to
`expires_at`	string (ISO 8601) or null	When the payment window expires
`inserted_at`	string (ISO 8601)	When the record was created
`updated_at`	string (ISO 8601)	When the record was last updated

Errors

Status	Error	Cause
`400`	`"missing required parameter: reference_id"`	A required field is missing or empty
`422`	`"no_psp_configured"`	No PSP is configured for the requested currency in your tenant
`422`	`"has already been taken"`	The `reference_id` already exists for your tenant

Get Deposit

GET /api/deposits/:id

Retrieve a single deposit by its Phoenix Pay UUID.

Get deposit by ID

curl https://pay.phoenixverse.io/api/deposits/01912e4a-7b3c-7def-8a90-1234567890ab \
  -H "Authorization: Bearer <token>"

200 OK

{
  "id": "01912e4a-7b3c-7def-8a90-1234567890ab",
  "reference_id": "order-12345",
  "type": "deposit",
  "status": "settled",
  "psp": "nowpayments",
  "requested_amount": "50.00",
  "received_amount": "50.00",
  "currency": "USDT",
  "pay_currency": "usdttrc20",
  "pay_amount": "50.00",
  "checkout_url": null,
  "pay_address": "TXrk4d5x7Bj3e6g7Y8Zw9AbCdEf1234567",
  "expires_at": "2026-03-11T14:30:00Z",
  "inserted_at": "2026-03-11T12:30:00Z",
  "updated_at": "2026-03-11T12:45:00Z"
}

Deposits are scoped to your tenant. You can only retrieve deposits created by your organization. Attempting to access another tenant's deposit returns 404.

Errors

Status	Error	Cause
`404`	`"not_found"`	No deposit with this ID exists for your tenant

Get Deposit by Reference

GET /api/deposits/ref/:reference_id

Retrieve a deposit using your original reference_id. This is useful when you need to look up a payment using your own system's identifier.

Get deposit by reference ID

curl https://pay.phoenixverse.io/api/deposits/ref/order-12345 \
  -H "Authorization: Bearer <token>"

The response format is identical to Get Deposit.

Errors

Status	Error	Cause
`404`	`"not_found"`	No deposit with this reference ID exists for your tenant

List Deposits

GET /api/deposits

Retrieve a paginated list of deposits for your tenant. Supports filtering by status, currency, date range, and text search.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`25`	Results per page (max 100)
`status`	string	-	Filter by status (e.g., `settled`, `awaiting_payment`, `failed`)
`currency`	string	-	Filter by currency code (e.g., `USDT`, `ETB`)
`from`	string (date)	-	Filter payments created on or after this date (ISO 8601 date, e.g., `2026-03-01`)
`to`	string (date)	-	Filter payments created on or before this date (ISO 8601 date, e.g., `2026-03-11`)
`search`	string	-	Search by reference ID (partial match)

The from and to parameters must both be provided for date filtering to take effect. Providing only one will be ignored.

Examples

List all deposits

curl "https://pay.phoenixverse.io/api/deposits?page=1&limit=10" \
  -H "Authorization: Bearer <token>"

List settled deposits

curl "https://pay.phoenixverse.io/api/deposits?status=settled" \
  -H "Authorization: Bearer <token>"

List deposits in date range

curl "https://pay.phoenixverse.io/api/deposits?from=2026-03-01&to=2026-03-11" \
  -H "Authorization: Bearer <token>"

Search by reference ID

curl "https://pay.phoenixverse.io/api/deposits?search=order-123" \
  -H "Authorization: Bearer <token>"

Response

200 OK

{
  "data": [
    {
      "id": "01912e4a-7b3c-7def-8a90-1234567890ab",
      "reference_id": "order-12345",
      "type": "deposit",
      "status": "settled",
      "psp": "nowpayments",
      "requested_amount": "50.00",
      "received_amount": "50.00",
      "currency": "USDT",
      "pay_currency": "usdttrc20",
      "pay_amount": "50.00",
      "checkout_url": null,
      "pay_address": "TXrk4d5x7Bj3e6g7Y8Zw...",
      "expires_at": "2026-03-11T14:30:00Z",
      "inserted_at": "2026-03-11T12:30:00Z",
      "updated_at": "2026-03-11T12:45:00Z"
    },
    {
      "id": "01912e4b-8c4d-7def-9b01-2345678901bc",
      "reference_id": "order-12346",
      "type": "deposit",
      "status": "awaiting_payment",
      "psp": "chapa",
      "requested_amount": "1000.00",
      "received_amount": null,
      "currency": "ETB",
      "pay_currency": null,
      "pay_amount": null,
      "checkout_url": "https://checkout.chapa.co/checkout/payment/abc123xyz",
      "pay_address": null,
      "expires_at": "2026-03-11T13:30:00Z",
      "inserted_at": "2026-03-11T12:30:00Z",
      "updated_at": "2026-03-11T12:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Results are sorted by creation date, newest first.

Deposits

On this page