🚧 Bloque documentation is under development
close
Bloque Docs
  • English

      • Error Handling

      Learn how to handle errors gracefully in Bloque Payments.

      Error Types

      Bloque Payments can return different types of errors:

      • Validation errors: Invalid input data
      • Authentication errors: Invalid or revoked API key
      • Payment errors: Payment processing failures
      • Network errors: Connection issues

      Frontend Error Handling

      Use the onError callback to handle errors in the React component:

      import { init, BloqueCheckout } from '@bloque/payments-react';

init({
  publishableKey: 'pk_live_...',
  mode: 'production',
});

function CheckoutPage({ checkoutId }) {
  return (
    <BloqueCheckout
      checkoutId={checkoutId}
      onSuccess={(data) => {
        console.log('Payment successful!', data.payment_id);
        window.location.href = '/success';
      }}
      onError={(error) => {
        console.error('Payment failed:', error);

        // Show user-friendly message
        alert(`Payment failed: ${error}`);
      }}
      onPending={(data) => {
        console.log('Payment pending:', data.payment_id);
        window.location.href = '/pending';
      }}
    />
  );
}

      Backend Error Handling

      Handle errors when creating checkouts:

      import { Bloque } from '@bloque/payments';
import express from 'express';

const app = express();
app.use(express.json());

const bloque = new Bloque({
  secretKey: process.env.BLOQUE_SECRET_KEY!,
  mode: 'production',
});

app.post('/api/create-checkout', async (req, res) => {
  try {
    const checkout = await bloque.checkout.create({
      name: req.body.name,
      items: req.body.items,
      success_url: req.body.success_url,
    });

    res.json({
      id: checkout.id,
      url: checkout.url,
      clientSecret: checkout.client_secret,
    });
  } catch (error) {
    console.error('Checkout error:', error);

    if (error.status === 400) {
      return res.status(400).json({
        success: false,
        error: 'Invalid checkout data',
        message: error.message,
      });
    }

    if (error.status === 401) {
      return res.status(401).json({
        success: false,
        error: 'Unauthorized',
        message: 'Invalid or revoked API key',
      });
    }

    res.status(500).json({
      success: false,
      error: 'Internal server error',
    });
  }
});

app.listen(3000);

      Common Error Codes

      Card Errors

      • card_declined: Card was declined
      • insufficient_funds: Not enough funds
      • invalid_card_number: Invalid card number
      • invalid_expiry: Invalid expiration date
      • invalid_cvv: Invalid security code

      3D Secure Errors

      • 3ds_challenge_cancelled: User cancelled the 3D Secure verification
      • 3ds_challenge_failed: 3D Secure authentication failed

      API Key Errors

      • E_KEY_REVOKED: The secret key has been revoked
      • E_INVALID_KEY: The secret key is invalid

      General Errors

      • invalid_amount: Invalid payment amount
      • invalid_currency: Unsupported currency
      • expired_checkout: Checkout session expired

      User-Friendly Messages

      Provide clear, actionable error messages:

      function getErrorMessage(errorCode: string): string {
  switch (errorCode) {
    case 'card_declined':
      return 'Your card was declined. Please try another payment method or contact your bank.';

    case 'insufficient_funds':
      return 'Your card has insufficient funds. Please try another card.';

    case 'invalid_card_number':
      return 'The card number you entered is invalid. Please check and try again.';

    case 'expired_card':
      return 'Your card has expired. Please use a different card.';

    case 'invalid_cvv':
      return 'The security code (CVV) you entered is invalid.';

    case 'bank_unavailable':
      return 'The selected bank is temporarily unavailable. Please try again later.';

    case 'expired_checkout':
      return 'The payment session has expired. Please start a new one.';

    case '3ds_challenge_cancelled':
      return '3D Secure verification was cancelled. Please try again.';

    case '3ds_challenge_failed':
      return '3D Secure authentication failed. Please try a different card or contact your bank.';

    default:
      return 'Payment failed. Please try again or contact support.';
  }
}

      Next Steps