Common Issues & Troubleshooting

1. Invalid SKU or Product Code

Cause: You're trying to buy a gift card that doesn't exist or has been removed from the catalog.

Real-World Example:

// ❌ Wrong: Using a hardcoded or outdated SKU
const response = await buyGiftCard({
  sku: "AMZN-US-50-OLD", // This SKU might be outdated
  amount: 50
});
// Result: "Invalid SKU" error

Fix:

Always fetch updated product data using GET /giftcard-trade/buy/config.
Verify the sku you're passing exists in the response.

// ✅ Correct: Fetch current SKUs first
const config = await fetch('/giftcard-trade/buy/config');
const availableProducts = config.products;

// Use a valid SKU from the response
const validSku = availableProducts[0].sku; // e.g., "AMZN-US-50-2024"
const response = await buyGiftCard({
  sku: validSku,
  amount: 50
});

2. Disabled Payment Method

Cause: The chosen payment method (e.g., Cedis) is temporarily disabled.

Real-World Example:

// ❌ User tries to pay with USDT but it's disabled
const paymentMethods = {
  "NAIRA": true,  
  "CEDIS": false // Temporarily disabled
};

// This will fail
const response = await buyGiftCard({
  sku: "AMZN-US-50-2024",
  paymentMethod: "CEDIS"
});
// Result: "Payment method disabled" error

Fix:

Check paymentMethodsAll in the configuration endpoint.
Only display methods that have "true" as their value.

// ✅ Correct: Filter available payment methods
const config = await fetch('/giftcard-trade/buy/config');
const availableMethods = Object.keys(config.paymentMethodsAll)
  .filter(method => config.paymentMethodsAll[method] === true);

// Show only: ["NAIRA", "CEDIS"]
renderPaymentOptions(availableMethods);

3. Insufficient Wallet Balance

Cause: Your Prestmit Naira or Cedis wallet doesn't have enough funds for the purchase.

Real-World Example:

// ❌ Attempting purchase without checking balance
const purchaseAmount = 25000; // ₦25,000
const walletBalance = 15000;   // Only ₦15,000 available

const response = await buyGiftCard({
  sku: "AMZN-US-50-2024",
  paymentMethod: "NAIRA"
});
// Result: "Insufficient funds" error

Fix:

Fund the wallet before retrying.
You can programmatically check balances using your wallet API endpoint.

4. Transaction Pending for Too Long

Cause: Network delay or the card is under manual review.

Fix:

Wait at least 5–15 minutes.
Check webhook events or use GET /giftcard-trade/buy/history to confirm progress.

// ✅ Correct: Implement proper status checking
const transactionId = response.transactionId;

// Poll status every 2 minutes instead of constant refreshing
const checkStatus = setInterval(async () => {
  const history = await fetch(`/giftcard-trade/buy/history?id=${transactionId}`);
  
  if (history.status === 'COMPLETED') {
    clearInterval(checkStatus);
    displayGiftCard(history.giftCardDetails);
  }
}, 120000); // Check every 2 minutes

// Stop checking after 15 minutes
setTimeout(() => clearInterval(checkStatus), 900000);

5. Transaction Rejected

Cause: Payment failure, stock unavailability, or invalid parameters.

Real-World Example:

// ❌ Transaction gets rejected
const response = await buyGiftCard({
  sku: "XBOX-US-25-2024",
  paymentMethod: "NAIRA",
  quantity: 1000 // Requesting too many cards
});

console.log(response.status); // "REJECTED"
console.log(response.rejectionReason); // "Quantity exceeds daily limit"

Fix:

Check the rejectionReason in the API response or history log.
Retry with valid inputs or select another product.

6. Webhook Not Received

Cause: Your webhook endpoint is unreachable or rejected the request.

Real-World Example:

// ❌ Webhook endpoint returns wrong status
app.post('/webhook/giftcard', (req, res) => {
  try {
    processGiftCardUpdate(req.body);
    res.status(201).send('Created'); // Wrong status code
  } catch (error) {
    res.status(500).send('Error');   // This will cause retries
  }
});

Fix:

Ensure you return HTTP 200 OK.
Verify your signature verification logic is correct.

// ✅ Correct: Proper webhook handling
app.post('/webhook/giftcard', (req, res) => {
  try {
    // Verify signature first
    const signature = req.headers['x-webhook-signature'];
    if (!verifySignature(req.body, signature)) {
      return res.status(401).send('Unauthorized');
    }

    processGiftCardUpdate(req.body);
    res.status(200).send('OK'); // Always return 200 for successful processing
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(200).send('OK'); // Still return 200 to stop retries
  }
});

Pro Tips

Caching Configuration Data

Always cache configuration data briefly (e.g., for 1 hour) and refresh periodically to stay synced with the live system:

// Cache implementation example
let configCache = null;
let cacheExpiry = 0;

async function getGiftCardConfig() {
  const now = Date.now();
  
  if (configCache && now < cacheExpiry) {
    return configCache; // Return cached data
  }
  
  // Fetch fresh data
  configCache = await fetch('/giftcard-trade/buy/config').then(r => r.json());
  cacheExpiry = now + (60 * 60 * 1000); // Cache for 1 hour
  
  return configCache;
}

Error Handling Best Practices

Implement comprehensive error handling to improve user experience:

async function safeBuyGiftCard(purchaseData) {
  try {
    const response = await buyGiftCard(purchaseData);
    return { success: true, data: response };
  } catch (error) {
    console.error('Gift card purchase failed:', error);
    
    return {
      success: false,
      error: error.message,
      retryable: ['network_error', 'timeout'].includes(error.code)
    };
  }
}