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

  • Cyrexa merchant account with API keys
  • Development environment (Node.js, Python, or PHP)
  • Webhook endpoint capability

​
Step 1: Environment Setup (2 minutes)

Set your environment variables: 
export YONOBI_H2H_ENDPOINT="https://gateway.cyrexa.comp/ipg/2.0/"
export YONOBI_API_KEY="your_sandbox_api_key"
export WEBHOOK_URL="https://your-server.com/webhook"

​
Step 2: Create Payment Request (3 minutes)

const axios = require('axios');

async function createPayment() {
  const response = await axios.post(
    `${process.env.YONOBI_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.YONOBI_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-cyrexa-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.YONOBI_H2H_ENDPOINT}/payment-requests/status/${paymentRequestId}`,
    {
      headers: {
        'X-API-Key': process.env.YONOBI_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

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!
⌘I