Skip to main content

​
Endpoint

PATCH /wallets/{id}/status

​
Description

Use this endpoint to change the status of a wallet to active, frozen, or deleted.
Status updates are commonly used to temporarily restrict wallet activity, permanently disable a wallet, or re-enable it after review.

​
Path Parameters

ParameterTypeRequiredDescription
idstring (UUID)YesUnique identifier of the wallet

​
Request Body

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

​
Request Fields

FieldTypeRequiredDescription
statusstringYesNew status to apply to the wallet
reasonstringNoExplanation for the status change (recommended for audit and compliance)

​
Supported Statuses

StatusDescription
activeWallet is enabled and can perform transactions
frozenWallet is temporarily disabled; transactions are blocked
deletedWallet is permanently disabled and cannot be reactivated

​
Response

​
Success Response (200 OK)

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

​
Response Fields

FieldTypeDescription
idstringWallet identifier
statusstringUpdated wallet status

​
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 CodeReason
400Invalid status value
401Unauthorized request
404Wallet not found
422Invalid status transition
  • 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

After updating a wallet’s status, you may want to:
  • Notify the user of the status change
  • Review transaction history
  • Trigger internal compliance or risk workflows