​

Overview

​

Supported Payment Providers

​

Major Payment Processors

​

sonect

• Standard Callback: POST /callbacks/sonect
• 3DS Callback: GET /callbacks/sonect3ds
• Chargeback Notifications: POST /callbacks/sonect-chargeback
• Refund Notifications: POST /callbacks/sonect-refund
• Use Case: European and global payment processing

​

SIBS

• Callback: GET /callbacks/sibs
• Region: Portugal and Iberian Peninsula
• Features: Local payment method support

​

Regional Processors

​

WiPay

• Standard Callback: POST /callbacks/wipay
• Hosted Page Callback: POST /callbacks/wipayhp
• Region: Caribbean

​

Cardcom

• Hosted Page Callback: POST /callbacks/cardcomhp
• Region: Israel

​

Specialized Processors

​

Spitman

• Standard Callback: POST /callbacks/spitman
• H2H Callback: POST /callbacks/spitmanh2h
• Features: Specialized payment processing

​

PayToro

• Callback: POST /callbacks/paytoro
• Features: Alternative payment methods

​

ChargeBlast

• Callback: POST /callbacks/chargeblast
• Features: High-risk payment processing

​

Vaultody

• Callback: POST /callbacks/vaultody
• Features: Cryptocurrency payments

​

Security & Authentication

​

3D Secure

• 3DS Callback: POST /callbacks/3ds
• Purpose: Handle 3D Secure authentication results
• Security: Enhanced transaction security

​

Callback Implementation

​

Setting Up Callbacks

1. Configure Webhook URLs: Set your notification URLs in payment requests
2. Handle HTTP Methods: Support both GET and POST methods as required
3. Verify Signatures: Validate callback authenticity using provider signatures
4. Process Asynchronously: Handle callbacks in background processes

​

Common Callback Data

• Transaction ID: Unique payment identifier
• Status: Payment status (success, failed, pending, etc.)
• Amount: Transaction amount and currency
• Timestamp: When the status change occurred
• Provider Data: Provider-specific information

​

Response Requirements

• HTTP 200: Always return 200 OK for successful processing
• Idempotency: Handle duplicate callbacks gracefully
• Timeout: Respond within provider timeout limits (usually 10-30 seconds)
• Retry Logic: Providers will retry failed callbacks

​

Testing Callbacks

​

Test Environment

• Test Callbacks: POST /callbacks/test/json, POST /callbacks/test/form, GET /callbacks/test/text
• Purpose: Test your callback handling implementation
• Formats: Support for JSON, form data, and plain text

​

Testing Strategy

1. Unit Tests: Test callback parsing and processing logic
2. Integration Tests: Test with actual provider test data
3. Error Scenarios: Test timeout, malformed data, and retry scenarios
4. Load Testing: Ensure callbacks can handle high volumes

​

Error Handling

​

Common Issues

• Network Timeouts: Implement proper timeout handling
• Malformed Data: Validate and sanitize callback data
• Duplicate Callbacks: Use idempotency keys to prevent duplicate processing
• Provider Downtime: Handle temporary provider unavailability

​

Best Practices

1. Logging: Log all callback attempts for debugging
2. Monitoring: Monitor callback success rates and response times
3. Alerting: Set up alerts for callback failures
4. Backup Processing: Implement alternative status checking methods

​

Security Considerations

​

Callback Verification

• IP Whitelisting: Restrict callbacks to known provider IPs
• Signature Validation: Verify callback signatures when available
• HTTPS Only: Always use HTTPS for callback endpoints
• Rate Limiting: Implement rate limiting to prevent abuse

​

Data Protection

• Sensitive Data: Never log sensitive payment information
• Encryption: Encrypt callback data in transit and at rest
• Access Control: Restrict access to callback processing systems

​

Integration Examples

​

Basic Callback Handler

app.post('/webhooks/payment-status', (req, res) => {
  try {
    const { transactionId, status, amount } = req.body;
    
    // Verify callback authenticity
    if (!verifySignature(req)) {
      return res.status(401).send('Unauthorized');
    }
    
    // Process payment status update
    await updatePaymentStatus(transactionId, status);
    
    // Always return 200 OK
    res.status(200).send('OK');
  } catch (error) {
    console.error('Callback processing error:', error);
    res.status(200).send('OK'); // Still return 200 to prevent retries
  }
});

​

Callback Data Processing

function processCallback(provider, data) {
  switch (provider) {
    case 'sonect':
      return processsonectCallback(data);
    case 'sibs':
      return processSibsCallback(data);
    default:
      throw new Error(`Unknown provider: ${provider}`);
  }
}

​

Monitoring & Analytics

​

Key Metrics

• Callback Success Rate: Percentage of successfully processed callbacks
• Response Time: Average callback processing time
• Retry Rate: Frequency of callback retries from providers
• Error Rate: Percentage of callback processing errors

​

Troubleshooting

• Failed Callbacks: Check logs for processing errors
• Missing Callbacks: Verify webhook URL configuration
• Delayed Callbacks: Monitor provider-side delays
• Duplicate Processing: Implement proper idempotency checks

​

Next Steps