Host-to-Host Integration

Overview

Host-to-Host (H2H) integration allows you to control the full payment flow from your backend. Your server communicates directly with PixelWave API to create operations and receive status updates via webhooks.

PayIn Flow

Merchant Server → POST /host2host/payin → PixelWave
                                              ↓
                                    Provider processes payment
                                              ↓
PixelWave → POST webhook → Merchant Server (status update)

Your server sends a PayIn request with the payment method, amount, and client data
PixelWave returns payment details (card number, phone, QR code, etc.)
You display the payment details to the customer
The customer makes the payment
PixelWave sends a webhook with the final status

PayOut Flow

Merchant Server → POST /host2host/payout → PixelWave
                                               ↓
                                     Provider processes payout
                                               ↓
PixelWave → POST webhook → Merchant Server (status update)

Your server sends a PayOut request with recipient details
PixelWave processes the payout through the provider
PixelWave sends a webhook with the final status

Example: Creating a PayIn

curl -X POST 'https://api.admin-pixelwave.com/host2host/payin' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentMethod": "toCard",
    "idTransactionMerchant": "order-12345",
    "amount": 5000,
    "clientID": "user-67890",
    "clientIP": "192.168.1.100",
    "clientDateCreated": "2025-01-15T10:30:00Z"
  }'

Response:

{
  "result": {
    "status": "success",
    "x-request-id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "codeError": "none",
    "codeErrorExt": "none",
    "message": ""
  },
  "data": {
    "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "dateAdded": "2025-01-15T10:30:01Z",
    "dateUpdated": "2025-01-15T10:30:01Z",
    "typeOperation": "payIn",
    "status": "in_progress",
    "idTransactionMerchant": "order-12345",
    "amountInitial": 5000,
    "amountRandomized": 0,
    "amount": 5000,
    "amountComission": 150,
    "currency": "RUB",
    "amountInCurrencyBalance": 62.50,
    "amountComissionInCurrencyBalance": 1.875,
    "exchangeRate": 80.00,
    "paymentDetailsData": {
      "nameMediator": "Ivanov Ivan",
      "paymentMethod": "toCard",
      "bankName": "Sberbank",
      "number": "4276 1234 5678 9012",
      "numberAdditional": null,
      "qRcode": null
    }
  },
  "totalNumberRecords": 0
}

Example: Creating a PayOut

curl -X POST 'https://api.admin-pixelwave.com/host2host/payout' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentMethod": "toCard",
    "idTransactionMerchant": "payout-12345",
    "amount": 3000,
    "number": "4276123456789012",
    "bankName": "Sberbank",
    "nameMediator": "Ivanov Ivan",
    "clientID": "user-67890",
    "clientIP": "192.168.1.100",
    "clientDateCreated": "2025-01-15T10:30:00Z"
  }'

Custom Webhook URL

You can set a per-operation webhook URL by including the integrationMerhcnatData object:

{
  "paymentMethod": "toCard",
  "idTransactionMerchant": "order-12345",
  "amount": 5000,
  "clientID": "user-67890",
  "clientIP": "192.168.1.100",
  "clientDateCreated": "2025-01-15T10:30:00Z",
  "integrationMerhcnatData": {
    "webHook": "https://your-server.com/pixelwave/callback"
  }
}

This overrides the default webhook URL configured in your merchant account.

Best Practices

Always generate a unique idTransactionMerchant for each operation
Store the returned id (platform ID) for status lookups
Implement idempotent webhook handling (you may receive the same webhook multiple times)
Always verify the operation status via the Operations API if unsure
Pass real client data (clientIP, clientID) for better fraud detection