Skip to main content

​
10-Minute H2H Quickstart

Get your first Host-to-Host payment running in under 10 minutes with this step-by-step guide.

​
Prerequisites

  • Caibo merchant account with API keys (Get API Keys)
  • Development environment (Node.js, Python, or PHP)
  • Webhook endpoint capability
Need API Keys? If you don’t have API keys yet, follow our Authentication Guide to learn how to log into the Control Panel and generate your API keys.

​
Step 1: Environment Setup (2 minutes)

Set your environment variables: 
export Caibo_H2H_ENDPOINT="https://apay.caibo.digital"
export Caibo_API_KEY="your_sandbox_api_key"
export WEBHOOK_URL="https://your-server.com/webhook"
Your API key should start with caibo_test_sk_ for sandbox or caibo_live_sk_ for production. Learn more about API key formats.

​
Step 2: Create Payment Request (3 minutes)

const axios = require('axios');

async function createPayment() {
  const response = await axios.post(
    `${process.env.Caibo_H2H_ENDPOINT}/payments/h2h/1`,
    {
      name: "John Doe",
      email: "john@example.com",
      phoneNumber: "+1234567890",
      address: "123 Main St",
      city: "New York",
      state: "NY",
      postalCode: "10001",
      country: "US",
      amount: 10.00,
      unit: "USD",
      originDomain: "localhost",
      notifyUrl: process.env.WEBHOOK_URL,
      successUrl: "http://localhost:3000/success",
      failureUrl: "http://localhost:3000/failure"
    },
    {
      headers: {
        'X-API-Key': process.env.Caibo_API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  
  console.log('Payment created:', response.data);
  return response.data;
}

createPayment();

​
Step 3: Handle Webhook (3 minutes)

const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-caibo-signature'];
  const payload = JSON.stringify(req.body);
  
  // Verify webhook signature
  const expectedSignature = crypto
    .createHmac('sha512', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  const { paymentRequestId, status, transactionId } = req.body;
  
  console.log(`Payment ${paymentRequestId} status: ${status}`);
  
  // Process payment status
  switch (status) {
    case 'completed':
      console.log('✅ Payment successful!');
      break;
    case 'failed':
      console.log('❌ Payment failed');
      break;
    case 'pending':
      console.log('⏳ Payment pending');
      break;
  }
  
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

​
Step 4: Check Payment Status (2 minutes)

async function checkPaymentStatus(paymentRequestId) {
  const response = await axios.get(
    `${process.env.Caibo_H2H_ENDPOINT}/payment-requests/status/${paymentRequestId}`,
    {
      headers: {
        'X-API-Key': process.env.Caibo_API_KEY
      }
    }
  );
  
  console.log('Payment status:', response.data);
  return response.data;
}

// Check status every 5 seconds
setInterval(() => {
  checkPaymentStatus('your_payment_request_id');
}, 5000);

​
Testing Your Integration

​
Test with Sandbox Data

Use these test values in sandbox: 
{
  "name": "Test User",
  "email": "test@example.com",
  "phoneNumber": "+1234567890",
  "amount": 10.00,
  "unit": "USD"
}

​
Expected Flow

  1. Payment Created → Status: pending
  2. User Completes Payment → Webhook received
  3. Payment Confirmed → Status: completed

​
Troubleshooting

​
Common Issues

IssueSolution
401 UnauthorizedCheck API key in X-API-Key header
400 Bad RequestValidate required fields
Webhook not receivedCheck webhook URL and firewall
Invalid signatureVerify webhook secret

​
Debug Checklist

  • ✅ API key is correct
  • ✅ Webhook URL is accessible
  • ✅ Webhook signature verification
  • ✅ Required fields provided
  • ✅ Amount format is correct

​
Next Steps

Authentication Guide

Learn about API key management and security

Credit Card Payments

Implement credit card processing

UPI Payments

Add UPI payment support

Testing Guide

Comprehensive testing scenarios

Error Handling

Handle errors and edge cases

​
Success! 🎉

You’ve successfully:
  • Created your first H2H payment request
  • Set up webhook handling with signature verification
  • Implemented payment status checking
  • Tested the complete payment flow
Your H2H integration is now ready for production!