MakeCrypto

Référence API

Webhooks

En-têtes de livraison, charges utiles d’événements, tentatives et journaux de livraison.

Rappel URL

Configurez le rappel d'équipe URL dans les paramètres d'intégration du développeur. MakePay vérifie d'abord les paramètres du produit MakePay, puis les paramètres de rappel partagés du développeur, de sorte que les paramètres MakeSwap webhook existants peuvent recevoir des événements de paiement MakePay pendant le déploiement du paramètre spécifique au produit.

Lorsque vous enregistrez un rappel MakePay URL, MakeCrypto génère un secret webhook. Stockez-le dans votre gestionnaire de secrets backend. Vous pouvez le régénérer à tout moment à partir du même écran de paramètres ; après la régénération, mettez à jour votre backend avant d'appliquer les signatures avec le nouveau secret.

Comportement de livraison

MakePay envoie le paiement et l'abonnement webhooks à la demande de POST avec un corps JSON. Les livraisons ayant échoué sont réessayées jusqu'à dix fois à intervalles de cinq minutes. Le renvoi manuel est disponible à partir des journaux de requêtes MakeCrypto webhook.

En-têtes

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

Vérifier les signatures

MakePay signe le corps brut exact de la demande JSON avec HMAC-SHA256. La charge utile de signature est :

{timestamp}.{raw_request_body}

L'en-tête x-makepay-signature contient l'horodatage Unix et le résumé versionné :

t=1776556800,v1=<hex_hmac_sha256>

Exemple de vérification dans 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)
  );
}

Lisez le corps brut avant d'analyser le JSON. Si votre infrastructure analyse d'abord le corps, configurez la route webhook pour exposer les octets bruts de la requête et vérifiez ces octets avant de faire confiance à la charge utile.

Charge utile de paiement

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

Types d'événements

  • status_changed pour les changements d’état de session de paiement.
  • settlement_updated lorsque les données de règlement changent après le rapprochement des statuts.
  • payment_request_expired, quote_expired et payment_cancelled_by_payer pour les résultats de non-paiement final.
  • channel_created lorsque le payeur accepte un devis et que MakePay crée le canal de dépôt.
  • subscription_status_changed lorsqu'un abonnement MakePay se déplace entre active, paused, overdue ou cancelled.

quote_created et quote_refreshed sont des événements de calendrier de paiement internes et ne sont pas envoyés aux URL de rappel.

Charge utile de l'état de l'abonnement

MakePay envoie également un rappel lorsqu'un statut d'abonnement change. Le planificateur marque un abonnement overdue lorsque le cycle de facturation impayé le plus ancien date d'au moins 24 heures après dueAt ; une fois qu'aucun cycle impayé n'est en retard de plus de 24 heures, le planificateur ramène l'abonnement à active. Les modifications de statut du commerçant et du portail client utilisent le même rappel.

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

Journaux de livraison API

Utilisez l'itinéraire de requête webhook pour inspecter les livraisons et les tentatives.

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

Les filtres en option incluent paymentLinkUid, deliveryStatus et search.

Besoin d'aide pour la configuration partenaire ?

Ouvrez la vue des détails du lien de paiement dans MakeCrypto pour copier les extraits générés pour un UID de paiement réel, ou revenez au portail pour gérer les paramètres du marchand.

Ouvrir le portail