Payment Form Integration

Overview

Payment Form integration lets you redirect customers to a PixelWave-hosted payment page. This is the simplest integration method — you create an operation and receive a payment form URL to redirect the customer to.

Flow

Customer → Merchant → POST /paymentform/prepare → PixelWave
                                                      ↓
                                              Returns form URL
                                                      ↓
Customer ← Redirect to payment form ← Merchant
                    ↓
         Customer completes payment
                    ↓
PixelWave → POST webhook → Merchant Server
                    ↓
Customer ← Redirect back ← PixelWave (optional)

Two Modes

1. Prepare Mode (Customer Selects Payment Method)

Use POST /paymentform/prepare when you want the customer to choose the payment method on the PixelWave form.

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

2. Full Mode (Pre-selected Payment Method)

Use POST /paymentform/full when you already know the payment method:

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

Response

Both modes return a linkPaymentForm URL:

{
  "result": {
    "status": "success",
    "x-request-id": "uuid",
    "codeError": "none",
    "codeErrorExt": "none",
    "message": ""
  },
  "data": {
    "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "typeOperation": "payIn",
    "status": "in_progress",
    "idTransactionMerchant": "order-12345",
    "amount": 5000,
    "currency": "RUB",
    "linkPaymentForm": "https://pf.admin-pixelwave.com/payment/f1e2d3c4-b5a6-7890-abcd-ef1234567890"
  },
  "totalNumberRecords": 0
}

Redirect the customer to the linkPaymentForm URL.

Redirect and Webhooks

You can configure a return URL and webhook via integrationMerhcnatData:

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

Best Practices

Use prepare mode for the best customer experience (they see all available methods)
Use full mode when you've already shown payment options in your own UI
Always implement webhook handling — do not rely on redirects for payment confirmation
The payment form URL is single-use and time-limited

Payment Form Integration

On this page