Update Wallet Status

​

Endpoint

PATCH /wallets/{id}/status

​

Description

​

Path Parameters

​

Request Body

{
  "status": "frozen",
  "reason": "Suspicious activity detected"
}

​

Request Fields

​

Supported Statuses

​

Response

​

Success Response (200 OK)

{
  "data": {
    "id": "wallet_id",
    "status": "frozen"
  }
}

​

Response Fields

​

Example cURL Request

curl -X PATCH https://api.yourdomain.com/wallets/{id}/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "frozen",
    "reason": "Suspicious activity detected"
  }'

​

Common Errors

​

Status Transition Rules (Recommended)

• active → frozen ✅
• frozen → active ✅
• active → deleted ✅
• frozen → deleted ✅
• deleted → any status ❌ (not allowed)

​

Notes & Best Practices

• Always include a reason when freezing or deleting a wallet for audit and compliance purposes.
• Freezing a wallet should immediately block:
  • Incoming transfers
  • Outgoing transfers
  • Payment method usage
• Deleting a wallet should be treated as irreversible.
• Log all status changes for traceability and risk monitoring.

​

Common Use Cases

• Freeze wallet due to suspicious or fraudulent activity
• Reactivate wallet after compliance review
• Delete wallet when a customer account is closed

​

Next Steps

• Notify the user of the status change
• Review transaction history
• Trigger internal compliance or risk workflows