> ## 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 > Complete guide to Host-to-Host API request parameters, objects, and authentication # 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 ```http theme={null} X-API-Key: your-api-key-from-dashboard ``` ## Core Request Parameters | Name | Description | Required | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `name` | Debit/credit card holder name | YES | | `number` | Debit/credit card number | YES (for credit card payment)
NO (for alternative payment)
NO (for UPI payment)
NO (for Google Pay) | | `expiration` | Debit/credit card expiration date in format MM/YY | YES (for credit card payment)
NO (for alternative payment)
NO (for UPI payment)
NO (for Google Pay) | | `cvv` | Debit/credit card CVV code | YES (for credit card payment)
NO (for alternative payment)
NO (for UPI payment)
NO (for Google Pay) | | `upiId` | UPI identifier | YES (for UPI payment)
NO (for credit card payment)
NO (for alternative payment)
NO (for Google Pay) | | `token` | Google Pay token | YES (for Google Pay and Apple Pay)
NO (for UPI payment)
NO (for credit card payment)
NO (for alternative payment) | | `address` | Payer address | YES | | `email` | Payer email address | YES | | `phoneNumber` | Payer phone number | YES | | `city` | Payer city name | YES | | `state` | Payer state name or code. For example, Florida or FL | YES | | `postalCode` | Payer postal code | YES | | `country` | Payer country 2-letter code by ISO-3166-1 alpha 2. For example, US | YES | | `amount` | Payment amount. For example, 10.50 | YES | | `unit` | Payment currency. For example, USD, EUR, BTC, USDT | YES | | `originDomain` | Origin domain name where from is performing payment request | YES | | `referenceId` | Merchant custom reference ID. Free text identifier to recognize a payment by merchant on receiving a payment notification | NO | | `notifyUrl` | Webhook URL to notify about a payment status. Overrides merchant level notify URL defined in a merchant profile | NO | | `successUrl` | Redirect URL on success payment for payment request. Overrides merchant level notify URL defined in a merchant profile | NO | | `failureUrl` | Redirect URL on fail payment for payment request. Overrides merchant level notify URL defined in a merchant profile | NO | | `captureDelayHours` | Payment capture delay in hours for credit card payments. Allows the values range 0 – 7. The value 0 means to capture a payment immediately. | NO | | `browserInfo` | User browser info for 3DS verification – browser info object | NO | | `wallet` | User Google or Apple wallet details – wallet object | YES (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: | Name | Description | Required | | -------------------------- | ----------------------------------- | -------- | | `browserAcceptHeader` | Request header parameter Accept | NO | | `browserLanguage` | Browser language | NO | | `browserScreenHeight` | User screen height | NO | | `browserScreenWidth` | User screen width | NO | | `browserTZ` | User time zone offset in minutes | NO | | `browserUserAgent` | Request header parameter User-Agent | NO | | `browserColorDepth` | Browser color depth | NO | | `browserIP` | User IP address | NO | | `browserJavaEnabled` | Browser Java enabled state | NO | | `browserJavascriptEnabled` | Browser JavaScript enabled state | NO | ### Browser Info Example ```json theme={null} { "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: | Name | Description | Required | | --------------------- | -------------------------------------------------------- | -------- | | `authenticationValue` | Wallet unencrypted authentication data | YES | | `walletType` | Wallet type
G – Google wallet
A – Apple wallet | YES | | `xid` | Wallet XID | NO | | `eci` | Wallet ECI | YES | ### Wallet Object Example ```json theme={null} { "authenticationValue": "ABCDE12345FGHJK67890\u0012e", "walletType": "A", "xid": "11111", "eci": "05" } ``` ## Complete Request Examples ### Credit Card Payment ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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) ```json theme={null} { "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 Learn about H2H API response format and handling Explore available payment methods and implementations Set up webhook notifications for payment status updates