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

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

{
  "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

{
  "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

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

Security

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

Error Prevention

Required Fields: Ensure all required fields are included based on payment method
Format Validation: Validate data formats (dates, phone numbers, emails)
Length Limits: Respect field length limitations
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

​H2H Request Structure

​API Specification

​Request Details

​Authentication Header

​Core Request Parameters

​Browser Info Object

​Browser Info Example

​Wallet Object

​Wallet Object Example

​Complete Request Examples

​Credit Card Payment

​Alternative Payment

​UPI Payment

​Google Pay Payment

​Apple Pay Payment

​Wallet Payment (Apple Pay Example)

​Best Practices

​Request Construction

​Security

​Error Prevention

​Next Steps