Overview

Caibo IPG uses a two-tier authentication system where merchants first authenticate through the Control Panel to generate API keys, then use those API keys to access payment APIs. This approach provides secure access management while maintaining ease of integration.

Authentication Architecture

Control Panel Authentication

The Caibo Control Panel (merchant back office) handles user authentication and API key management. Merchants log into the control panel to manage their account and generate API keys for programmatic access.

API Key Authentication

Generated API keys are used to authenticate requests to all Caibo IPG payment APIs. These keys are included in HTTP headers for secure API access.

Getting Started

Step 1: Access the Control Panel

Navigate to the Caibo Control Panel and log in with your merchant credentials. Login Endpoint: POST /auth/login Request:

{
  "email": "merchant@example.com",
  "password": "your-secure-password"
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expireDate": "2024-01-15T10:30:00Z"
}

Step 2: Generate API Key

Once logged into the control panel, navigate to your profile section to generate or regenerate your API key. API Key Generation Endpoint: PUT /users/{userId}/apikey Headers:

Authorization: Bearer {accessToken}

Response:

"caibo_live_sk_1234567890abcdef"

Step 3: Use API Key in Payment Requests

Include your API key in all payment API requests using the X-API-Key header. Example Payment Request:

curl -X POST \
  "https://apay.caibo.digital/payment-requests" \
  -H "X-API-Key: caibo_live_sk_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "EUR",
    "reference": "ORDER-12345"
  }'

API Key Management

Key Types

Caibo provides different API key types based on your environment:

Live Keys: caibo_live_sk_* - For production transactions
Test Keys: caibo_test_sk_* - For development and testing

Security Best Practices

Key Storage

Never expose API keys in client-side code or public repositories
Store keys securely in environment variables or secure configuration
Use different keys for different environments (development, staging, production)

Key Rotation

Regenerate keys regularly for enhanced security
Update all integrations when rotating keys
Monitor key usage through the control panel

Access Control

Limit key permissions to required operations only
Monitor API key usage for suspicious activity
Revoke compromised keys immediately

Regenerating API Keys

To regenerate your API key:

Log into the Control Panel
Navigate to Profile Settings
Click “Re-generate API Key”
Confirm the action (old key will be invalidated)
Update your integrations with the new key

Warning: Regenerating an API key immediately invalidates the previous key. Ensure all integrations are updated before regenerating.

Authentication Headers

Required Headers

All Caibo IPG API requests must include the following headers:

X-API-Key: your-api-key-here
Content-Type: application/json

Optional Headers

Additional headers for enhanced functionality:

X-Idempotency-Key: unique-request-id
X-Webhook-Signature: signature-for-verification

Error Handling

Authentication Errors

401 Unauthorized

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid or has been revoked"
}

Common Causes:

Invalid or expired API key
Missing X-API-Key header
Revoked or regenerated key

Resolution:

Verify your API key is correct
Check that the key hasn’t been regenerated
Ensure the header is properly formatted

403 Forbidden

{
  "error": "Insufficient permissions",
  "code": "INSUFFICIENT_PERMISSIONS", 
  "message": "Your API key does not have permission for this operation"
}

Common Causes:

API key lacks required permissions
Account limitations or restrictions
Suspended merchant account

Resolution:

Contact support to verify account status
Check account permissions in control panel
Ensure compliance with terms of service

Testing Authentication

Test Your API Key

Use this simple endpoint to verify your API key is working:

curl -X GET \
  "https://apay.caibo.digital/ping" \
  -H "X-API-Key: your-api-key-here"

Success Response:

{
  "status": "ok",
  "message": "API key is valid",
  "timestamp": "2024-01-15T10:30:00Z"
}

Webhook Authentication

For webhook endpoints, Caibo includes signature verification:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === expectedSignature;
}

Integration Examples

Node.js Example

const axios = require('axios');

const caiboClient = axios.create({
  baseURL: 'https://apay.caibo.digital',
  headers: {
    'X-API-Key': process.env.CAIBO_API_KEY,
    'Content-Type': 'application/json'
  }
});

// Create payment request
async function createPayment(paymentData) {
  try {
    const response = await caiboClient.post('/payment-requests', paymentData);
    return response.data;
  } catch (error) {
    if (error.response?.status === 401) {
      throw new Error('Invalid API key - please check your credentials');
    }
    throw error;
  }
}

PHP Example

<?php
class CaiboClient {
    private $apiKey;
    private $baseUrl = 'https://apay.caibo.digital';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    public function createPayment($paymentData) {
        $headers = [
            'X-API-Key: ' . $this->apiKey,
            'Content-Type: application/json'
        ];
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $this->baseUrl . '/payment-requests');
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($paymentData));
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode === 401) {
            throw new Exception('Invalid API key - please check your credentials');
        }
        
        return json_decode($response, true);
    }
}
?>

Python Example

import requests
import os

class CaiboClient:
    def __init__(self, api_key=None):
        self.api_key = api_key or os.getenv('CAIBO_API_KEY')
        self.base_url = 'https://apay.caibo.digital'
        self.headers = {
            'X-API-Key': self.api_key,
            'Content-Type': 'application/json'
        }
    
    def create_payment(self, payment_data):
        response = requests.post(
            f'{self.base_url}/payment-requests',
            json=payment_data,
            headers=self.headers
        )
        
        if response.status_code == 401:
            raise Exception('Invalid API key - please check your credentials')
        
        response.raise_for_status()
        return response.json()

# Usage
client = CaiboClient()
payment = client.create_payment({
    'amount': 100.00,
    'currency': 'EUR',
    'reference': 'ORDER-12345'
})

Troubleshooting

Common Issues

API Key Not Working

Verify key format - Should start with caibo_live_sk_ or caibo_test_sk_
Check environment - Ensure using correct key for environment
Confirm regeneration - Verify key hasn’t been regenerated recently

Control Panel Access Issues

Password reset - Use forgot password if needed
Account status - Verify account is active and in good standing
Browser issues - Clear cache and cookies, try different browser

Integration Problems

Header format - Ensure X-API-Key header is correctly formatted
HTTPS required - All requests must use HTTPS
Content-Type - Include application/json for POST requests

Getting Help

If you encounter authentication issues:

Check API Status - Visit status.caibo.digital for service status
Review Logs - Check your application logs for detailed error messages
Contact Support - Reach out to support@caibo.digital with:
- Your merchant ID
- Error messages and timestamps
- Steps to reproduce the issue

Next Steps

Payment Requests

Create your first payment request

Webhooks Setup

Configure real-time payment notifications

API Reference

Explore the complete API documentation

Control Panel Guide

Learn more about the merchant control panel

Customers

Payment Requests

​Overview

​Authentication Architecture

​Control Panel Authentication

​API Key Authentication

​Getting Started

​Step 1: Access the Control Panel

​Step 2: Generate API Key

​Step 3: Use API Key in Payment Requests

​API Key Management

​Key Types

​Security Best Practices

​Key Storage

​Key Rotation

​Access Control

​Regenerating API Keys

​Authentication Headers

​Required Headers

​Optional Headers

​Error Handling

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Testing Authentication

​Test Your API Key

​Webhook Authentication

​Integration Examples

​Node.js Example

​PHP Example

​Python Example

​Troubleshooting

​Common Issues

​API Key Not Working

​Control Panel Access Issues

​Integration Problems

​Getting Help

​Next Steps

Payment Requests

Webhooks Setup

API Reference

Control Panel Guide

Overview

Authentication Architecture

Control Panel Authentication

API Key Authentication

Getting Started

Step 1: Access the Control Panel

Step 2: Generate API Key

Step 3: Use API Key in Payment Requests

API Key Management

Key Types

Security Best Practices

Key Storage

Key Rotation

Access Control

Regenerating API Keys

Authentication Headers

Required Headers

Optional Headers

Error Handling

Authentication Errors

401 Unauthorized

403 Forbidden

Testing Authentication

Test Your API Key

Webhook Authentication

Integration Examples

Node.js Example

PHP Example

Python Example

Troubleshooting

Common Issues

API Key Not Working

Control Panel Access Issues

Integration Problems

Getting Help

Next Steps