Revoke Consent

​

Overview

• The customer explicitly requests to revoke their consent through your application interface
• A loan application is completed or cancelled, and continued data access is no longer needed
• Your business logic determines that data sharing should be terminated (e.g., customer account closure, product expiry)
• You need to comply with data minimization principles by revoking consent as soon as the business purpose is fulfilled

​

Endpoint

POST {{Base_URL}}/revokeconsent

​

Authentication

​

Request Body

​

Important Notes

• Consent ID Format: The consent ID is a UUID (Universally Unique Identifier) typically in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Ensure you’re using the correct consent ID and not confusing it with the consent handle.
• Active Consents Only: Only consents in ACTIVE or PAUSED status can be revoked. Attempting to revoke a consent that is already REVOKED, REJECTED, EXPIRED, or PENDING will result in an error.
• Consent Handle vs Consent ID: Do not confuse the consent handle (created during consent request) with the consent ID (assigned after approval). Only the consent ID can be used for revocation, and it’s only available after the customer approves the consent.
• Irreversible Action: Revocation cannot be undone. After revoking, you’ll need to create a new consent request if data access is needed again.

​

Response

​

Success Response (200 OK)

{
  "ver": "1.21.0",
  "status": "success",
  "message": "Successfully revoked."
}

​

Post-Revocation Behavior

1. Immediate Effect: The consent status changes to REVOKED immediately. Any in-flight or future data fetch requests using this consent will be rejected.
2. Webhook Notification: If you have webhook subscriptions configured for consent revocation events, a webhook notification will be triggered with event type CONSENT and event status CONSENT_REVOKED.
3. Data Access Termination: The FIP will be notified about the revocation, and the customer’s data will no longer be accessible through this consent.
4. Audit Trail: The revocation event is recorded in the consent audit trail with timestamp and source information for compliance and record-keeping purposes.

​

Error Response (400 Bad Request) - Already Revoked

{
  "ver": "1.21.0",
  "timestamp": "2025-10-01T11:44:44.115Z",
  "errorCode": "InvalidStatus",
  "errorMsg": "Consent ID is already in REVOKED state"
}

​

Error Response (400 Bad Request) - Invalid Consent ID

{
  "ver": "1.21.0",
  "timestamp": "2025-10-01T11:45:12.330Z",
  "errorCode": "InvalidRequest",
  "errorMsg": "Invalid consent ID or consent not found"
}

​

Error Response (400 Bad Request) - Invalid Status

{
  "ver": "1.21.0",
  "timestamp": "2025-10-01T11:45:30.221Z",
  "errorCode": "InvalidStatus",
  "errorMsg": "Consent cannot be revoked in current status: PENDING"
}

​

Common Error Codes

​

Example Request

curl --location '{{Base_URL}}/revokeconsent' \
--header 'Content-Type: application/json' \
--header 'client_id: {{Client_Id}}' \
--header 'client_secret: {{Client_Secret}}' \
--header 'organisationId: {{Organisation_Id}}' \
--header 'appIdentifier: {{App_Identifier}}' \
--data '{
    "consentID": "20918495-ea9c-4508-a1b4-93ca1fbfd0f3"
}'

​

Use Cases

​

Customer-Initiated Revocation

class ConsentManager {
  async revokeConsentWithConfirmation(consentID, consentDetails) {
    // Show confirmation dialog to user
    const confirmed = await this.confirmRevocation(consentDetails);

    if (!confirmed) {
      return { cancelled: true };
    }

    // Proceed with revocation
    const result = await revokeConsent(consentID);

    if (result.success) {
      // Log for audit trail
      await this.logRevocation(consentID, 'CUSTOMER_INITIATED');

      // Update UI
      this.updateConsentStatus(consentID, 'REVOKED');

      // Show success message
      this.showNotification('Your consent has been revoked successfully');
    } else {
      // Handle error
      this.showError(`Failed to revoke consent: ${result.error}`);
    }

    return result;
  }

  async confirmRevocation(consentDetails) {
    return window.confirm(
      `Are you sure you want to revoke consent for ${consentDetails.fipName}?\n` +
      `Account: ${consentDetails.maskedAccountNumber}\n` +
      `This action cannot be undone.`
    );
  }
}

​

Automatic Revocation After Loan Completion

def handle_loan_completion(loan_application_id):
    """Automatically revoke consents when loan is disbursed or rejected"""
    # Get all active consents for this loan application
    account_id = f"LOAN_{loan_application_id}"
    consents = get_consents_v2(
        identifier_type='MOBILE',
        identifier_value=loan_application.customer_mobile,
        product_id='LOAN_UNDERWRITING',
        account_id=account_id
    )

    # Revoke all active consents
    revocation_results = []
    for consent in consents['data']:
        if consent['status'] == 'ACTIVE' and consent['consentID']:
            result = revoke_consent(consent['consentID'])
            revocation_results.append({
                'consent_id': consent['consentID'],
                'fip_id': consent.get('fipId'),
                'result': result
            })

            # Log for compliance audit
            log_consent_revocation(
                loan_application_id=loan_application_id,
                consent_id=consent['consentID'],
                reason='LOAN_COMPLETED',
                success=result['success']
            )

    return revocation_results

​

Batch Revocation for Expired Products

async function bulkRevokeExpiredProductConsents(productID, mobileNumbers) {
  const results = {
    success: [],
    failed: [],
    alreadyRevoked: []
  };

  for (const mobile of mobileNumbers) {
    try {
      // Get consents for this customer and product
      const consents = await getConsentsList(mobile, productID);

      for (const consent of consents.data) {
        if (consent.status === 'ACTIVE' && consent.consentID) {
          const result = await revokeConsent(consent.consentID);

          if (result.success) {
            results.success.push({
              mobile,
              consentID: consent.consentID,
              fipId: consent.fipId
            });
          } else if (result.error.includes('already in REVOKED state')) {
            results.alreadyRevoked.push(consent.consentID);
          } else {
            results.failed.push({
              mobile,
              consentID: consent.consentID,
              error: result.error
            });
          }
        }
      }
    } catch (error) {
      console.error(`Error processing consents for ${mobile}:`, error);
      results.failed.push({ mobile, error: error.message });
    }
  }

  return results;
}

​

Revocation with Status Verification

def safe_revoke_consent(consent_id: str) -> dict:
    """Revoke consent with pre-revocation status check"""
    # First, verify the consent exists and is in revocable status
    # This requires having the customer's mobile and product ID
    # In practice, you'd retrieve this from your database

    try:
        result = revoke_consent(consent_id)

        if result['success']:
            return {
                'status': 'SUCCESS',
                'message': result['message'],
                'consent_id': consent_id
            }
        elif 'already in REVOKED state' in result.get('error', ''):
            return {
                'status': 'ALREADY_REVOKED',
                'message': 'Consent was already revoked',
                'consent_id': consent_id
            }
        else:
            return {
                'status': 'ERROR',
                'error': result['error'],
                'error_code': result.get('error_code'),
                'consent_id': consent_id
            }
    except Exception as e:
        return {
            'status': 'EXCEPTION',
            'error': str(e),
            'consent_id': consent_id
        }

​

Best Practices

1. User Confirmation: Always require explicit user confirmation before revoking consents initiated through customer interfaces. Display relevant consent details (FIP name, account number, data types) in the confirmation dialog.
2. Audit Logging: Log all revocation attempts (both successful and failed) with timestamp, reason, and initiating user/system for compliance and debugging purposes.
3. Status Verification: Before attempting revocation, verify that the consent is in ACTIVE or PAUSED status to avoid unnecessary error responses. Use the Consent List APIs to check current status.
4. Error Handling: Handle “already revoked” errors gracefully - this is a common scenario when multiple systems or processes might attempt to revoke the same consent.
5. Webhook Integration: Configure webhook subscriptions for revocation events so your system can react to revocations initiated by customers through the AA interface or other channels.
6. Data Cleanup: After revoking consent, consider triggering data retention policies to delete or archive any financial information that was fetched using the revoked consent, in accordance with your privacy policy.
7. Customer Communication: Notify customers when consents are revoked, especially for system-initiated revocations. Include information about why the revocation occurred and how to grant new consent if needed.
8. Idempotency Consideration: Implement idempotent revocation logic in your application. If a revocation request fails or times out, it should be safe to retry without causing issues.

​

Regulatory Considerations

• Right to Withdraw: Customers have the right to withdraw consent at any time. Your application must provide easily accessible mechanisms for consent revocation.
• Immediate Effect: Revocation must take effect immediately upon processing. Continuing to fetch data after revocation is a regulatory violation.
• Transparency: Maintain clear audit trails showing when consents were revoked, by whom, and for what reason.
• Data Deletion: Consider implementing automatic data deletion policies triggered by consent revocation to comply with data minimization principles.
• Customer Access: Customers should be able to view their revocation history and understand which consents are active vs revoked.

​

Integration with Webhooks

{
  "timestamp": "2025-10-01T12:00:00.000Z",
  "consentHandle": "8b5b9333-00df-4b99-99d8-b0918f897e7b",
  "eventType": "CONSENT",
  "eventStatus": "CONSENT_REVOKED",
  "consentId": "20918495-ea9c-4508-a1b4-93ca1fbfd0f3",
  "vua": "9876543210@onemoney",
  "productID": "TESTWM01",
  "accountID": "test123",
  "revokedBy": "FIU",
  "revocationReason": "API_INITIATED"
}

• Update consent status in your database
• Trigger data cleanup processes
• Notify relevant internal systems
• Update customer-facing dashboards in real-time

​

Related APIs

• Consent List APIs: Use these to retrieve consent IDs before revocation
• Consent Request APIs: Create new consents if a revoked consent needs to be replaced
• Data Management APIs: Any data fetch operations using revoked consent IDs will fail