#Payment Methods

Bloque Payments supports multiple payment methods to give your customers flexibility in how they pay.

#Available Payment Methods

#Card Payments

Accept credit and debit card payments from major card networks.

Supported Cards:

• Visa
• Mastercard
• American Express
• Diners Club

Features:

• Real-time authorization
• 3D Secure support
• Automatic card validation
• CVV verification

Integration Example:

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

<BloqueCheckout
  config={{
    payment_methods: ['card'],
    amount: 1999,
    currency: 'USD',
  }}
  requireEmail={true}
  onSubmit={handleSubmit}
/>

Card Payment Data:

{
  type: 'card',
  data: {
    cardNumber: string;        // 16-digit card number
    cardholderName: string;    // Name on card
    expiryMonth: string;       // MM format
    expiryYear: string;        // YY or YYYY format
    cvv: string;               // 3-4 digit security code
    email?: string;            // Customer email (optional)
  }
}

#PSE (Colombian Online Banking)

PSE (Pagos Seguros en Línea) is Colombia's most popular online banking payment method.

Features:

• Direct bank account transfers
• Real-time payment confirmation
• Support for all major Colombian banks
• Secure authentication through bank portals

Integration Example:

<BloqueCheckout
  config={{
    payment_methods: ['pse'],
    amount: 1999,
    currency: 'USD',
  }}
  onSubmit={handleSubmit}
/>

PSE Payment Data:

{
  type: 'pse',
  data: {
    personType: 'natural' | 'juridica';  // Person or company
    documentType: string;                 // ID type (CC, NIT, etc.)
    documentNumber: string;               // ID number
    bankCode: string;                     // Bank identifier
    email: string;                        // Customer email
  }
}

Supported Banks:

The component automatically loads all available Colombian banks. Some popular ones include:

• Bancolombia
• Banco de Bogotá
• BBVA Colombia
• Davivienda
• Banco de Occidente

#Cash Payments

Generate payment receipts for customers to pay at physical locations.

Features:

• Generate unique payment codes
• Multiple payment locations
• Extended payment deadlines
• Automatic confirmation

Integration Example:

<BloqueCheckout
  config={{
    payment_methods: ['cash'],
    amount: 1999,
    currency: 'USD',
  }}
  onSubmit={handleSubmit}
/>

Cash Payment Data:

{
  type: 'cash',
  data: {
    email: string;            // Customer email
    documentType: string;     // ID type
    documentNumber: string;   // ID number
    fullName: string;         // Full name
  }
}

Payment Locations:

Cash payments can be made at various locations including:

• Efecty
• Baloto
• Su Red
• Apostar
• Paga Todo

#Configuring Available Methods

You can configure which payment methods to offer:

#All Methods (Default)

<BloqueCheckout
  config={{
    payment_methods: ['card', 'pse', 'cash'],
    amount: 1999,
    currency: 'USD',
  }}
  onSubmit={handleSubmit}
/>

#Cards Only

<BloqueCheckout
  config={{
    payment_methods: ['card'],
    amount: 1999,
    currency: 'USD',
  }}
  requireEmail={true}
  onSubmit={handleSubmit}
/>

#PSE Only

<BloqueCheckout
  config={{
    payment_methods: ['pse'],
    amount: 1999,
    currency: 'USD',
  }}
  onSubmit={handleSubmit}
/>

#Cards and PSE

<BloqueCheckout
  config={{
    payment_methods: ['card', 'pse'],
    amount: 1999,
    currency: 'USD',
  }}
  onSubmit={handleSubmit}
/>

#Payment Method Selection

The BloqueCheckout component includes a built-in payment method selector when multiple methods are available:

<BloqueCheckout
  config={{
    payment_methods: ['card', 'pse', 'cash'],
    amount: 1999,
    currency: 'USD',
  }}
  showMethodSelector={true}  // Show method selector (default)
  onSubmit={handleSubmit}
/>

To hide the selector and default to the first method:

<BloqueCheckout
  config={{
    payment_methods: ['card'],
    amount: 1999,
    currency: 'USD',
  }}
  showMethodSelector={false}  // Hide selector
  onSubmit={handleSubmit}
/>

#Payment Flow by Method

#Card Payment Flow

1. Customer enters card details
2. Client-side validation
3. Submit to your backend
4. Backend processes with Bloque API
5. Real-time authorization
6. Success/failure response

#PSE Payment Flow

1. Customer selects bank
2. Customer enters identification
3. Submit to your backend
4. Backend creates PSE transaction
5. Customer redirected to bank
6. Bank authentication
7. Payment confirmation
8. Webhook notification

#Cash Payment Flow

1. Customer enters personal details
2. Submit to your backend
3. Backend generates payment code
4. Customer receives payment instructions
5. Customer pays at physical location
6. Webhook notification on payment

#Handling Payment Responses

All payment methods use the same response structure:

<BloqueCheckout
  config={config}
  onSubmit={async (payload) => {
    const response = await fetch('/api/payments', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload),
    });
    return response.json();
  }}
  onSuccess={(response) => {
    console.log('Payment ID:', response.id);
    console.log('Status:', response.status);
    console.log('Method:', response.payment_method);

    // Redirect based on method
    if (response.payment_method === 'pse') {
      // PSE requires redirect
      window.location.href = response.redirect_url;
    } else {
      // Other methods complete immediately
      window.location.href = '/success';
    }
  }}
  onError={(error) => {
    console.error('Payment failed:', error.message);
  }}
/>

#Currency Support

Currently supported currency:

• COP (Colombian Peso)

All amounts should be specified in the smallest currency unit (cents for COP):

// $19.99 USD = 1999 cents
const config = {
  amount: 1999,
  currency: 'USD',
};

#Security

All payment methods are processed securely:

• Card payments: PCI-DSS compliant, card data never touches your servers
• PSE payments: Bank-level security with direct authentication
• Cash payments: Secure code generation and validation

#Next Steps

• React Integration - Set up BloqueCheckout component
• Webhooks - Handle payment notifications
• Error Handling - Handle payment errors