Webhooks

Overview

PixelWave sends webhook notifications to your server when an operation's status changes. This is the primary way to track payment completion.

Configuration

Webhooks can be configured in two ways:

Account-level — Set a default webhook URL in your merchant account (via your PixelWave manager)
Per-operation — Pass integrationMerhcnatData.webHook when creating an operation (overrides account-level)

Webhook Request

PixelWave sends a POST request to your webhook URL.

Headers

Content-Type: application/json

Body

The webhook body has the same format as the standard API 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:35:00Z",
    "typeOperation": "payIn",
    "status": "success",
    "idTransactionMerchant": "order-12345",
    "amountInitial": 5000,
    "amountRandomized": 0,
    "amount": 5000,
    "amountComission": 150,
    "currency": "RUB",
    "amountInCurrencyBalance": 62.50,
    "amountComissionInCurrencyBalance": 1.875,
    "exchangeRate": 80.00
  },
  "totalNumberRecords": 0
}

Statuses

You will receive webhooks for the following status transitions:

Status	Description	Final?
`in_progress`	Operation is being processed	No
`success`	Payment completed successfully	Yes
`failed`	Payment failed or was cancelled	Yes

Expected Response

Your webhook endpoint must return an HTTP 200 status code to acknowledge receipt. Any other status code will trigger a retry.

HTTP/1.1 200 OK

Retry Policy

If your endpoint is unavailable or returns a non-200 status, PixelWave will retry the webhook delivery.

Implementation Example

Node.js / Express

app.post('/pixelwave/webhook', (req, res) => {
  const { result, data } = req.body;

  if (result.status !== 'success' || !data) {
    return res.sendStatus(200); // Acknowledge but ignore errors
  }

  const { id, status, idTransactionMerchant, amount, currency } = data;

  switch (status) {
    case 'success':
      // Payment completed — credit the user
      console.log(`Payment ${idTransactionMerchant} completed: ${amount} ${currency}`);
      break;
    case 'failed':
      // Payment failed — notify the user
      console.log(`Payment ${idTransactionMerchant} failed`);
      break;
    case 'in_progress':
      // Still processing — no action needed
      break;
  }

  res.sendStatus(200);
});

Python / Flask

@app.route('/pixelwave/webhook', methods=['POST'])
def webhook():
    payload = request.json
    result = payload.get('result', {})
    data = payload.get('data')

    if result.get('status') != 'success' or not data:
        return '', 200

    status = data.get('status')
    merchant_id = data.get('idTransactionMerchant')
    amount = data.get('amount')

    if status == 'success':
        # Payment completed
        process_successful_payment(merchant_id, amount)
    elif status == 'failed':
        # Payment failed
        handle_failed_payment(merchant_id)

    return '', 200

Best Practices

Idempotency — You may receive the same webhook multiple times. Use idTransactionMerchant or id to deduplicate.
Quick response — Return 200 immediately and process the payment asynchronously. Long-running webhook handlers may cause timeouts.
Verification — Always verify the operation status via the Operations API before crediting a user, as an additional security measure.
HTTPS — Your webhook endpoint must use HTTPS.
Logging — Log all incoming webhooks with the x-request-id for troubleshooting with support.

Webhooks

On this page