Skip to main content

Wallet

4 API calls in this section.

Get Wallet Dashboard​

Customer Portal / Delivery Management / Wallet
GET/customer/wallet/dashboard

Customer wallet dashboard data for UI cards + transaction history.

Rules

  • wallet.balance is currently usable funds; active draft-delivery holds have already been deducted.

  • wallet.reserved is the total held for active wallet-paid draft deliveries.

  • No currency field is returned; the frontend displays currency from tenant configuration.

  • Cards: Total Top-ups (lifetime), Total Spent (lifetime), This Month (current month spent). Refunds do not inflate Total Spent or orders-paid counts.

  • All history contains top-ups, delivery-fee payments, positive delivery-fee refunds, and payouts.

  • Payment history contains delivery-fee charges and positive delivery-fee refunds. Top-ups and Withdraw exclude refunds.

  • A refund is returned in the existing transaction shape with type = payment, a localized refund title/subtitle, positive amount, post-refund running_balance, and its delivery snapshot fields.

  • history.statuses counts use the same optional from_date / to_date population as history pagination.

  • Withdraw tab returns payout transactions (wallet_transactions.type = 'payout').

  • Per transaction running balance is returned in running_balance (from wallet_transactions.balance_snapshot column).

  • Every transaction includes nullable delivery_id and delivery_code. Delivery references use the stored wallet-transaction snapshot; non-delivery or unresolved historical rows return null.

Frontend integration contract

  • For a transaction linked to a delivery, use delivery_id for navigation and display delivery_code as the order identifier.

  • Render a type = payment item with positive amount as incoming/refunded; do not assume every Payment item is a debit.

  • Do not parse subtitle or use reference_id as a display code.

  • Treat null delivery fields as a transaction with no resolvable delivery context.

Query parameters

ParameterTypeDescription
pagestring

Page number (default: 1)

Example: 1

limitstring

Page size (frontend default: 5)

Example: 5

typestring

Transaction tab: all | topup | payment | withdraw. Payment includes delivery-fee charges and positive delivery-fee refunds.

Example: all

from_dateOptionalstring

Optional ISO date lower bound

to_dateOptionalstring

Optional ISO date upper bound

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Staging
Request
curl
1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/customer/wallet/dashboard?page=1&limit=5&type=all" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

200OK
Response body
json
1{2  "success": true,3  "data": {4    "wallet": {5      "balance": 100,6      "reserved": 25.57    },8    "cards": {9      "total_topups": {10        "amount": 100,11        "transactions_count": 112      },13      "total_spent": {14        "amount": 40.5,15        "orders_paid_count": 216      },17      "this_month": {18        "amount": 019      }20    },21    "history": {22      "type": "all",23      "statuses": [24        {25          "key": "all",26          "label": "All",27          "count": 428        },29        {30          "key": "topup",31          "label": "Top-ups",32          "count": 133        },34        {35          "key": "payment",36          "label": "Payment",37          "count": 338        },39        {40          "key": "withdraw",41          "label": "Withdraw",42          "count": 043        }44      ],45      "transactions": [46        {47          "id": "refund-uuid",48          "type": "payment",49          "title": "Delivery fee refund",50          "subtitle": "Delivery fee refunded for order DEL1949",51          "amount": 15.5,52          "running_balance": 100,53          "created_at": "2024-01-30T15:30:00Z",54          "reference_id": "delivery-uuid",55          "reference_type": "delivery",56          "delivery_id": "delivery-uuid",57          "delivery_code": "1949"58        },59        {60          "id": "uuid",61          "type": "payment",62          "title": "Order payment",63          "subtitle": "Delivery fee for order DEL1949",64          "amount": -15.5,65          "running_balance": 84.5,66          "created_at": "2024-01-29T15:30:00Z",67          "reference_id": "delivery-uuid",68          "reference_type": "delivery",69          "delivery_id": "delivery-uuid",70          "delivery_code": "1949"71        },72        {73          "id": "uuid",74          "type": "topup",75          "title": "Top-up",76          "subtitle": "Wallet top-up via card",77          "amount": 100,78          "running_balance": 100,79          "created_at": "2024-01-25T15:30:00Z",80          "reference_id": "uuid",81          "reference_type": "payment",82          "delivery_id": null,83          "delivery_code": null84        }85      ],86      "pagination": {87        "current_page": 1,88        "per_page": 5,89        "total_items": 3,90        "total_pages": 1,91        "has_next_page": false,92        "has_previous_page": false93      }94    }95  }96}

Create Payout Request​

Customer Portal / Delivery Management / Wallet
POST/customer/wallet/payout-requests

Customer creates a payout request (allowed user types configured in customer portal settings: individual and/or business).

Rules

  • Workflow only. No wallet debit happens here.

  • Wallet balance is checked (must be >= amount).

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Content-Typestring

Example: application/json

Body parameters

ParameterTypeDescription
amountRequirednumber

(required)

referenceOptionalstring

(optional)

notesOptionalstring

(optional)

Staging
Request
curl
1curl --globoff --request POST "https://staging-api.ondi.io/functions/v1/customer/wallet/payout-requests" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}" \3  --header "Content-Type: application/json" \4  --data-raw '{5  "amount": 0,6  "reference": "",7  "notes": ""8}'

Response examples

No saved response example. Use Try it to inspect a staging response.

List Payout Requests​

Customer Portal / Delivery Management / Wallet
GET/customer/wallet/payout-requests

Lists customer-owned payout requests. Access controlled by customer portal wallet_settings.allowed_payout_user_types (individual and/or business).

Query parameters

ParameterTypeDescription
pagestring

Page number (>=1)

Example: 1

limitstring

Items per page (1-50)

Example: 10

statusstring

all | pending | approved | rejected

Example: all

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Staging
Request
curl
1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/customer/wallet/payout-requests?page=1&limit=10&status=all" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

No saved response example. Use Try it to inspect a staging response.

Get Payout Request​

Customer Portal / Delivery Management / Wallet
GET/customer/wallet/payout-requests/:id

Gets customer-owned payout request detail. Access controlled by customer portal wallet_settings.allowed_payout_user_types (individual and/or business).

Path parameters

ParameterTypeDescription
idRequiredstring

Payout request ID

Example: payout-request-uuid

Headers

ParameterTypeDescription
Authorizationstring

Example: Bearer {{access_token}}

Staging
Request
curl
1curl --globoff --request GET "https://staging-api.ondi.io/functions/v1/customer/wallet/payout-requests/${ID}" \2  --header "Authorization: Bearer ${ONDI_ACCESS_TOKEN}"

Response examples

No saved response example. Use Try it to inspect a staging response.