Admin adjust / clawback organisation wallet (audited)

Signed, audited wallet adjustment — the single sanctioned manual mutation path (ADR-013). Positive amount credits; negative amount debits/claws back. Writes a transactions row, journals a wallet_ledgers entry (operationId adj:<ref>, with reason + adjustedBy), updates the durable Postgres balance and syncs the Redis mirror — replacing raw Redis/SQL edits. A reason is mandatory; adjustments above WALLET_ADJUST_APPROVAL_THRESHOLD require a secondApprover. Admin only.

POST/v1/payments/admin/adjust/{organisationId}

Authorization

bearer

AuthorizationBearer <token>

In: header

Path Parameters

organisationId*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount*number

Signed adjustment amount in major units (NGN). Positive credits the wallet; negative debits/claws back.

reason*string

Mandatory justification for the adjustment. Persisted on the ledger entry for audit.

secondApprover?string

ID/email of the second approver. Required when |amount| exceeds WALLET_ADJUST_APPROVAL_THRESHOLD.

currency?string

Currency code (ISO 4217)

Default"NGN"

Response Body

`application/json`

curl -X POST "https://example.com/v1/payments/admin/adjust/string" \  -H "Content-Type: application/json" \  -d '{    "amount": -1200000,    "reason": "Revert Safe Haven duplicate over-credit (GH #295)"  }'

{  "success": true,  "statusCode": 200,  "message": "Request processed successfully",  "timestamp": "2025-10-20T16:30:00.000Z",  "path": "/v1/auth/register",  "data": {    "transactionId": "clx123abc",    "reference": "ADMIN-ADJ-1711500000000-ABC123",    "operationId": "adj:ADMIN-ADJ-1711500000000-ABC123",    "amount": -1200000,    "direction": "DEBIT",    "currency": "NGN",    "status": "SUCCESS",    "newBalance": 50000,    "organisationId": "org_clx456def",    "adjustedAt": "2019-08-24T14:15:22Z"  }}

Empty