MakeCrypto

API-Referenz

Webhooks

Zustellungsheader, Ereignisnutzlasten, Wiederholungsversuche und Zustellungsprotokolle.

Rückruf-URL

Konfigurieren Sie die Team-Rückruf-URL in den Entwicklerintegrationseinstellungen. MakePay überprüft zuerst die Produkteinstellungen MakePay und dann die gemeinsamen Entwickler-Callback-Einstellungen, sodass bestehende MakeSwap-Webhook-Einstellungen MakePay-Zahlungsereignisse empfangen können, während die produktspezifische Einstellung eingeführt wird.

Wenn Sie eine MakePay-Rückruf-URL speichern, generiert MakeCrypto ein Webhook-Geheimnis. Speichern Sie es in Ihrem Backend-Secret-Manager. Sie können es jederzeit über denselben Einstellungsbildschirm neu generieren. Aktualisieren Sie nach der Regeneration Ihr Backend, bevor Sie Signaturen mit dem neuen Geheimnis erzwingen.

Lieferverhalten

MakePay sendet Zahlungs- und Abonnement-Webhooks als POST-Anfragen mit einem JSON-Body. Fehlgeschlagene Zustellungen werden bis zu zehn Mal im Abstand von fünf Minuten wiederholt. Manuelles erneutes Senden ist in den MakeCrypto-Webhook-Anforderungsprotokollen verfügbar.

Überschriften

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

Signaturen überprüfen

MakePay signiert den genauen rohen JSON-Anfragetext mit HMAC-SHA256. Die Signaturnutzlast ist:

{timestamp}.{raw_request_body}

Der x-makepay-signature-Header enthält den Unix-Zeitstempel und den versionierten Digest:

t=1776556800,v1=<hex_hmac_sha256>

Beispielverifizierung in 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)
  );
}

Lesen Sie den Rohtext, bevor Sie JSON analysieren. Wenn Ihr Framework zuerst den Text analysiert, konfigurieren Sie die Webhook-Route so, dass die rohen Anforderungsbytes verfügbar gemacht werden, und überprüfen Sie diese Bytes, bevor Sie der Nutzlast vertrauen.

Zahlungsnutzlast

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

Veranstaltungstypen

  • status_changed für Statusänderungen der Zahlungssitzung.
  • settlement_updated, wenn sich die Abrechnungsdaten nach dem Statusabgleich ändern.
  • payment_request_expired, quote_expired und payment_cancelled_by_payer für endgültige Nichtzahlungsergebnisse.
  • channel_created, wenn der Zahler ein Angebot annimmt und MakePay den Einzahlungskanal erstellt.
  • subscription_status_changed, wenn ein MakePay-Abonnement zwischen active, paused, overdue oder cancelled verschoben wird.

quote_created und quote_refreshed sind interne Zahlungszeitleistenereignisse und werden nicht an Rückruf-URLs gesendet.

Nutzlast für den Abonnementstatus

MakePay sendet auch einen Rückruf, wenn sich ein Abonnementstatus ändert. Der Planer markiert ein Abonnement mit overdue, wenn der älteste unbezahlte Abrechnungszeitraum mindestens beträgt 24 Stunden nach dueAt; Sobald kein unbezahlter Zyklus mehr als 24 Stunden überfällig ist, wird der Der Planer verschiebt das Abonnement zurück auf active. Händler- und Kundenportal Statusänderungen verwenden denselben Rückruf.

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

Lieferprotokoll-API

Verwenden Sie die Webhook-Anfrageroute, um Zustellungen und Wiederholungsversuche zu überprüfen.

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

Zu den optionalen Filtern gehören paymentLinkUid, deliveryStatus und search.

Benötigen Sie Hilfe bei der Partnereinrichtung?

Öffnen Sie die Detailansicht des Zahlungslinks in MakeCrypto, um die generierten Snippets für eine echte Zahlungs-UID zu kopieren, oder kehren Sie zum Portal zurück, um Händlereinstellungen zu verwalten.

Portal öffnen