Caibo IPG API Documentation

Complete API reference and integration guide for Caibo's Integrated Payment Gateway. Access comprehensive documentation, code examples, and testing resources for seamless payment integration.

About Caibo IPG

Caibo IPG is a robust payment gateway solution that supports a wide range of payment methods including credit cards, digital wallets (Apple Pay, Google Pay), UPI payments, and alternative payment methods. Our platform is designed to handle high-volume transactions with enterprise-grade security and reliability.

Key Features

Quick Start

Get your first payment processed in minutes. Follow these four steps to integrate Caibo IPG into your application.

• 1

  Environment Setup

  Use a single base URL for both Test and Production environments.

  Server URL: https://apaycaibo.digital

  The base URL is identical for test and production. The only difference is which H2H payment method IDs are enabled for your tenant.

  H2H Method IDs: Test → 35  |  Live → 36

• 2

  Authentication

  All API requests require an API key passed via the X-API-Key header. Generate keys from your Caibo Control Panel under Settings → API Keys.

  HTTP

  POST https://apaycaibo.digital/payments/h2h/35
  Content-Type: application/json
  X-API-Key: your_api_key_here

• 3

  Create Your First Payment Request

  Send a payment request with the required fields. The response contains a requestId used in subsequent calls.

  JSON

  {
    "amount": 100.00,
    "unit": "USD",
    "referenceId": "ORDER-123",
    "notifyUrl": "https://your-site.com/webhook",
    "successUrl": "https://your-site.com/success",
    "failureUrl": "https://your-site.com/failure"
  }

• 4

  Handle Payment Processing

  Process payments using your preferred integration mode: redirect customers to hosted payment pages, integrate payment forms directly, or use server-to-server H2H integration.

Authentication

All API requests to Caibo IPG must be authenticated using API keys generated from the Caibo Control Panel. API keys are passed in the request header.

API Key Header

X-API-Key: your_secret_api_key

Generating API Keys

1. Log in to your Caibo Control Panel
2. Navigate to Settings → API Keys
3. Click Generate New Key
4. Copy and securely store the key — it will not be shown again

Rate Limiting

Environments

Caibo uses a single base URL for both sandbox and production. Switching environments is handled entirely by your API key and the H2H method ID you supply.

Payment Methods

Caibo IPG supports a comprehensive range of payment methods to meet diverse customer preferences across global markets.

Credit & Debit Cards

Full support for all major card networks with 3D Secure authentication and tokenization.

• Visa, Mastercard, American Express — major card networks
• 3D Secure (3DS 1.0 & 2.0) — enhanced chargeback protection
• Tokenization — secure card token storage for recurring payments
• Multi-Currency Processing — accept payments in multiple currencies
• Browser Fingerprinting — PCI compliance features built in

Credit Card Request Example

{
  "amount": 150.00,
  "unit": "USD",
  "referenceId": "ORDER-456",
  "payer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "country": "US",
      "zip": "10001"
    }
  },
  "card": {
    "number": "4111111111111111",
    "expiry": "12/26",
    "cvv": "123"
  },
  "notifyUrl": "https://your-site.com/webhook",
  "successUrl": "https://your-site.com/success",
  "failureUrl": "https://your-site.com/failure"
}

Digital Wallets

Seamless integration with Apple Pay and Google Pay for fast, secure checkout experiences.

• Apple Pay — Touch ID / Face ID support, encrypted payment tokens
• Google Pay — token-based security, seamless mobile experience
• Secure Token Processing — handle encrypted wallet payment tokens

Google Pay Request Example

{
  "amount": 75.00,
  "unit": "USD",
  "referenceId": "ORDER-789",
  "wallet": {
    "type": "google_pay",
    "token": "encrypted_google_pay_token_here"
  },
  "notifyUrl": "https://your-site.com/webhook"
}

Alternative Payment Methods

Non-card payment options including UPI, QR codes, and bank transfers.

• UPI (Unified Payments Interface) — instant real-time transfers, 24/7 availability, Indian market
• QR Code Payments — generate and process QR code-based payments
• Bank Transfers / ACH — direct bank account debits and transfers
• BNPL (Buy Now Pay Later) — flexible payment options for customers

UPI Request Example

{
  "amount": 500.00,
  "unit": "INR",
  "referenceId": "ORDER-UPI-001",
  "upi": {
    "id": "customer@paytm"
  },
  "notifyUrl": "https://your-site.com/webhook"
}

Integration Options

Choose the integration method that best fits your technical stack and business requirements.

Embedded Checkout SDK

The Caibo embedded checkout SDK renders the payment page inside your website using a secure iframe, without exposing your merchant API key to the browser.

How It Works

1. Create a payment request server-side → receive a requestId
2. Mint a short-lived checkout session token bound to that requestId
3. Initialize the SDK with CaiboCheckout.init() passing the token
4. Listen for postMessage events for success/failure

Quick Start — Inline Mode

<div id="caibo-checkout"></div>
<script src="https://js.caibo.digital/checkout.js"></script>
<script>
  CaiboCheckout.init({
    token: "SESSION_TOKEN_HERE",
    container: "#caibo-checkout",
    mode: "inline",
    onSuccess: (data) => console.log("Payment succeeded", data),
    onFailure: (err)  => console.log("Payment failed", err),
  });
</script>

Framework Examples

Copy-ready snippets are available for React, Angular, and Vue 3 — see the full documentation for each framework.

Host-to-Host (H2H) Integration

Direct server-to-server integration for merchants who want full control over the payment experience. All H2H requests use the same base URL and differ only by the method ID.

H2H Endpoint

Request Parameters

Payment-Specific Fields

H2H Notifications

Caibo sends webhook notifications to your notifyUrl when payment status changes. Verify each notification using HMAC-SHA512 signature verification.

{
  "event": "payment.success",
  "referenceId": "ORDER-123",
  "transactionId": "TXN-abc123",
  "amount": 100.00,
  "currency": "USD",
  "status": "COMPLETED",
  "timestamp": "2025-05-19T10:30:00Z",
  "signature": "hmac_sha512_signature_here"
}

Webhooks & Callbacks

Caibo sends real-time webhook notifications for all payment events. Configure your webhook endpoint in the Control Panel under Settings → Webhooks & Callbacks.

Signature Verification

Each webhook includes an X-Signature header containing an HMAC-SHA512 signature. Always verify this before processing the payload.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha512', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Supported Callback Types

• payment.success — payment completed successfully
• payment.failed — payment declined or failed
• payment.pending — payment awaiting confirmation
• payment.refunded — refund issued
• 3ds.required — 3D Secure authentication required
• 3ds.completed — 3DS flow completed

API Endpoints Overview

All endpoints use https://apaycaibo.digital as the base URL with the X-API-Key authentication header.

Payment Requests

Payments

Transactions

Customers

Sandbox & Testing

The sandbox environment mirrors production exactly — same endpoints, same schema, same error codes. No real money is moved. Use it to test all payment methods and error scenarios before going live.

Test Cards

Test UPI IDs

Testing Checklist

• API authentication with test key
• Payment creation for each method type
• Webhook delivery and signature verification
• 3DS authentication flow (triggered & completed)
• Payment status polling after creation
• Error handling for declined/expired cards
• Refund flow
• Load/stress testing before production launch

Merchant Control Panel

The Caibo Merchant Control Panel provides a full management interface for payment requests, transactions, customers, security settings, and API configuration.

API Keys

Generate and manage API keys for secure access to Caibo IPG APIs. Navigate to Settings → API Keys to create, rotate, or revoke keys. Always use separate keys for sandbox and production.

Transactions

View, filter, search, and export all transactions from the Transactions section. Available features:

• Transactions List — browse all transactions with full status and metadata
• Filters & Exports — filter by date, status, payment method, amount range; export CSV for reconciliation
• Reconciliation — match transactions against settlements with built-in tools
• Refunds & Reversals — initiate refunds directly from the transaction detail view

Customers

Manage customer profiles, view payment history, and check KYC verification status:

• Customers List — browse and search your customer base
• Customer Details — view a customer's profile, activity, and related payments
• KYC Statuses — understand customer verification indicators (if enabled for your tenant)

Security

• Origin Domains — restrict which website origins may initialize payment flows
• Webhook Signatures — verify webhook signatures to ensure callbacks originate from Caibo
• Roles & Permissions — control panel roles and what actions each can perform
• User Management — invite and manage team access

Analytics

• Analytics Overview — visualize payment performance with built-in charts and dashboards
• Saved Reports — create and manage saved analytics views for recurring reporting

Errors & Troubleshooting

All Caibo API errors follow a consistent structure with an HTTP status code and a JSON error body.

{
  "error": {
    "code": "INVALID_CARD_NUMBER",
    "message": "The card number provided is not valid.",
    "status": 422,
    "requestId": "req_abc123"
  }
}

HTTP Status Codes

Common Issues

• Webhook not received — verify your notifyUrl is publicly accessible and returns 200 within 10 seconds
• 3DS redirect loop — ensure browserInfo is complete and your success/failure URLs are reachable
• Card declined in sandbox — use the correct test card number for the scenario you are testing
• Rate limit hit — implement exponential backoff and reduce request frequency

Changelog

Version history, breaking changes, and deprecation policy for the Caibo H2H API.

Glossary

Merchant-friendly definitions for key terms used throughout this documentation.

H2H (Host-to-Host)

Direct server-to-server payment processing where your backend communicates directly with Caibo's API, giving you full control over the payment UI.

3DS / 3D Secure

An authentication protocol that adds an extra layer of security for online card transactions, reducing chargebacks. Supports 3DS 1.0 and 2.0.

Payment Request

A server-side object representing an intent to collect a payment. Contains amount, currency, reference ID, and redirect URLs.

Webhook / Callback

An HTTP POST notification sent by Caibo to your notifyUrl when a payment event occurs. Must be verified with HMAC-SHA512.

Tokenization

The process of replacing sensitive card data with a non-sensitive token that can be stored and used for recurring payments.

UPI (Unified Payments Interface)

India's real-time interbank payment system. Payments are identified by a UPI ID (e.g. customer@paytm) rather than card or bank details.

Tenant

Your merchant account on the Caibo platform. Each tenant has its own API keys, enabled payment methods, and Control Panel access.

Next Steps

Ready to integrate? Start with authentication, then explore the API reference and integration options.