Card Issuance KYC API Access Webhook

Event Type: account_status_change

Event Name: card_issuance_api_access_updated

Overview

The Card Issuance KYC API access notification is sent when your entity's compliance status changes, affecting access to card issuance functionality. This notification uses Reap's consolidated notification system that automatically determines the appropriate event type and message based on your compliance state.

Important: The status field is always present and required in all Card Issuance KYC API notifications. It uses the RequirementStatus enum values: APPROVED, PENDING, or REJECTED.

Notification Strategy

Requirement Rejections: You'll receive notifications when individual requirements are rejected, so you know what needs to be fixed
Feature Access: You'll receive notifications when your overall feature access is granted, updated, or revoked
No Spam: You won't receive notifications for individual requirement approvals - only when the entire feature is ready to use

Webhook Payload Structure

When your Card Issuance KYC API access status changes, you will receive a webhook notification with the following payload:

{
  "eventType": "account_status_change",
  "eventName": "card_issuance_api_access_updated",
  "data": {
    "message": "Card Issuance KYC API access updated",
    "entityId": "ent_123e4567-e89b-12d3-a456-426614174000",
    "status": "APPROVED",
    "moderationComment": "Identity verification approved by compliance team",
    "reviewRejectType": "RETRY",
    "rejectLabels": ["DOCUMENT_QUALITY"],
    "timestamp": "2024-03-20T10:00:00Z"
  }
}

Payload Fields

Field	Type	Required	Description	Example
`eventType`	string	✅	Always `account_status_change`	`"account_status_change"`
`eventName`	string	✅	Always `card_issuance_api_access_updated`	`"card_issuance_api_access_updated"`
`data.message`	string	✅	Human-readable message describing the change	`"Card Issuance KYC API access granted"`
`data.entityId`	string	✅	UUID of your entity	`"ent_123e4567-e89b-12d3-a456-426614174000"`
`data.status`	string	✅	Current compliance status (always present)	`"APPROVED"`, `"PENDING"`, or `"REJECTED"`
`data.moderationComment`	string	❌	Comment from the compliance team	`"Identity verification approved by compliance team"`
`data.reviewRejectType`	string	❌	Type of rejection (only for rejected status)	`"FINAL"` or `"RETRY"`
`data.rejectLabels`	string[]	❌	Specific rejection reasons (only for rejections)	`["DOCUMENT_QUALITY", "EXPIRED_DOCUMENT"]`
`data.timestamp`	string	✅	ISO 8601 timestamp when the event occurred	`"2024-03-20T10:00:00Z"`

Status Values

Status	Description	When It Occurs
`APPROVED`	Requirement successfully met	When KYC verification passes all checks
`PENDING`	Awaiting review or processing	When requirement is submitted but not yet processed
`REJECTED`	Requirement failed verification	When KYC verification fails or is rejected

Review Reject Type Values

Type	Description	Action Required
`FINAL`	Permanent rejection, no further attempts allowed	Contact support for clarification
`RETRY`	Temporary rejection, can resubmit with corrections	Address the issues and resubmit

Common Reject Labels

When a requirement is rejected, the rejectLabels array may contain one or more of these values:

Label	Description
`DOCUMENT_QUALITY`	Document image quality is insufficient
`EXPIRED_DOCUMENT`	Document has expired
`DOCUMENT_NOT_SUPPORTED`	Document type is not accepted
`FACE_MISMATCH`	Face verification failed
`RESTRICTED_PERSON`	Person appears on restricted lists
`INVALID_DATA`	Submitted data contains errors
`INCOMPLETE_SUBMISSION`	Required information is missing

For a complete list of rejection labels, see: SumSub Documentation

Example Payloads

Requirement Rejected (Individual Issue)

{
  "eventType": "account_status_change",
  "eventName": "card_issuance_api_access_updated",
  "data": {
    "message": "Card Issuance KYC API requirement rejected",
    "entityId": "ent_123e4567-e89b-12d3-a456-426614174000",
    "status": "REJECTED",
    "moderationComment": "Identity document image quality is insufficient. Please resubmit with clearer images",
    "reviewRejectType": "RETRY",
    "rejectLabels": ["DOCUMENT_QUALITY"],
    "requirementId": "req_456e7890-f12c-34d5-b678-901234567890",
    "slug": "individual-verification-identity",
    "timestamp": "2024-03-20T10:00:00Z"
  }
}

Access Granted (Auto-Enabled)

{
  "eventType": "account_status_change",
  "eventName": "card_issuance_api_access_updated",
  "data": {
    "message": "Card Issuance KYC API access auto-granted - Card Issuance KYC API",
    "entityId": "ent_123e4567-e89b-12d3-a456-426614174000",
    "status": "APPROVED",
    "timestamp": "2024-03-20T10:00:00Z"
  }
}

Access Granted (Manual Approval)

{
  "eventType": "account_status_change",
  "eventName": "card_issuance_api_access_updated",
  "data": {
    "message": "Card Issuance KYC API access granted",
    "entityId": "ent_123e4567-e89b-12d3-a456-426614174000",
    "status": "APPROVED",
    "moderationComment": "Identity verification and business documents approved by compliance team",
    "timestamp": "2024-03-20T10:00:00Z"
  }
}

Access Revoked - Final Rejection

{
  "eventType": "account_status_change",
  "eventName": "card_issuance_api_access_updated",
  "data": {
    "message": "Card Issuance KYC API access revoked",
    "entityId": "ent_123e4567-e89b-12d3-a456-426614174000",
    "status": "REJECTED",
    "moderationComment": "Business registration documents do not meet compliance standards",
    "reviewRejectType": "FINAL",
    "rejectLabels": ["DOCUMENT_NOT_SUPPORTED", "INVALID_DATA"],
    "timestamp": "2024-03-20T10:00:00Z"
  }
}

Access Revoked - Retry Allowed

{
  "eventType": "account_status_change",
  "eventName": "card_issuance_api_access_updated",
  "data": {
    "message": "Card Issuance KYC API access revoked",
    "entityId": "ent_123e4567-e89b-12d3-a456-426614174000",
    "status": "REJECTED",
    "moderationComment": "Identity document image quality is insufficient. Please resubmit with clearer images",
    "reviewRejectType": "RETRY",
    "rejectLabels": ["DOCUMENT_QUALITY"],
    "timestamp": "2024-03-20T10:00:00Z"
  }
}

Webhook Handler Example

// Express.js webhook handler
app.post('/webhooks/reap', (req, res) => {
  const notification = req.body;

  // Verify webhook signature (see WEBHOOK_SETUP.md for implementation)
  if (!verifyWebhookSignature(req.body, req.headers['reap-signature'])) {
    return res.status(401).send('Invalid signature');
  }

  if (notification.eventName === 'card_issuance_api_access_updated') {
    const {
      entityId,
      status,
      moderationComment,
      reviewRejectType,
      rejectLabels,
      requirementId,
      slug,
    } = notification.data;

    // Handle status-based notifications using RequirementStatus enum values
    // Status is always present and uses enum values: APPROVED, PENDING, REJECTED
    switch (status) {
      case 'APPROVED':
        console.log(`✅ Entity ${entityId} now has Card Issuance KYC API access`);
        if (moderationComment) {
          console.log(`Compliance comment: ${moderationComment}`);
        }
        enableCardIssuanceFeatures(entityId);
        break;

      case 'PENDING':
        console.log(`⏳ Entity ${entityId} KYC is under review`);
        if (moderationComment) {
          console.log(`Compliance comment: ${moderationComment}`);
        }
        showPendingStatus(entityId, moderationComment);
        break;

      case 'REJECTED':
        // Check if this is a requirement rejection or feature access revocation
        if (requirementId && slug) {
          // Individual requirement rejected - user needs to fix specific issue
          console.log(`❌ Entity ${entityId} requirement '${slug}' was rejected`);
          if (moderationComment) {
            console.log(`Compliance comment: ${moderationComment}`);
          }

          if (rejectLabels && rejectLabels.length > 0) {
            console.log(`Rejection reasons: ${rejectLabels.join(', ')}`);
          }

          if (reviewRejectType === 'RETRY') {
            console.log(`💡 You can resubmit your documents after addressing the issues`);
            showRequirementRetryOption(entityId, slug, moderationComment, rejectLabels);
          } else if (reviewRejectType === 'FINAL') {
            console.log(`🚫 This is a final rejection. Please contact support for assistance`);
            showSupportContact(entityId);
          }
        } else {
          // Feature access revoked - entire access removed
          console.log(`❌ Entity ${entityId} Card Issuance KYC API access was revoked`);
          if (moderationComment) {
            console.log(`Compliance comment: ${moderationComment}`);
          }
          disableCardIssuanceFeatures(entityId);
        }
        break;
    }
  }

  res.status(200).send('OK');
});

// Helper functions (implement according to your application needs)
function enableCardIssuanceFeatures(entityId) {
  // Enable card issuance functionality for this entity
  // Update your application state, enable UI features, etc.
}

function disableCardIssuanceFeatures(entityId) {
  // Disable card issuance functionality for this entity
  // Update your application state, disable UI features, etc.
}

function showPendingStatus(entityId, comment) {
  // Show pending status to user with optional comment
}

function showRequirementRetryOption(entityId, requirementSlug, comment, rejectLabels) {
  // Show retry option for specific requirement with guidance based on rejection reasons
  // Focus user on fixing the specific requirement that was rejected
}

function showSupportContact(entityId) {
  // Show support contact information for final rejections
}

Integration Notes

Entity-Level Focus

This notification system focuses on entity-level compliance. Each entity represents either an individual or business customer requiring verification.

Automatic Feature Enablement

The system includes automatic feature enablement for qualifying entities. When an entity meets all requirements, they may receive access automatically without manual approval.

Smart Notification System

The notification system automatically determines the appropriate message and event details based on the compliance context, reducing the complexity of webhook handling.

Webhook Security

Always verify webhook signatures before processing notifications. See WEBHOOK_SETUP.md for detailed security implementation guidance.