Xpay Merchant API (1.27.3)

Use the token issued in the merchant’s personal account to access the API. The token must be passed in the Authorization header.

Webhooks can let your integrations take an action in response to events that occur on Xpay.

Xpay submits a POST request to the designated webhook URL with information about changes in transaction statuses.

The User-Agent for the requests will xpay-webhook-agent.

To receive webhooks, use the Xpay Merchant dashboard to configure a Webhook URL in the Settings.

Exactly one webhook URL may be configured per account.

Your server should respond with status code 200 within 5 seconds. Otherwise, we consider the webhook not delivered. In this case, we make 3 attempts to send a webhook within 90 seconds.

{
  "webhook_id": "WCgVCMVcaYEXYieY58LA7f",
  "tx": {
    "geo": "RU",
    "tx_id": "98cgqgbJajJ3fwfAU3qhar",
    "tx_direction": "P2P_FIAT_IN",
    "tx_status": "TX_ACTIVE",
    "merchant_tx_id": "123",
    "merchant_client_id": "456",
    "payment_method": "BANK_CARD",
    "payment_system": "ALFABANK",
    "payment_requisite": "42111111111111",
    "payment_expires_at": "2024-12-27T09:03:37Z",
    "in_currency": "RUB",
    "in_amount": "5000.95",
    "in_amount_confirmed": "0",
    "out_currency": "USDT",
    "out_amount": "44.485921",
    "out_amount_confirmed": "0",
    "rate": "112.94",
    "created_at": "2024-12-27T08:03:37.654491Z",
    "updated_at": "2024-12-27T08:03:37.654491Z",
    "completed_at": null,
    "reference_id": "789",
    "is_manual_confirmed": false,
    "fee_pct": "10.5",
    "widget_id": "",
    "bank_code": "100000000008",
    "payment_requisite_full_name": "Иван Петров",
    "fee_amount_confirmed": "0",
    "fee_currency": "USDT"
  },
  "is_manual_sending": false
}

You can enable signature verification for webhooks in the Xpay Merchant dashboard and provide a secret key.

The webhook payload is signed with the HMAC-SHA256 algorithm.

Signature is passed in the X-Signature header.

Examples of signature generation in different languages

# Python
import hmac
import hashlib

def sign(payload, secret):
    return hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

// PHP
<?php

function sign($payload, $secret) {
    return hash_hmac('sha256', $payload, $secret);
}

// Go
package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func sign(payload, secret string) string {
    h := hmac.New(sha256.New, []byte(secret))
    h.Write([]byte(payload))
    return hex.EncodeToString(h.Sum(nil))
}

// C#
using System.Security.Cryptography;
using System.Text;

public string Sign(string payload, string secret)
{
    using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
    {
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
        return BitConverter.ToString(hash).Replace("-", "").ToLower();
    }
}

// JavaScript
const crypto = require('crypto');

function sign(payload, secret) {
    return crypto.createHmac('sha256', secret).update(payload).digest('hex');
}