> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yonobi.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Callbacks & Webhooks

> Handle real-time payment notifications from various payment providers through Yonobi IPG callback system

# Overview

Yonobi IPG provides a comprehensive callback system to handle real-time payment status notifications from various payment providers. This ensures you receive immediate updates about payment status changes. The callback system supports notifications from multiple payment providers, each with their own endpoint and data format. All callbacks are processed asynchronously and provide real-time payment status updates.

## 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

Most callbacks include:

* **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

```javascript theme={null}
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

```javascript theme={null}
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

<Card title="Payment Status Reference" icon="chart-line" href="/ipg/payment-requests/payment-status">
  Learn about querying payment status directly
</Card>

<Card title="Webhook Troubleshooting" icon="exclamation-triangle" href="/cpanel/troubleshooting/webhook-debugging">
  Debug webhook delivery and signature issues
</Card>

<Card title="Webhook Signatures" icon="shield-check" href="/cpanel/security/webhook-signatures">
  Verify and secure callback authenticity
</Card>