Dokumentacja API

Webhooks

Nagłówki dostaw, ładunki zdarzeń, ponowne próby i dzienniki dostaw.

Adres URL wywołania zwrotnego

Skonfiguruj adres URL wywołania zwrotnego zespołu w ustawieniach integracji programistów. MakePay sprawdza najpierw ustawienia produktu MakePay, a następnie udostępnione ustawienia wywołania zwrotnego programisty, dzięki czemu istniejące ustawienia MakeSwap webhook mogą odbierać zdarzenia płatnicze MakePay podczas wdrażania ustawień specyficznych dla produktu.

Podczas zapisywania adresu URL wywołania zwrotnego MakePay MakeCrypto generuje klucz tajny webhook. Przechowuj go w menedżerze tajnych danych zaplecza. Możesz go zregenerować w dowolnym momencie na tym samym ekranie ustawień; po regeneracji zaktualizuj swój backend przed wymuszeniem podpisów nowym kluczem tajnym.

Zachowanie podczas dostawy

MakePay wysyła webhooks dotyczące płatności i subskrypcji jako żądania POST z treścią JSON. Dostawy, które nie powiodły się, są ponawiane maksymalnie dziesięć razy w odstępach pięciominutowych. Ręczne ponowne wysłanie jest dostępne w dziennikach żądań MakeCrypto webhook.

Nagłówki

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...

Sprawdź podpisy

MakePay podpisuje dokładnie surową treść żądania JSON za pomocą HMAC-SHA256. Ładunek podpisu to:

{timestamp}.{raw_request_body}

Nagłówek x-makepay-signature zawiera znacznik czasu Uniksa i skrót wersji:

t=1776556800,v1=<hex_hmac_sha256>

Przykładowa weryfikacja w 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)
  );
}

Przeczytaj surową treść przed analizą JSON. Jeśli struktura najpierw analizuje treść, skonfiguruj trasę webhook, aby udostępnić nieprzetworzone bajty żądania i zweryfikować te bajty przed zaufaniem ładunku.

Ładunek płatności

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

Typy wydarzeń

status_changed dla zmian stanu sesji płatniczej.
settlement_updated, gdy dane rozliczeniowe zmieniają się po uzgodnieniu statusu.
payment_request_expired, quote_expired i payment_cancelled_by_payer dla końcowych wyników braku płatności.
channel_created, gdy płatnik akceptuje ofertę, a MakePay tworzy kanał depozytowy.
subscription_status_changed, gdy subskrypcja MakePay zostanie przeniesiona pomiędzy active, paused, overdue lub cancelled.

quote_created i quote_refreshed to zdarzenia na osi czasu płatności wewnętrznych, które nie są wysyłane na adresy URL wywołania zwrotnego.

Ładunek stanu subskrypcji

MakePay wysyła także wywołanie zwrotne w przypadku zmiany statusu subskrypcji. Planista oznacza subskrypcję overdue, gdy wynosi co najmniej najstarszy nieopłacony cykl rozliczeniowy 24 godziny po dueAt; gdy żaden bezpłatny cykl nie jest opóźniony o więcej niż 24 godziny, program planujący przenosi subskrypcję z powrotem do active. Portal handlowy i klienta zmiany statusu korzystają z tego samego wywołania zwrotnego.

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

Dzienniki dostaw API

Użyj trasy żądania webhook, aby sprawdzić dostawy i ponowne próby.

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

Opcjonalne filtry obejmują paymentLinkUid, deliveryStatus i search.