Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.caibo.digital/llms.txt

Use this file to discover all available pages before exploring further.

​
H2H Request Structure

Host-to-Host API requests use a standardized JSON structure with specific parameters for different payment methods. This guide covers all request components, authentication, and parameter requirements.

​
API Specification

​
Request Details

  • API Endpoint: Custom URL obtained from dashboard (varies by provider)
  • HTTP Method: POST
  • Content Type: application/json
  • Authentication: X-API-Key header with your API key

​
Authentication Header

X-API-Key: your-api-key-from-dashboard

​
Core Request Parameters

NameDescriptionRequired
nameDebit/credit card holder nameYES
numberDebit/credit card numberYES (for credit card payment)
NO (for alternative payment)
NO (for UPI payment)
NO (for Google Pay)
expirationDebit/credit card expiration date in format MM/YYYES (for credit card payment)
NO (for alternative payment)
NO (for UPI payment)
NO (for Google Pay)
cvvDebit/credit card CVV codeYES (for credit card payment)
NO (for alternative payment)
NO (for UPI payment)
NO (for Google Pay)
upiIdUPI identifierYES (for UPI payment)
NO (for credit card payment)
NO (for alternative payment)
NO (for Google Pay)
tokenGoogle Pay tokenYES (for Google Pay and Apple Pay)
NO (for UPI payment)
NO (for credit card payment)
NO (for alternative payment)
addressPayer addressYES
emailPayer email addressYES
phoneNumberPayer phone numberYES
cityPayer city nameYES
statePayer state name or code. For example, Florida or FLYES
postalCodePayer postal codeYES
countryPayer country 2-letter code by ISO-3166-1 alpha 2. For example, USYES
amountPayment amount. For example, 10.50YES
unitPayment currency. For example, USD, EUR, BTC, USDTYES
originDomainOrigin domain name where from is performing payment requestYES
referenceIdMerchant custom reference ID. Free text identifier to recognize a payment by merchant on receiving a payment notificationNO
notifyUrlWebhook URL to notify about a payment status. Overrides merchant level notify URL defined in a merchant profileNO
successUrlRedirect URL on success payment for payment request. Overrides merchant level notify URL defined in a merchant profileNO
failureUrlRedirect URL on fail payment for payment request. Overrides merchant level notify URL defined in a merchant profileNO
captureDelayHoursPayment capture delay in hours for credit card payments. Allows the values range 0 – 7. The value 0 means to capture a payment immediately.NO
browserInfoUser browser info for 3DS verification – browser info objectNO
walletUser Google or Apple wallet details – wallet objectYES (for wallet payment)
NO (for credit card payment or alternative payment)

​
Browser Info Object

The browserInfo object is used for 3D Secure verification and contains browser-specific information:
NameDescriptionRequired
browserAcceptHeaderRequest header parameter AcceptNO
browserLanguageBrowser languageNO
browserScreenHeightUser screen heightNO
browserScreenWidthUser screen widthNO
browserTZUser time zone offset in minutesNO
browserUserAgentRequest header parameter User-AgentNO
browserColorDepthBrowser color depthNO
browserIPUser IP addressNO
browserJavaEnabledBrowser Java enabled stateNO
browserJavascriptEnabledBrowser JavaScript enabled stateNO

​
Browser Info Example

{
  "browserAcceptHeader": "application/json, text/plain, */*",
  "browserColorDepth": "24",
  "browserIP": "127.0.0.1",
  "browserJavaEnabled": false,
  "browserJavascriptEnabled": true,
  "browserLanguage": "en-US",
  "browserScreenHeight": "1080",
  "browserScreenWidth": "1920",
  "browserTZ": "300",
  "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
}

​
Wallet Object

The wallet object contains digital wallet information for Google Pay and Apple Pay payments. All values should be obtained from Google Pay or Apple Pay wallets:
NameDescriptionRequired
authenticationValueWallet unencrypted authentication dataYES
walletTypeWallet type
G – Google wallet
A – Apple wallet		YES
xidWallet XIDNO
eciWallet ECIYES

​
Wallet Object Example

{
  "authenticationValue": "ABCDE12345FGHJK67890\u0012e",
  "walletType": "A",
  "xid": "11111",
  "eci": "05"
}

​
Complete Request Examples

​
Credit Card Payment

{
  "name": "Test User",
  "number": "4111111111111111",
  "expiration": "10/25",
  "cvv": "123",
  "email": "test.user@email.com",
  "phoneNumber": "1234567890",
  "address": "10 Unknown Street",
  "city": "Far Town",
  "state": "NA",
  "postalCode": "123456",
  "country": "US",
  "amount": 10.50,
  "unit": "USD",
  "originDomain": "example.com",
  "referenceId": "123-GA-456",
  "notifyUrl": "https://notify.me",
  "successUrl": "https://success.payment.com",
  "failureUrl": "http://fail.payment.com",
  "captureDelayHours": 0,
  "browserInfo": {
    "browserAcceptHeader": "application/json, text/plain, */*",
    "browserColorDepth": "24",
    "browserIP": "127.0.0.1",
    "browserJavaEnabled": false,
    "browserJavascriptEnabled": true,
    "browserLanguage": "en-US",
    "browserScreenHeight": "1080",
    "browserScreenWidth": "1920",
    "browserTZ": "300",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
  }
}

​
Alternative Payment

{
  "name": "Test User",
  "email": "test.user@email.com",
  "phoneNumber": "1234567890",
  "address": "10 Unknown Street",
  "city": "Far Town",
  "state": "NA",
  "postalCode": "123456",
  "country": "US",
  "amount": 10.50,
  "unit": "USD",
  "originDomain": "example.com",
  "referenceId": "123-GA-456",
  "notifyUrl": "https://notify.me",
  "successUrl": "https://success.payment.com",
  "failureUrl": "http://fail.payment.com"
}

​
UPI Payment

{
  "name": "Test User",
  "upiId": "upi-id",
  "email": "test.user@email.com",
  "phoneNumber": "1234567890",
  "address": "10 Unknown Street",
  "city": "Far Town",
  "state": "NA",
  "postalCode": "123456",
  "country": "US",
  "amount": 10.50,
  "unit": "USD",
  "originDomain": "example.com",
  "referenceId": "123-GA-456",
  "notifyUrl": "https://notify.me",
  "successUrl": "https://success.payment.com",
  "failureUrl": "http://fail.payment.com",
  "browserInfo": {
    "browserAcceptHeader": "application/json, text/plain, */*",
    "browserColorDepth": "24",
    "browserIP": "127.0.0.1",
    "browserJavaEnabled": false,
    "browserJavascriptEnabled": true,
    "browserLanguage": "en-US",
    "browserScreenHeight": "1080",
    "browserScreenWidth": "1920",
    "browserTZ": "300",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
  }
}

​
Google Pay Payment

{
  "name": "Test User",
  "token": "Google Pay token",
  "email": "test.user@email.com",
  "phoneNumber": "1234567890",
  "address": "10 Unknown Street",
  "city": "Far Town",
  "state": "NA",
  "postalCode": "123456",
  "country": "US",
  "amount": 10.50,
  "unit": "USD",
  "originDomain": "example.com",
  "referenceId": "123-GA-456",
  "notifyUrl": "https://notify.me",
  "successUrl": "https://success.payment.com",
  "failureUrl": "http://fail.payment.com",
  "browserInfo": {
    "browserAcceptHeader": "application/json, text/plain, */*",
    "browserColorDepth": "24",
    "browserIP": "127.0.0.1",
    "browserJavaEnabled": false,
    "browserJavascriptEnabled": true,
    "browserLanguage": "en-US",
    "browserScreenHeight": "1080",
    "browserScreenWidth": "1920",
    "browserTZ": "300",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
  }
}

​
Apple Pay Payment

{
  "name": "Test User",
  "token": "Apple Pay token",
  "email": "test.user@email.com",
  "phoneNumber": "1234567890",
  "address": "10 Unknown Street",
  "city": "Far Town",
  "state": "NA",
  "postalCode": "123456",
  "country": "US",
  "amount": 10.50,
  "unit": "USD",
  "originDomain": "example.com",
  "referenceId": "123-GA-456",
  "notifyUrl": "https://notify.me",
  "successUrl": "https://success.payment.com",
  "failureUrl": "http://fail.payment.com",
  "browserInfo": {
    "browserAcceptHeader": "application/json, text/plain, */*",
    "browserColorDepth": "24",
    "browserIP": "127.0.0.1",
    "browserJavaEnabled": false,
    "browserJavascriptEnabled": true,
    "browserLanguage": "en-US",
    "browserScreenHeight": "1080",
    "browserScreenWidth": "1920",
    "browserTZ": "300",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
  }
}

​
Wallet Payment (Apple Pay Example)

{
  "name": "Test User",
  "number": "4111111111111111",
  "expiration": "10/25",
  "email": "test.user@email.com",
  "phoneNumber": "1234567890",
  "address": "10 Unknown Street",
  "city": "Far Town",
  "state": "NA",
  "postalCode": "123456",
  "country": "US",
  "amount": 10.50,
  "unit": "USD",
  "originDomain": "example.com",
  "referenceId": "123-GA-456",
  "notifyUrl": "https://notify.me",
  "successUrl": "https://success.payment.com",
  "failureUrl": "http://fail.payment.com",
  "browserInfo": {
    "browserAcceptHeader": "application/json, text/plain, */*",
    "browserColorDepth": "24",
    "browserIP": "127.0.0.1",
    "browserJavaEnabled": false,
    "browserJavascriptEnabled": true,
    "browserLanguage": "en-US",
    "browserScreenHeight": "1080",
    "browserScreenWidth": "1920",
    "browserTZ": "300",
    "browserUserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"
  },
  "wallet": {
    "authenticationValue": "ABCDE12345FGHJK67890\u0012e",
    "walletType": "A",
    "xid": "11111",
    "eci": "05"
  }
}

​
Best Practices

​
Request Construction

  1. Parameter Validation: Validate all required parameters before sending requests
  2. Data Sanitization: Sanitize input data to prevent injection attacks
  3. Currency Formatting: Use proper decimal formatting for amounts
  4. Country Codes: Use ISO-3166-1 alpha-2 country codes

​
Security

  1. HTTPS Only: Always use HTTPS for API requests
  2. API Key Protection: Never expose API keys in client-side code
  3. Data Encryption: Encrypt sensitive data before transmission
  4. Request Signing: Consider implementing request signing for additional security

​
Error Prevention

  1. Required Fields: Ensure all required fields are included based on payment method
  2. Format Validation: Validate data formats (dates, phone numbers, emails)
  3. Length Limits: Respect field length limitations
  4. Character Encoding: Use UTF-8 encoding for all text fields

​
Next Steps

Response Structure

Learn about H2H API response format and handling

Payment Methods

Explore available payment methods and implementations

Notifications

Set up webhook notifications for payment status updates