Credit Card Payments

Process credit card payments directly through the Host-to-Host API with full control over the payment flow, including 3D Secure authentication and advanced fraud protection.

Overview

Credit card processing through H2H API provides:

Direct Processing: Server-to-server credit card processing
3D Secure Support: Enhanced security with 3DS authentication
Multiple Card Types: Support for Visa, Mastercard, American Express, and more
Real-time Processing: Immediate payment processing and response
Fraud Protection: Advanced fraud detection and prevention

Required Parameters

Core Credit Card Fields

Parameter	Description	Required	Example
`name`	Card holder full name	YES	”John Doe”
`number`	Credit card number	YES	”4111111111111111”
`expiration`	Card expiration (MM/YY)	YES	”12/25”
`cvv`	Card verification value	YES	”123”

Customer Information

Parameter	Description	Required	Example
`email`	Customer email address	YES	”[email protected]”
`phoneNumber`	Customer phone number	YES	”+1234567890”
`address`	Billing address	YES	”123 Main St”
`city`	Billing city	YES	”New York”
`state`	State or province	YES	”NY”
`postalCode`	ZIP or postal code	YES	”10001”
`country`	Country code (ISO 3166-1)	YES	”US”

Transaction Details

Parameter	Description	Required	Example
`amount`	Payment amount	YES	99.99
`unit`	Currency code	YES	”USD”
`originDomain`	Merchant domain	YES	”shop.example.com”
`referenceId`	Merchant reference	NO	”ORDER-12345”

Optional Parameters

Parameter	Description	Required	Example
`captureDelayHours`	Capture delay (0-7 hours)	NO	0
`notifyUrl`	Webhook notification URL	NO	”https://api.example.com/webhook”
`successUrl`	Success redirect URL	NO	”https://shop.example.com/success”
`failureUrl`	Failure redirect URL	NO	”https://shop.example.com/failure”
`browserInfo`	3DS browser information	NO	See browser info object

Browser Info Object

For 3D Secure authentication, include browser information:

{
  "browserAcceptHeader": "application/json, text/plain, */*",
  "browserColorDepth": "24",
  "browserIP": "192.168.1.100",
  "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"
}

Complete Request Example

{
  "name": "John Doe",
  "number": "4111111111111111",
  "expiration": "12/25",
  "cvv": "123",
  "email": "[email protected]",
  "phoneNumber": "+1234567890",
  "address": "123 Main Street",
  "city": "New York",
  "state": "NY",
  "postalCode": "10001",
  "country": "US",
  "amount": 99.99,
  "unit": "USD",
  "originDomain": "shop.example.com",
  "referenceId": "ORDER-12345",
  "notifyUrl": "https://api.example.com/webhook",
  "successUrl": "https://shop.example.com/success",
  "failureUrl": "https://shop.example.com/failure",
  "captureDelayHours": 0,
  "browserInfo": {
    "browserAcceptHeader": "application/json, text/plain, */*",
    "browserColorDepth": "24",
    "browserIP": "192.168.1.100",
    "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"
  }
}

Implementation Example

JavaScript/Node.js

async function processCreditCardPayment(paymentData) {
  const apiEndpoint = process.env.Caibo_H2H_ENDPOINT;
  const apiKey = process.env.Caibo_API_KEY;
  
  try {
    const response = await fetch(apiEndpoint, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': apiKey
      },
      body: JSON.stringify({
        // Card details
        name: paymentData.cardholderName,
        number: paymentData.cardNumber,
        expiration: paymentData.expiryDate,
        cvv: paymentData.cvv,
        
        // Customer info
        email: paymentData.customerEmail,
        phoneNumber: paymentData.customerPhone,
        address: paymentData.billingAddress.street,
        city: paymentData.billingAddress.city,
        state: paymentData.billingAddress.state,
        postalCode: paymentData.billingAddress.postalCode,
        country: paymentData.billingAddress.country,
        
        // Transaction
        amount: paymentData.amount,
        unit: paymentData.currency,
        originDomain: paymentData.merchantDomain,
        referenceId: paymentData.orderId,
        
        // URLs
        notifyUrl: paymentData.webhookUrl,
        successUrl: paymentData.successUrl,
        failureUrl: paymentData.failureUrl,
        
        // 3DS
        browserInfo: paymentData.browserInfo
      })
    });
    
    const result = await response.json();
    
    if (response.ok) {
      return {
        success: true,
        paymentRequestId: result.paymentRequestId,
        redirectUrl: result.redirectUrl,
        status: result.status
      };
    } else {
      return {
        success: false,
        error: result.error,
        message: result.message
      };
    }
  } catch (error) {
    return {
      success: false,
      error: 'NETWORK_ERROR',
      message: error.message
    };
  }
}

PHP

<?php
function processCreditCardPayment($paymentData) {
    $apiEndpoint = $_ENV['Caibo_H2H_ENDPOINT'];
    $apiKey = $_ENV['Caibo_API_KEY'];
    
    $requestData = [
        // Card details
        'name' => $paymentData['cardholderName'],
        'number' => $paymentData['cardNumber'],
        'expiration' => $paymentData['expiryDate'],
        'cvv' => $paymentData['cvv'],
        
        // Customer info
        'email' => $paymentData['customerEmail'],
        'phoneNumber' => $paymentData['customerPhone'],
        'address' => $paymentData['billingAddress']['street'],
        'city' => $paymentData['billingAddress']['city'],
        'state' => $paymentData['billingAddress']['state'],
        'postalCode' => $paymentData['billingAddress']['postalCode'],
        'country' => $paymentData['billingAddress']['country'],
        
        // Transaction
        'amount' => $paymentData['amount'],
        'unit' => $paymentData['currency'],
        'originDomain' => $paymentData['merchantDomain'],
        'referenceId' => $paymentData['orderId'],
        
        // URLs
        'notifyUrl' => $paymentData['webhookUrl'],
        'successUrl' => $paymentData['successUrl'],
        'failureUrl' => $paymentData['failureUrl'],
        
        // 3DS
        'browserInfo' => $paymentData['browserInfo']
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $apiEndpoint);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestData));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    $result = json_decode($response, true);
    
    if ($httpCode === 200) {
        return [
            'success' => true,
            'paymentRequestId' => $result['paymentRequestId'],
            'redirectUrl' => $result['redirectUrl'] ?? null,
            'status' => $result['status']
        ];
    } else {
        return [
            'success' => false,
            'error' => $result['error'] ?? 'UNKNOWN_ERROR',
            'message' => $result['message'] ?? 'Payment processing failed'
        ];
    }
}
?>

3D Secure Authentication

3DS Flow

Initial Request: Submit payment with browser info
3DS Check: System determines if 3DS is required
Challenge: Customer completes 3DS challenge if needed
Final Processing: Payment processed after authentication

Browser Info Collection

function collectBrowserInfo() {
  return {
    browserAcceptHeader: navigator.userAgent,
    browserColorDepth: screen.colorDepth.toString(),
    browserIP: '', // Server-side detection
    browserJavaEnabled: navigator.javaEnabled(),
    browserJavascriptEnabled: true,
    browserLanguage: navigator.language,
    browserScreenHeight: screen.height.toString(),
    browserScreenWidth: screen.width.toString(),
    browserTZ: new Date().getTimezoneOffset().toString(),
    browserUserAgent: navigator.userAgent
  };
}

Error Handling

Common Error Codes

INVALID_CARD: Invalid card number or format
EXPIRED_CARD: Card has expired
INSUFFICIENT_FUNDS: Insufficient funds on card
CARD_DECLINED: Card declined by issuer
CVV_MISMATCH: CVV verification failed
3DS_FAILED: 3D Secure authentication failed

Error Response Example

{
  "success": false,
  "error": "CARD_DECLINED",
  "message": "The card was declined by the issuing bank",
  "code": "002",
  "details": {
    "declineReason": "Insufficient funds",
    "issuerResponse": "51"
  }
}

Security Best Practices

PCI DSS Compliance

Never Store: Never store card numbers, CVV, or expiration dates
Secure Transmission: Use HTTPS for all API communications
Data Minimization: Only collect necessary card data
Access Control: Restrict access to payment processing systems

Implementation Security

API Key Protection: Store API keys securely
Input Validation: Validate all input parameters
Error Handling: Don’t expose sensitive information in errors
Logging: Log transactions without sensitive data

Testing

Test Card Numbers

Card Type	Number	CVV	Expiry
Visa	4111111111111111	123	12/25
Mastercard	5555555555554444	123	12/25
American Express	378282246310005	1234	12/25

Test Scenarios

Successful Payment: Use valid test card numbers
Declined Payment: Use specific test numbers for declines
3DS Challenge: Test 3D Secure authentication flows
Network Errors: Test timeout and network failure scenarios

Best Practices

Implementation

Validation: Validate card data before API calls
Error Handling: Implement comprehensive error handling
Retry Logic: Use appropriate retry mechanisms
Monitoring: Monitor payment success rates

User Experience

Real-time Validation: Validate card details as user types
Clear Errors: Provide clear, actionable error messages
Loading States: Show processing indicators
Security Indicators: Display security badges and SSL indicators

Performance

Connection Pooling: Use HTTP connection pooling
Timeout Handling: Set appropriate timeout values
Async Processing: Handle responses asynchronously
Caching: Cache non-sensitive configuration data

Next Steps

3D Secure Integration

Learn about 3D Secure authentication implementation

Payment Status

Track credit card payment status

Webhooks

Handle payment status notifications

Path Parameters

integer<int64>

required

Query Parameters

transaction3dsId

string

Body

name

string

required

Maximum string length: 100

number

string

required

Required string length: 8 - 19

expiration

string

required

Minimum string length: 1

cvv

string

required

Required string length: 3 - 4

string<email>

required

Maximum string length: 100

phoneNumber

string

required

Required string length: 10 - 14

address

string

required

Maximum string length: 100

city

string

required

Maximum string length: 50

state

string

required

Minimum string length: 1

postalCode

string

required

Maximum string length: 10

country

string

required

Required string length: 2

captureDelayHours

integer<int32>

Required range: 0 <= x <= 7

browserInfo

object

Show child attributes

browserInfo.acceptHeader

string | null

browserInfo.colorDepth

string | null

browserInfo.ip

string | null

browserInfo.javaEnabled

boolean

browserInfo.javascriptEnabled

boolean

browserInfo.language

string | null

browserInfo.screenHeight

string | null

browserInfo.screenWidth

string | null

browserInfo.timezone

string | null

browserInfo.userAgent

string | null

wallet

object

Show child attributes

wallet.walletType

string | null

wallet.authenticationValue

string | null

wallet.xid

string | null

wallet.eci

string | null

is3ds

boolean

isSandbox

boolean

ipAddress

string | null

H2H Integration

​Credit Card Payments

​Overview

​Required Parameters

​Core Credit Card Fields

​Customer Information

​Transaction Details

​Optional Parameters

​Browser Info Object

​Complete Request Example

​Implementation Example

​JavaScript/Node.js

​PHP

​3D Secure Authentication

​3DS Flow

​Browser Info Collection

​Error Handling

​Common Error Codes

​Error Response Example

​Security Best Practices

​PCI DSS Compliance

​Implementation Security

​Testing

​Test Card Numbers

​Test Scenarios

​Best Practices

​Implementation

​User Experience

​Performance

​Next Steps

3D Secure Integration

Payment Status

Webhooks

Path Parameters

Query Parameters

Body

Response

Credit Card Payments

Overview

Required Parameters

Core Credit Card Fields

Customer Information

Transaction Details

Optional Parameters

Browser Info Object

Complete Request Example

Implementation Example

JavaScript/Node.js

PHP

3D Secure Authentication

3DS Flow

Browser Info Collection

Error Handling

Common Error Codes

Error Response Example

Security Best Practices

PCI DSS Compliance

Implementation Security

Testing

Test Card Numbers

Test Scenarios

Best Practices

Implementation

User Experience

Performance

Next Steps