Credit Wallet

Credits a wallet balance inside one project. Use this endpoint for manual top-ups, credit grants, or other externally confirmed funding events.

POST /v1/projects/:project_id/wallets/credit

Authentication

Authorization: Bearer <api-key>
Content-Type: application/json

Path Parameters

Field	Required	Description
project_id	Yes	Project that owns the wallet. The account_id or resolved subject route must belong to this project.

Request Body

{
  "account_id": "acct_xxx",
  "currency": "USD",
  "amount": "500.00",
  "source_type": "manual_topup",
  "source_id": "topup_20260629_001",
  "remark": "Record a confirmed customer bank transfer",
  "idempotency_key": "topup:t_001:acct_xxx:20260629_001"
}

Field	Required	Description
account_id	Conditionally	Billing account ID in the same project. Mutually exclusive with resolving the account from subject_type and subject_id. Recommended for wallet credits.
subject_type	Conditionally	Subject type used to resolve the account when account_id is not provided.
subject_id	Conditionally	Subject ID used to resolve the account when account_id is not provided.
currency	Yes	Currency to credit.
amount	Yes	Credit amount. Must be greater than 0. Use a JSON string for decimal precision.
source_type	No	Source type for the credit, for example manual_topup.
source_id	No	Source identifier from your system.
remark	No	Reason for the credit, up to 500 Unicode characters. Leading and trailing whitespace is trimmed. Returned with the ledger entry and visible to ledger readers; avoid internal sensitive information.
idempotency_key	No	Idempotency key. Length: 1-255 characters when provided. Repeated requests with the same key do not apply duplicate credits.

Notes

• Prefer passing account_id directly for top-up flows.
• Use a stable idempotency_key for retryable requests, up to 255 characters.
• Idempotency is scoped by tenant_id + project_id; the same key in another project is independent.
• Wallet balance mutations are serialized by the service for the affected tenant, project, account, and currency.

Response

Returns the updated wallet and the created ledger_entry. The ledger response omits remark when empty. Retries with the same idempotency key return the original entry and preserve its original remark.

{
  "wallet": {
    "id": "wlt_xxx",
    "tenant_id": "t_001",
    "project_id": "proj_gateway",
    "account_id": "acct_xxx",
    "currency": "USD",
    "balance": "500",
    "available_balance": "500",
    "credit_limit": "0",
    "status": "active",
    "created_at": 1782720000,
    "updated_at": 1782720000
  },
  "ledger_entry": {
    "id": "wle_xxx",
    "tenant_id": "t_001",
    "project_id": "proj_gateway",
    "account_id": "acct_xxx",
    "wallet_id": "wlt_xxx",
    "currency": "USD",
    "fund_type": "cash",
    "fund_id": "cash:acct_xxx:USD",
    "direction": "credit",
    "amount": "500",
    "balance_after": "500",
    "source_type": "manual_topup",
    "source_id": "topup_20260629_001",
    "remark": "Record a confirmed customer bank transfer",
    "idempotency_key": "topup:t_001:acct_xxx:20260629_001",
    "created_at": 1782720000
  }
}