Card Payments H2H Integration¶

This guide covers H2H payment integration for international card payments (VISA, Mastercard). Card payments are processed instantly with support for 3D Secure authentication.

Overview¶

Payment Method: Card (VISA, Mastercard, American Express) Currencies: Multi-currency (USD, EUR, GBP, and more) User Experience: Customer enters card details directly on your website Authentication: 3D Secure (3DS) is required for enhanced security

Payment Flow¶

Initiate Payment: Call /h2h/initiate with card payment type and card details
Instant Processing: Payment is processed immediately (no QR codes or external redirects)
3DS Authentication Customer is redirected to their bank's 3DS page
Automatic Confirmation: Payment result is returned via IPN (Webhook) after 3DS completion
No Manual Verification: Card payments are either approved or declined - no proof submission needed

Important Differences from Local Payments

No QR codes or payment links - customer enters card details directly
No proof of payment - cards are approved/declined instantly
3DS is required - customer need to authenticate with their bank
Immediate results - no waiting period for automatic confirmation

HTTP Request¶

POST http://{{DOMAIN}}/h2h/initiate

Request Example¶

curl -X POST https://{{DOMAIN}}/h2h/initiate \
-H "Content-Type: application/json" \
-d '{
  "public_key": "your_api_key",
  "amount": 100.00,
  "currency": "USD",
  "payment_method_type": "card",
  "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "mobile": "+1234567890"
  },
  "card": {
      "number": "4111111111111111",
      "expiry_month": 12,
      "expiry_year": 2025,
      "cvv": "123",
      "holder": "John Doe",
      "type": "VISA"
  },
  "billing_address": {
      "country": "US",
      "address": "123 Main Street",
      "city": "New York",
      "postal_code": "10001"
  },
  "device_fingerprint": "unique_device_identifier",
  "details": "Payment for order #123",
  "identifier": "order_123_unique_id",
  "ipn_url": "https://yourdomain.com/ipn",
  "success_url": "https://yourdomain.com/success",
  "cancel_url": "https://yourdomain.com/cancel",
  "site_name": "Your Store"
}'

Response Examples¶

Success Response (No 3DS Required)¶

{
  "status": "success",
  "trx": "UUID",
  "payment_status": "success",
  "requires_3ds": false,
  "redirect_url": null,
  "message": "Payment processed successfully"
}

Response Requiring 3DS Authentication¶

{
  "status": "success",
  "trx": "UUID",
  "payment_status": "pending",
  "requires_3ds": true,
  "redirect_url": "https://3ds-authentication-url.com/auth/xyz123",
  "message": "3DS authentication required"
}

Declined Payment¶

{
  "status": "success",
  "trx": "UUID",
  "payment_status": "failed",
  "requires_3ds": false,
  "redirect_url": null,
  "message": "Card declined by issuer"
}

Request Parameters¶

Parameter	Required	Description	Example
public_key	true	Your API key	"your_api_key"
amount	true	Amount in specified currency	100.00, 250.50
currency	true	ISO currency code	"USD", "EUR", "GBP"
payment_method_type	true	Must be "card" for card payments	"card"
customer	true	Customer information	See Customer Parameters
card	true	Card details	See Card Parameters
billing_address	true	Billing address information	See Billing Address Parameters
device_fingerprint	true	Unique device identifier for fraud prevention	"unique_device_id"
details	true	Payment description (max 255 chars)	"Payment for order #123"
identifier	true	Unique payment ID (max 255 chars)	"order_123_unique_id"
ipn_url	true	Webhook URL for status updates	"https://yourdomain.com/ipn"
success_url	true	Success redirect URL	"https://yourdomain.com/success"
cancel_url	true	Cancel redirect URL	"https://yourdomain.com/cancel"
site_name	true	Your website name	"Your Store"
site_logo	false	Your logo URL	"https://yourdomain.com/logo.png"

Customer Parameters¶

Parameter	Required	Description	Example
first_name	true	Customer's first name	"John"
last_name	true	Customer's last name	"Doe"
email	true	Customer's email address	"[email protected]"
mobile	true	Customer's phone number	"+1234567890"

Card Parameters¶

Parameter	Required	Description	Example
number	true	Card number (12-19 digits, spaces allowed)	"4111111111111111"
expiry_month	true	Expiry month (1-12)	12
expiry_year	true	Expiry year (4 digits)	2025
cvv	true	Card security code (3-4 digits)	"123"
holder	true	Cardholder name (as on card)	"John Doe"
type	false	Card brand (auto-detected if omitted)	"VISA", "MASTERCARD", "AMEX"

Card Brand Auto-Detection

If you don't provide the type parameter, the system will automatically detect the card brand based on the card number. However, providing it explicitly can improve processing speed.

Billing Address Parameters¶

Parameter	Required	Description	Example
country	true	ISO country code (2 letters, uppercase)	"US", "GB", "DE"
address	false	Street address	"123 Main Street"
city	false	City name	"New York"
postal_code	false	Postal/ZIP code	"10001"

Response Parameters¶

Parameter	Description	Example
status	Request status	"success"
trx	Transaction ID for status checking and reference	"TRX123456789"
payment_status	Payment outcome	"success", "pending", "failed"
requires_3ds	Whether 3DS authentication is required	true, false
redirect_url	3DS authentication URL (only if requires_3ds is true)	"https://3ds-auth.com/..."
message	Human-readable payment status message	"Payment processed successfully"

Payment Status Values¶

Status	Description	Next Steps
success	Payment approved and completed	Order can be fulfilled
pending	3DS authentication in progress	Redirect customer to `redirect_url`
failed	Payment declined or failed	Show error to customer, allow retry

3D Secure (3DS) Authentication Flow¶

When requires_3ds is true, you must handle the 3DS authentication flow:

1. Redirect Customer to 3DS Page¶

if (response.requires_3ds) {
  // Redirect customer to their bank's authentication page
  window.location.href = response.redirect_url;
}

2. Customer Completes Authentication¶

Customer enters password/OTP on their bank's page
Bank validates authentication
Customer is redirected back to your success_url or cancel_url

3. Receive Final Status¶

You will receive the final payment status via: - IPN Webhook: Recommended - instant notification - Status Polling: Alternative - check payment status periodically

// Option 1: Wait for IPN notification (recommended)
// Your IPN handler will receive the final payment status

// Option 2: Poll status endpoint
async function pollPaymentStatus(trx) {
  const response = await fetch('/h2h/status', {
    method: 'POST',
    body: JSON.stringify({ public_key: 'your_key', trx: trx })
  });

  const data = await response.json();

  if (!data.requires_3ds) {
    // 3DS completed, check final status
    if (data.payment_status === 'success') {
      // Payment successful
    } else if (data.payment_status === 'failed') {
      // Payment failed
    }
  }
}

What to Expect¶

Processing Time¶

With 3DS: 30 seconds to 5 minutes (depends on customer authentication speed)

3DS Requirement¶

All transactions require 3DS confirmation for security reasons.

Approval Rates¶

Card payments are either approved or declined instantly
No manual verification or proof of payment required
Final decision from card issuer within seconds

Error Handling¶

Common Error Responses¶

Invalid Card Number

{
  "status": "error",
  "message": ["Card number is required"]
}

Expired Card

{
  "status": "error",
  "message": ["Card has expired"]
}

Invalid Expiry Month

{
  "status": "error",
  "message": ["Card expiry month must be between 1 and 12"]
}

No Card Gateway Available

{
  "status": "error",
  "message": ["No H2H flows available for this currency and merchant"]
}

Error Scenarios¶

Invalid Card Data: Ensure all card fields are properly formatted
Merchant Not Enabled: Contact support to enable card H2H payments
Currency Not Supported: Check supported currencies with support team
Billing Country Missing: Country code is required and must be ISO 2-letter format

Security Best Practices¶

PCI Compliance¶

Never log card numbers: Mask PAN in logs (only last 4 digits)
Use HTTPS: All API calls must be over encrypted connections
Device Fingerprinting: Always include device_fingerprint for fraud prevention
Validate on Client: Pre-validate card format before submitting to reduce errors

Fraud Prevention¶

Device Fingerprinting: Implement browser fingerprinting library
IP Verification: Ensure customer IP matches expected region
Velocity Checks: Limit number of payment attempts per customer
AVS Matching: Provide accurate billing address for address verification

Implementation Example¶

async function processCardPayment(cardData, customerData, orderInfo) {
  try {
    // 1. Collect card details from your payment form
    const requestData = {
      public_key: 'your_api_key',
      amount: orderInfo.amount,
      currency: orderInfo.currency,
      payment_method_type: 'card',
      customer: customerData,
      card: {
        number: cardData.number,
        expiry_month: parseInt(cardData.expiryMonth),
        expiry_year: parseInt(cardData.expiryYear),
        cvv: cardData.cvv,
        holder: cardData.holder
      },
      billing_address: cardData.billingAddress,
      device_fingerprint: getDeviceFingerprint(),
      details: orderInfo.description,
      identifier: orderInfo.orderId,
      ipn_url: 'https://yoursite.com/ipn',
      success_url: 'https://yoursite.com/success',
      cancel_url: 'https://yoursite.com/cancel',
      site_name: 'Your Store'
    };

    // 2. Send payment request
    const response = await fetch('/h2h/initiate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(requestData)
    });

    const result = await response.json();

    // 3. Handle response
    if (result.status === 'success') {
      if (result.requires_3ds) {
        // Redirect to 3DS authentication
        window.location.href = result.redirect_url;
      } else if (result.payment_status === 'success') {
        // Payment successful
        window.location.href = '/success?trx=' + result.trx;
      } else if (result.payment_status === 'failed') {
        // Payment declined
        showError(result.message);
      }
    } else {
      // API error
      showError(result.message);
    }
  } catch (error) {
    console.error('Payment error:', error);
    showError('Payment failed. Please try again.');
  }
}

function getDeviceFingerprint() {
  // Implement device fingerprinting
  // Use library like FingerprintJS or create custom implementation
  return 'device_' + Date.now() + '_' + Math.random();
}

Comparison with Local Payments¶

Feature	Card Payments	UPI/Bangladesh Wallets
Payment Instruments	VISA, Mastercard, AMEX	UPI apps, BKASH, NAGAD
Processing Time	Instant (1-5 seconds)	10-60 seconds
3DS Authentication	Yes	No
Proof of Payment	❌ Not supported	✅ Supported
QR Codes	❌ No	✅ Yes (UPI)
Payment Links	❌ No	✅ Yes
Manual Verification	❌ Never needed	✅ Sometimes (5-25%)
Currencies	Multi-currency	INR, BDT only
Geographic Coverage	Global	India, Bangladesh

Next Steps¶

Check Payment Status - Monitor payment progress and 3DS completion
IPN Integration - Receive automatic status updates
India (UPI) Integration - For India-specific payments
Bangladesh Integration - For Bangladesh payments
Back to H2H Overview