MakeCrypto

Referência API

Webhooks

Cabeçalhos de entrega, cargas de eventos, novas tentativas e logs de entrega.

retorno de chamada URL

Configure o retorno de chamada da equipe URL nas configurações de integração do desenvolvedor. MakePay revisa primeiro a configuração do produto MakePay e, em seguida, a configuração de retorno de chamada do desenvolvedor compartilhado, para que as configurações webhooks MakeSwap existentes possam receber eventos de pagamento MakePay enquanto a configuração específica do produto é implementada.

Ao salvar um retorno de chamada URL MakePay, MakeCrypto gera um segredo webhook. Salve-o em seu gerenciador de segredos de back-end. Você pode regenerá-lo a qualquer momento na mesma tela de configurações; após regenerá-lo, atualize seu back-end antes de exigir assinaturas com o novo segredo.

Comportamento de entrega

MakePay envia pagamento e assinatura webhooks como solicitações POST com corpo JSON. As entregas com falha são repetidas até dez vezes em intervalos de cinco minutos. O encaminhamento manual está disponível nos logs de solicitação webhook de MakeCrypto.

Cabeçalhos

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

Verifique assinaturas

MakePay assina o corpo JSON bruto exato com HMAC-SHA256. A carga útil da assinatura é:

{timestamp}.{raw_request_body}

O cabeçalho x-makepay-signature contém o carimbo de data/hora Unix e o resumo versionado:

t=1776556800,v1=<hex_hmac_sha256>

Exemplo de verificação em 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)
  );
}

Lê o corpo bruto antes de analisar o JSON. Se sua estrutura analisar o corpo primeiro, configure o caminho webhook para expor os bytes brutos e verifique esses bytes antes de confiar na carga útil.

Carga útil de pagamento

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

Tipos de eventos

  • status_changed para alterações de status da sessão de pagamento.
  • settlement_updated quando os dados de liquidação são alterados após a reconciliação de status.
  • payment_request_expired, quote_expired e payment_cancelled_by_payer para resultados terminais sem pagamento.
  • channel_created quando o pagador aceita uma cotação e MakePay cria o canal de depósito.
  • subscription_status_changed quando uma assinatura MakePay muda entre active, paused, overdue ou cancelled.

quote_created e quote_refreshed são eventos internos do cronograma de pagamento e não são enviados para URLs de retorno de chamada.

Carga útil do status da assinatura

MakePay também envia um retorno de chamada quando o status de uma assinatura é alterado. O agendador marca uma assinatura como overdue quando o ciclo de faturamento não pago mais antigo ultrapassa pelo menos 24 horas seu dueAt; Quando nenhum ciclo não pago excede essas 24 horas, o agendador transfere a assinatura de volta para active. As alterações de status do portal do comerciante e do cliente usam o mesmo retorno de chamada.

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

Registros de entrega API

Use o caminho de solicitação webhook para inspecionar entregas e novas tentativas.

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

Os filtros opcionais incluem paymentLinkUid, deliveryStatus e search.

Precisa de ajuda na configuração de parceiro?

Abra a visualização de detalhes do link de pagamento no MakeCrypto para copiar os snippets gerados para um UID de pagamento real, ou volte ao portal para gerenciar as configurações do comerciante.

Abrir portal