> ## 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.

# Credit Card Payments

> Complete guide to processing credit card payments through Host-to-Host API with 3D Secure support

# 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      | "[john@example.com](mailto:john@example.com)" |
| `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](https://api.example.com/webhook)"   |
| `successUrl`        | Success redirect URL      | NO       | "[https://shop.example.com/success](https://shop.example.com/success)" |
| `failureUrl`        | Failure redirect URL      | NO       | "[https://shop.example.com/failure](https://shop.example.com/failure)" |
| `browserInfo`       | 3DS browser information   | NO       | See browser info object                                                |

## Browser Info Object

For 3D Secure authentication, include browser information:

```json theme={null}
{
  "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

```json theme={null}
{
  "name": "John Doe",
  "number": "4111111111111111",
  "expiration": "12/25",
  "cvv": "123",
  "email": "john@example.com",
  "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

```javascript theme={null}
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 theme={null}
<?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

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

### Browser Info Collection

```javascript theme={null}
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

```json theme={null}
{
  "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

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

### User Experience

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

### Performance

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

## Next Steps

<Card title="3D Secure Integration" icon="shield-check" href="/h2h/3ds-integration">
  Learn about 3D Secure authentication implementation
</Card>

<Card title="Payment Status" icon="chart-line" href="/ipg/payment-requests/payment-status">
  Track credit card payment status
</Card>

<Card title="Webhooks" icon="webhook" href="/h2h/notifications">
  Handle payment status notifications
</Card>


## OpenAPI

````yaml POST /payments/creditCard/{id}
openapi: 3.0.4
info:
  title: FinHub API
  description: >-
    FinHub API provides services for the Caibo platform to support client's
    applications
  version: v1
servers:
  - url: https://apay.caibo.digital
    description: Caibo APay server (Test and Production share base; method IDs differ)
security: []
paths:
  /payments/creditCard/{id}:
    post:
      tags:
        - Payments
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - name: transaction3dsId
          in: query
          schema:
            type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              $ref: '#/components/schemas/CreditCardPayment'
          application/json:
            schema:
              $ref: '#/components/schemas/CreditCardPayment'
          text/json:
            schema:
              $ref: '#/components/schemas/CreditCardPayment'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreditCardPayment'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '424':
          description: Failed Dependency
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    CreditCardPayment:
      required:
        - address
        - city
        - country
        - cvv
        - email
        - expiration
        - name
        - number
        - phoneNumber
        - postalCode
        - state
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 0
          type: string
        number:
          maxLength: 19
          minLength: 8
          type: string
        expiration:
          minLength: 1
          pattern: ^\d{2}\/\d{2}$
          type: string
        cvv:
          maxLength: 4
          minLength: 3
          pattern: ^\d+$
          type: string
        email:
          maxLength: 100
          minLength: 0
          type: string
          format: email
        phoneNumber:
          maxLength: 14
          minLength: 10
          pattern: ^\d+$
          type: string
        address:
          maxLength: 100
          minLength: 0
          type: string
        city:
          maxLength: 50
          minLength: 0
          type: string
        state:
          minLength: 1
          type: string
        postalCode:
          maxLength: 10
          minLength: 0
          type: string
        country:
          maxLength: 2
          minLength: 2
          type: string
        captureDelayHours:
          maximum: 7
          minimum: 0
          type: integer
          format: int32
        browserInfo:
          $ref: '#/components/schemas/BrowserInfo'
        wallet:
          $ref: '#/components/schemas/CreditCardWallet'
        is3ds:
          type: boolean
        isSandbox:
          type: boolean
        ipAddress:
          type: string
          nullable: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    BrowserInfo:
      type: object
      properties:
        acceptHeader:
          type: string
          nullable: true
        colorDepth:
          type: string
          nullable: true
        ip:
          type: string
          nullable: true
        javaEnabled:
          type: boolean
        javascriptEnabled:
          type: boolean
        language:
          type: string
          nullable: true
        screenHeight:
          type: string
          nullable: true
        screenWidth:
          type: string
          nullable: true
        timezone:
          type: string
          nullable: true
        userAgent:
          type: string
          nullable: true
      additionalProperties: false
    CreditCardWallet:
      type: object
      properties:
        walletType:
          type: string
          nullable: true
        authenticationValue:
          type: string
          nullable: true
        xid:
          type: string
          nullable: true
        eci:
          type: string
          nullable: true
      additionalProperties: false

````