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. For browser-side flows (the embedded checkout iframe), the API key is never sent to the browser. Instead the merchant backend exchanges it for a short-lived checkout session token scoped to a single payment request. See Checkout Session Tokens below.

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 server-to-server requests to Caibo IPG payment APIs. These keys are included in HTTP headers for secure API access. The apiKey is a long-lived bearer secret and must never appear in browser URLs, client-side code, or any value that can leave your server.

Checkout Session Token Authentication

For the embedded checkout iframe — where the merchant apiKey cannot be used directly — your backend mints a short-lived (15-minute) checkout session token that is bound to a single payment request. The browser uses that token to authenticate against a small allow-list of endpoints. See Checkout Session Tokens.

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.

Checkout Session Tokens (Browser-Side Flows)

The embedded checkout iframe runs in the customer’s browser, where the merchant apiKey cannot be used directly — leaking it would compromise the entire account. To authenticate the iframe safely, your backend exchanges the apiKey for a short-lived, scoped token:

Property	Merchant `apiKey`	Checkout session token
Lifetime	Long-lived (until rotated)	15 minutes
Scope	Full merchant API	One payment request + a small endpoint allow-list
Where to send it	`X-API-Key` header, server-to-server	`X-Checkout-Token` header, or `?token=` in iframe URL
Can it mint more tokens?	n/a	No

Minting a Token

Your backend calls the mint endpoint after creating the payment request:

curl -X POST \
  "https://apay.caibo.digital/payment-requests/{paymentRequestId}/checkout-session" \
  -H "X-API-Key: caibo_live_sk_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "token": "bhMlOWTW16rHxnmOugI9Uu1qNJk4IzD0-EZfGsRLJDU",
  "paymentRequestId": 17784899067150744,
  "expiresAt": "2026-05-11T13:25:33Z",
  "ttlSeconds": 900
}

Your server then returns { requestId, token } to the browser (over your own authenticated channel) and the frontend constructs:

https://pay.caibo.digital/main?requestId=REQUEST_ID&token=TOKEN

This URL is safe to use as the iframe src: a leak only compromises one payment request for 15 minutes, not the whole account.

Never pass apiKey= in the iframe URL. The legacy ?apiKey= parameter still works for backward compatibility but emits a console deprecation warning on every checkout-page load. Migrate to ?token= — exposing the apiKey to the browser is treated as a credential leak.

For the full reference (endpoint behavior, response shape, allow-listed endpoints, error codes, lifecycle), see the Mint a Checkout Session Token page.

Authentication Headers

Required Headers (server-to-server)

Most server-to-server Caibo IPG API requests must include the following headers:

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

Required Headers (embedded checkout)

Requests originating from inside the embedded checkout iframe authenticate with a checkout session token instead. The Caibo payment page sets this header automatically once it picks up ?token= from the iframe URL; you only need to set it manually if you call the API from a non-browser client using a token.

X-Checkout-Token: bhMlOWTW16rHxnmOugI9Uu1qNJk4IzD0-EZfGsRLJDU
Content-Type: application/json

Exactly one of X-API-Key or X-Checkout-Token is expected per request. If both are present, the checkout token takes precedence and the request is treated as a scoped (checkout_session) call.

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

Documentation Index

​Overview

​Authentication Architecture

​Control Panel Authentication

​API Key Authentication

​Checkout Session Token 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

​Checkout Session Tokens (Browser-Side Flows)

​Minting a Token

​Authentication Headers

​Required Headers (server-to-server)

​Required Headers (embedded checkout)

​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

Checkout Session Token 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

Checkout Session Tokens (Browser-Side Flows)

Minting a Token

Authentication Headers

Required Headers (server-to-server)

Required Headers (embedded checkout)

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