Convert to Credit Webhooks

Overview

Convert to Credit (C2C) webhooks enable users to exchange their Lucra cash balance for credits in your system. When a user initiates a C2C transaction, Lucra temporarily holds the dollar amount and sends a webhook to your endpoint for credit fulfillment.

Prerequisites

• Webhook endpoint configured per Webhook Setup

• Subscribed to C2CWithdrawal event

• Signature verification implemented per Webhook Setup

• API credentials from API Setup

Important Constraints

• The C2CWithdrawal subscription can only exist in one webhook configuration at a time

• See Webhook Setup for details on subscription restrictions

C2CWithdrawal Event

The C2CWithdrawal event fires when a user requests to convert their Lucra balance to credits in your system.

Webhook Flow

1. User initiates Convert to Credit transaction

2. Lucra temporarily holds the dollar amount

3. Amount is deducted from user's balance

4. Webhook sent to your endpoint

5. Your system grants credits

6. Your endpoint returns success/failure response

7. Lucra finalizes or reverses the transaction based on response

Payload

{
  "intentId": "5a31e00a-a2b8-4cdc-80cb-3ce3312f8023",
  "userId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "amount": 100,
  "convertedAmount": 120,
  "conversionMetadata": {
    "customKey1": "customValue1",
    "promotionId": "summer-2025",
    "tier": "gold"
  }
}

Field Descriptions

Field	Type	Description
intentId	string	UUID passed from SDK - use for idempotency tracking
userId	string	Lucra's canonical user identifier (UUID)
amount	number	Dollar amount deducted from user's Lucra balance
convertedAmount	number	Credit amount to grant after multiplier applied
conversionMetadata	object|null	Custom data passed via SDK (null by default)

Notes:

• intentId is unique per transaction - use for idempotency

• amount is what the user paid in dollars

• convertedAmount reflects any conversion multiplier (e.g., 1.2x bonus)

• conversionMetadata can contain arbitrary custom data for tracking

Response Format

Your endpoint must respond synchronously with a JSON object indicating transaction outcome.

Success Response

{
  "status": "COMPLETED",
  "responseText": "Successfully added 120 credits to your account!",
  "responseDetails": {
    "transactionId": "txn_abc123",
    "creditsGranted": 120,
    "newBalance": 1520
  }
}

Failure Response

{
  "status": "FAILED",
  "responseText": "Unable to process credit conversion. Please contact support.",
  "responseDetails": {
    "errorCode": "ACCOUNT_SUSPENDED",
    "reason": "User account is temporarily suspended"
  }
}

Pending Response

{
  "status": "PENDING",
  "responseText": "Your credit conversion is being processed. You'll receive a notification when complete.",
  "responseDetails": {
    "estimatedCompletionTime": "2025-06-15T15:30:00Z",
    "referenceId": "pending_xyz789"
  }
}

Response Fields

Field	Type	Required	Description
status	string	Yes	Transaction status: COMPLETED, FAILED, or PENDING (case-sensitive)
responseText	string	Yes	User-facing message displayed in the UI
responseDetails	any	No	Arbitrary JSON data stored for support inquiries

Status Values:

• COMPLETED: Credits successfully granted. Dollar amount remains deducted from user's Lucra balance.

• FAILED: Credits not granted. Dollar amount returned to user's Lucra balance.

• PENDING: Processing continues asynchronously. Dollar amount remains deducted. Use for delayed fulfillment scenarios.

Important:

• responseText is shown directly to the user - make it clear and friendly

• responseDetails is for internal tracking and support purposes

• Status values are case-sensitive

Implementation Examples

Basic Implementation (Node.js/Express)

interface C2CWithdrawalPayload {
  intentId: string;
  userId: string;
  amount: number;
  convertedAmount: number;
  conversionMetadata: any | null;
}

interface C2CResponse {
  status: 'COMPLETED' | 'FAILED' | 'PENDING';
  responseText: string;
  responseDetails?: any;
}

app.post('/webhooks/c2c', async (req, res) => {
  try {
    // Verify webhook signature
    if (!verifySignature(req)) {
      return res.status(401).json({
        status: 'FAILED',
        responseText: 'Invalid signature',
        responseDetails: { error: 'Signature verification failed' },
      });
    }

    const payload: C2CWithdrawalPayload = req.body;
    const { intentId, userId, convertedAmount, conversionMetadata } = payload;

    // Check for duplicate processing
    const existing = await db.c2cTransactions.findOne({ intentId });
    if (existing) {
      // Return same response as before (idempotency)
      return res.status(200).json(existing.response);
    }

    // Grant credits to user
    const result = await grantCredits(userId, convertedAmount, {
      source: 'lucra_c2c',
      intentId,
      metadata: conversionMetadata,
    });

    const response: C2CResponse = {
      status: 'COMPLETED',
      responseText: `Successfully added ${convertedAmount} credits to your account!`,
      responseDetails: {
        transactionId: result.transactionId,
        creditsGranted: convertedAmount,
        newBalance: result.newBalance,
      },
    };

    // Store transaction record
    await db.c2cTransactions.create({
      intentId,
      userId,
      amount: payload.amount,
      convertedAmount,
      status: 'COMPLETED',
      response,
      processedAt: new Date(),
    });

    res.status(200).json(response);
  } catch (error) {
    console.error('C2C webhook error:', error);

    const response: C2CResponse = {
      status: 'FAILED',
      responseText: 'Unable to process your request. Please try again later.',
      responseDetails: {
        error: error.message,
        timestamp: new Date().toISOString(),
      },
    };

    res.status(200).json(response);
  }
});

Advanced Implementation with Validation

async function handleC2CWithdrawal(payload: C2CWithdrawalPayload): Promise<C2CResponse> {
  const { intentId, userId, amount, convertedAmount, conversionMetadata } = payload;

  // 1. Idempotency check
  const existing = await getExistingTransaction(intentId);
  if (existing) {
    return existing.response;
  }

  // 2. Validate user eligibility
  const user = await getUser(userId);
  if (!user) {
    return {
      status: 'FAILED',
      responseText: 'User account not found.',
      responseDetails: { error: 'USER_NOT_FOUND' },
    };
  }

  if (user.status === 'suspended') {
    return {
      status: 'FAILED',
      responseText: 'Your account is temporarily suspended. Please contact support.',
      responseDetails: { error: 'ACCOUNT_SUSPENDED' },
    };
  }

  // 3. Validate conversion amount
  if (convertedAmount <= 0) {
    return {
      status: 'FAILED',
      responseText: 'Invalid conversion amount.',
      responseDetails: { error: 'INVALID_AMOUNT', amount: convertedAmount },
    };
  }

  // 4. Check for rate limiting
  const recentConversions = await countRecentConversions(userId, '1h');
  if (recentConversions >= 10) {
    return {
      status: 'FAILED',
      responseText: 'Too many conversions. Please try again later.',
      responseDetails: { error: 'RATE_LIMIT_EXCEEDED' },
    };
  }

  try {
    // 5. Grant credits
    const creditResult = await grantCredits(userId, convertedAmount, {
      source: 'lucra_c2c',
      intentId,
      originalAmount: amount,
      metadata: conversionMetadata,
    });

    // 6. Log transaction
    await logC2CTransaction({
      intentId,
      userId,
      amount,
      convertedAmount,
      status: 'COMPLETED',
      transactionId: creditResult.transactionId,
      processedAt: new Date(),
    });

    // 7. Send notification
    await sendNotification(userId, {
      type: 'c2c_completed',
      credits: convertedAmount,
      newBalance: creditResult.newBalance,
    });

    return {
      status: 'COMPLETED',
      responseText: `Successfully added ${convertedAmount} credits to your account!`,
      responseDetails: {
        transactionId: creditResult.transactionId,
        creditsGranted: convertedAmount,
        previousBalance: creditResult.previousBalance,
        newBalance: creditResult.newBalance,
      },
    };
  } catch (error) {
    // Log error for investigation
    await logC2CError({
      intentId,
      userId,
      error: error.message,
      stack: error.stack,
    });

    return {
      status: 'FAILED',
      responseText: 'Unable to process your request. Please contact support.',
      responseDetails: {
        error: error.message,
        errorCode: error.code || 'UNKNOWN_ERROR',
      },
    };
  }
}

Async Processing with PENDING Status

async function handleC2CWithdrawalAsync(payload: C2CWithdrawalPayload): Promise<C2CResponse> {
  const { intentId, userId, convertedAmount } = payload;

  // Queue for asynchronous processing
  await processingQueue.add('c2c-conversion', {
    intentId,
    userId,
    convertedAmount,
    payload,
  });

  // Return pending status immediately
  return {
    status: 'PENDING',
    responseText: "Your credit conversion is being processed. You'll receive a notification when complete.",
    responseDetails: {
      intentId,
      estimatedCompletionTime: new Date(Date.now() + 5 * 60 * 1000).toISOString(), // 5 minutes
      queuePosition: await processingQueue.getPosition(intentId),
    },
  };
}

// Background worker
processingQueue.process('c2c-conversion', async (job) => {
  const { intentId, userId, convertedAmount } = job.data;

  try {
    // Process conversion
    await grantCredits(userId, convertedAmount, { intentId });

    // Update status and notify user
    await updateC2CStatus(intentId, 'COMPLETED');
    await sendNotification(userId, {
      type: 'c2c_completed',
      credits: convertedAmount,
    });
  } catch (error) {
    // Mark as failed and refund via Lucra support
    await updateC2CStatus(intentId, 'FAILED');
    await sendNotification(userId, {
      type: 'c2c_failed',
      message: 'Conversion failed. Your balance has been restored.',
    });
  }
});

Best Practices

1. Idempotency

Always check for duplicate processing using intentId:

async function ensureIdempotency(intentId: string) {
  const existing = await db.c2cTransactions.findOne({ intentId });
  if (existing) {
    console.log(`Duplicate C2C request: ${intentId}`);
    return existing.response;
  }
  return null;
}

2. User-Friendly Messages

Craft clear responseText messages for different scenarios:

const RESPONSE_MESSAGES = {
  SUCCESS: (credits: number) => `Successfully added ${credits} credits to your account!`,
  ACCOUNT_ISSUE: "There's an issue with your account. Please contact support.",
  SYSTEM_ERROR: 'Unable to process your request right now. Please try again later.',
  RATE_LIMIT: "You've made too many conversions recently. Please wait a bit.",
  PENDING: "Your conversion is being processed. We'll notify you when it's complete.",
};

3. Comprehensive Logging

Log all C2C transactions for audit and support:

interface C2CTransactionLog {
  intentId: string;
  userId: string;
  amount: number;
  convertedAmount: number;
  status: 'COMPLETED' | 'FAILED' | 'PENDING';
  responseText: string;
  responseDetails: any;
  processedAt: Date;
  errorMessage?: string;
}

await db.c2cLogs.create({
  intentId,
  userId,
  amount,
  convertedAmount,
  status: response.status,
  responseText: response.responseText,
  responseDetails: response.responseDetails,
  processedAt: new Date(),
});

4. Error Recovery

Implement graceful error handling with meaningful responses:

try {
  await grantCredits(userId, convertedAmount);
} catch (error) {
  if (error.code === 'INSUFFICIENT_INVENTORY') {
    return {
      status: 'PENDING',
      responseText: "Processing your conversion. You'll be notified shortly.",
      responseDetails: { reason: 'INVENTORY_REPLENISHMENT' },
    };
  }

  // Log for manual intervention
  await logCriticalError({
    intentId,
    userId,
    error: error.message,
  });

  return {
    status: 'FAILED',
    responseText: 'Unable to complete conversion. Please contact support.',
    responseDetails: { errorCode: error.code },
  };
}

5. Conversion Metadata Usage

Leverage conversionMetadata for business logic:

async function applyConversionRules(userId: string, convertedAmount: number, metadata: any) {
  // Check for promotion codes
  if (metadata?.promotionId) {
    const promo = await getPromotion(metadata.promotionId);
    if (promo?.active) {
      convertedAmount *= promo.multiplier;
    }
  }

  // Apply user tier bonuses
  if (metadata?.tier === 'gold') {
    convertedAmount *= 1.1; // 10% bonus for gold tier
  }

  return convertedAmount;
}

6. Timeout Handling

Set appropriate timeouts for synchronous processing:

app.post('/webhooks/c2c', async (req, res) => {
  // Set 25-second timeout (leave buffer for Lucra's timeout)
  const timeout = setTimeout(() => {
    if (!res.headersSent) {
      res.status(200).json({
        status: 'PENDING',
        responseText: "Processing your conversion. You'll be notified when complete.",
        responseDetails: { reason: 'TIMEOUT' },
      });
    }
  }, 25000);

  try {
    const response = await handleC2CWithdrawal(req.body);
    clearTimeout(timeout);
    res.status(200).json(response);
  } catch (error) {
    clearTimeout(timeout);
    // Handle error
  }
});

TypeScript Types

interface C2CWithdrawalPayload {
  intentId: string;
  userId: string;
  amount: number;
  convertedAmount: number;
  conversionMetadata: Record<string, any> | null;
}

interface C2CResponse {
  status: 'COMPLETED' | 'FAILED' | 'PENDING';
  responseText: string;
  responseDetails?: any;
}

interface C2CTransactionRecord {
  intentId: string;
  userId: string;
  amount: number;
  convertedAmount: number;
  status: 'COMPLETED' | 'FAILED' | 'PENDING';
  response: C2CResponse;
  processedAt: Date;
  completedAt?: Date;
}

Security Considerations

1. Signature Verification: Always verify webhook signatures per Webhook Setup

2. HTTPS Only: C2C webhooks must be received over HTTPS

3. Idempotency: Use intentId to prevent duplicate credit grants

4. User Validation: Verify user exists and is eligible before granting credits

5. Rate Limiting: Prevent abuse by limiting conversions per user per time period

6. Audit Logging: Log all transactions for compliance and fraud detection

Testing

Test Payload

{
  "intentId": "test-5a31e00a-a2b8-4cdc-80cb-3ce3312f8023",
  "userId": "test-user-7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "amount": 10,
  "convertedAmount": 12,
  "conversionMetadata": {
    "environment": "sandbox",
    "testMode": true
  }
}

Related Documentation

• Webhook Setup - Webhook subscription and signature verification

• API Setup - API credentials and authentication

• Free-to-Play Webhooks - Similar webhook pattern for FTP rewards