Private Account Lifecycle

This guide describes the customer-facing lifecycle actions supported for private accounts.

Private accounts support three lifecycle actions through the API:

• Cancel — permanently disables a private account
• Block — temporarily disables a private account
• Activate — restores a previously blocked private account to ACTIVE

This guide covers the following customer-facing states for private accounts:

• ACTIVE
• BLOCKED
• CANCELLED

• ACTIVE → BLOCKED
• BLOCKED → ACTIVE
• ACTIVE → CANCELLED

Use this action when you want to permanently disable a private account.

PUT /v1/clients/{clientId}/accounts/{accountId}/cancel

• Changes the account status to CANCELLED
• The operation is permanent
• The operation is irreversible

This endpoint does not require a request body.

Before cancelling the account, the API validates the following conditions:

1. The account must belong to the specified client
2. Only private accounts can be cancelled
3. The account must not already be cancelled
4. The available balance must be equal to 0

Status Code: 200 OK

The API returns the updated account object with:

{
  "account_status": "CANCELLED"
}

curl -X PUT "{{base_url}}/v1/clients/{{clientId}}/accounts/{{accountId}}/cancel" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json"

• Cancellation is immediate after a successful API response
• Cancellation is irreversible
• Only private accounts can be cancelled
• Accounts with non-zero balance cannot be cancelled

HTTP Code: 400 Bad Request

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Account is already cancelled",
        "http_code": "400",
        "module": "Account",
        "method_name": "Cancel"
      }
    }
  ]
}

HTTP Code: 400 Bad Request

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Only Private Accounts can be cancelled",
        "http_code": "400",
        "module": "Account",
        "method_name": "Cancel",
        "error_code": "10-E4120"
      }
    }
  ]
}

HTTP Code: 400 Bad Request

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Invalid account balance, account balance must be equal to 0",
        "http_code": "400",
        "module": "Account",
        "method_name": "Cancel"
      }
    }
  ]
}

HTTP Code: 403 Forbidden

{
  "code": 7,
  "message": "API Error",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "FORBIDDEN",
      "domain": "CORE",
      "metadata": {
        "error_detail": "Account does not belong to the specified client",
        "http_code": "403",
        "module": "Account",
        "method_name": "Cancel"
      }
    }
  ]
}

Use this action when you want to temporarily disable a private account.

PUT /v1/clients/{clientId}/accounts/{accountId}/block

• Changes the account status to BLOCKED
• The operation is temporary
• The account can later be restored to ACTIVE

This endpoint does not require a request body.

Before blocking the account, the API validates the following conditions:

1. The account must belong to the specified client
2. Only private accounts can be blocked

Status Code: 200 OK

The API returns the updated account object with:

{
  "account_status": "BLOCKED"
}

curl -X PUT "{{base_url}}/v1/clients/{{clientId}}/accounts/{{accountId}}/block" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json"

• Blocking is temporary
• A blocked account can later be restored through the activation endpoint

Use this action when you want to restore a previously blocked private account.

PATCH /v1/clients/{clientId}/accounts/{accountId}/activate

• Changes the account status to ACTIVE
• This action is intended to reverse a previous block

This endpoint does not require a request body.

Before activating the account, the API validates the following conditions:

1. The account must belong to the specified client
2. The account must currently be blocked

Status Code: 200 OK

The API returns the updated account object with:

{
  "account_status": "ACTIVE"
}

curl -X PATCH "{{base_url}}/v1/clients/{{clientId}}/accounts/{{accountId}}/activate" \
  -H "Authorization: Bearer {{access_token}}" \
  -H "Content-Type: application/json"

• Activation is used to restore a previously blocked private account
• Once activation succeeds, the account remains in ACTIVE status

The following customer-facing endpoints are available for private account lifecycle management:

• PUT /v1/clients/{clientId}/accounts/{accountId}/cancel
• PUT /v1/clients/{clientId}/accounts/{accountId}/block
• PATCH /v1/clients/{clientId}/accounts/{accountId}/activate