Справочник API

Вебхуки

Заголовки доставки, полезные данные событий, повторные попытки и журналы доставки.

обратный вызов URL

Настройте обратный вызов команды URL в настройках интеграции разработчика. MakePay сначала проверяет конфигурацию продукта MakePay, а затем общую конфигурацию обратного вызова разработчика, чтобы существующие параметры webhooks MakeSwap могли получать события оплаты MakePay во время развертывания конфигурации для конкретного продукта.

Когда вы сохраняете обратный вызов URL MakePay, MakeCrypto генерирует секретный код webhook. Сохраните его в своем внутреннем менеджере секретов. Вы можете восстановить его в любое время на том же экране настроек; после его регенерации обновите серверную часть, прежде чем требовать подписи с новым секретом.

Поведение при доставке

MakePay отправляет оплату и подписку webhooks как запросы POST с телом JSON. Неудачные доставки повторяются до десяти раз с пятиминутными интервалами. Переадресация вручную доступна в журналах запросов webhook MakeCrypto.

Заголовки

content-type: application/json
user-agent: MakePay-Webhooks/1.0
x-makepay-delivery-id: 9f1c6cf4-8514-4ee5-80fd-8e8fe2b5e313
x-makepay-delivery-group-id: 9f1c6cf4-8514-4ee5-80fd-8e8fe2b5e313
x-makepay-delivery-origin: event
x-makepay-event: status_changed
x-makepay-attempt: 1
x-makepay-signature: t=1776556800,v1=7d4b3f...

Проверка подписей

MakePay подписывает точное необработанное тело JSON с помощью HMAC-SHA256. Подпись payload:

{timestamp}.{raw_request_body}

Заголовок x-makepay-signature содержит временную метку Unix и версионный дайджест:

t=1776556800,v1=<hex_hmac_sha256>

Пример проверки в Node.js:

import crypto from "node:crypto";

const WEBHOOK_SECRET = process.env.MAKEPAY_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 300;

export function verifyMakePayWebhook(input: {
  rawBody: string;
  signatureHeader: string | null;
}) {
  if (!input.signatureHeader) {
    return false;
  }

  const parts = Object.fromEntries(
    input.signatureHeader.split(",").map((part) => {
      const [key, value] = part.trim().split("=");
      return [key, value];
    }),
  );

  const timestamp = Number(parts.t);
  const signature = parts.v1;

  if (!Number.isFinite(timestamp) || !signature) {
    return false;
  }

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > TOLERANCE_SECONDS) {
    return false;
  }

  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(`${timestamp}.${input.rawBody}`, "utf8")
    .digest("hex");
  const actualBuffer = Buffer.from(signature, "hex");
  const expectedBuffer = Buffer.from(expected, "hex");

  return (
    actualBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(actualBuffer, expectedBuffer)
  );
}

Считывает необработанное тело перед анализом JSON. Если ваша платформа сначала анализирует тело, настройте путь webhook для предоставления необработанных байтов и проверьте эти байты, прежде чем доверять payload.

Полезная нагрузка платежа

{
  "deliveryId": "9f1c6cf4-8514-4ee5-80fd-8e8fe2b5e313",
  "type": "makepay.payment.status_changed",
  "createdAt": "2026-04-19T00:00:00.000Z",
  "event": {
    "type": "status_changed",
    "trigger": "payment_status_reconcile"
  },
  "paymentLink": {
    "id": "8d15bb78-d0f8-45ef-88d7-2a1f1f79644b",
    "uid": "01hzy4k6p4w9y2x7e2z7n8a2xm",
    "status": "active",
    "publicUrl": "https://makepay.io/payment/01hzy4k6p4w9y2x7e2z7n8a2xm",
    "expiresAt": "2026-04-19T12:00:00.000Z",
    "amount": "129.99",
    "currency": "USDT",
    "asset": "ETH.USDT-0xdac17f958d2ee523a2206206994597c13d831ec7",
    "label": "Website order #1042",
    "description": "Checkout for order #1042",
    "merchantOrderId": "order_1042",
    "clientEmail": "buyer@example.com",
    "clientId": null
  },
  "session": {
    "id": "5b55f0bb-0ac4-4f7c-a1d1-0d9af19c3bbd",
    "status": "complete",
    "previousStatus": "pending",
    "invoiceAsset": "USDT",
    "invoiceAmount": "129.99",
    "selectedSellAsset": "ETH",
    "requiredSellAmount": "0.04",
    "expectedBuyAmount": "129.99",
    "destinationAddress": "0xmerchant...",
    "depositAddress": "0xdeposit...",
    "channelId": "channel_123",
    "compositeChannelId": "ETH:channel_123",
    "sourceChain": "ETH",
    "expiresAt": "2026-04-19T00:30:00.000Z",
    "settlement": {},
    "errorMessage": null
  }
}

Типы событий

status_changed для изменения статуса платежного сеанса.
settlement_updated, когда данные расчета изменяются после сверки статуса.
payment_request_expired, quote_expired и payment_cancelled_by_payer для результатов терминала без оплаты.
channel_created, когда плательщик принимает котировку, и MakePay создает канал депозита.
subscription_status_changed, когда подписка MakePay перемещается между active, paused, overdue или cancelled.

quote_created и quote_refreshed являются внутренними событиями графика платежей и не отправляются на URL-адреса обратного вызова.

Полезная информация о состоянии подписки

MakePay также отправляет обратный вызов при изменении статуса подписки. Планировщик помечает подписку как overdue, когда самый старый неоплаченный цикл выставления счетов проходит как минимум через 24 часа после ее dueAt; Если ни один неоплаченный цикл не превышает эти 24 часа, планировщик перемещает подписку обратно на active. Изменения состояния из merchant и клиентского портала используют один и тот же обратный вызов.

{
  "deliveryId": "78c35c42-61fb-4dd3-94b7-2a7df998bb6f",
  "type": "makepay.subscription.status_changed",
  "createdAt": "2026-04-20T00:00:00.000Z",
  "event": {
    "type": "subscription_status_changed",
    "trigger": "subscription_scheduler"
  },
  "subscription": {
    "id": "f6b76460-a437-4a81-a59f-8fcbb18c0f0f",
    "uid": "sub_premium_001",
    "status": "overdue",
    "previousStatus": "active",
    "customerEmail": "buyer@example.com",
    "label": "Premium plan",
    "description": "Monthly subscription",
    "amountUsd": "49.99",
    "settlementAsset": "ETH.USDT-0xdac17f958d2ee523a2206206994597c13d831ec7",
    "cadence": "monthly",
    "billingIntervalUnit": "month",
    "billingIntervalCount": 1,
    "startAt": "2026-04-18T00:00:00.000Z",
    "timezone": "Asia/Dubai",
    "metadata": {
      "clientId": "client_1042"
    },
    "createdAt": "2026-04-18T00:00:00.000Z",
    "updatedAt": "2026-04-20T00:00:00.000Z"
  },
  "cycle": {
    "id": "f303b3b3-26d8-42bc-8c10-91fa1445f507",
    "subscriptionId": "f6b76460-a437-4a81-a59f-8fcbb18c0f0f",
    "sequence": 0,
    "dueAt": "2026-04-18T00:00:00.000Z",
    "amountUsd": "49.99",
    "paymentLinkId": "8d15bb78-d0f8-45ef-88d7-2a1f1f79644b",
    "paymentLinkUid": "01hzy4k6p4w9y2x7e2z7n8a2xm",
    "paymentUrl": "https://makepay.io/payment/01hzy4k6p4w9y2x7e2z7n8a2xm",
    "status": "overdue"
  },
  "data": {
    "previousStatus": "active",
    "nextStatus": "overdue",
    "reason": "cycle_one_day_overdue"
  }
}

Записи о доставке API

Используйте путь запроса webhook для проверки доставок и повторных попыток.

GET /api/partner/v1/makepay/webhook-requests?limit=100

Дополнительные фильтры включают paymentLinkUid, deliveryStatus и search.