Reference

Webhooks

AspiPay pushes state changes to your endpoint as JSON events, signed with HMAC-SHA256.

Event types

payment_session.createdHosted checkout lifecycle
payment_session.authorizedHosted checkout lifecycle
payment_session.capturedHosted checkout lifecycle
payment_session.failedHosted checkout lifecycle
payment_session.expiredHosted checkout lifecycle
transaction.succeededMoney movement result
transaction.failedMoney movement result
refund.createdRefund lifecycle
payout.sentPayout to bank/mobile money
merchant.kyb_updatedKYB / merchant state

Subscribe to * to receive every event.

Payload envelope

json
{
  "id": "evt_9f8e7d6c",
  "type": "transaction.succeeded",
  "created": 1789843200,
  "data": {
    "id": "tx_...",
    "amount_minor": 4999,
    "currency": "USD",
    "status": "succeeded"
  }
}

Signature verification

Every request carries an x-aspipay-signature header — HMAC-SHA256 of the raw body using your endpoint's whsec_… secret. Compare in constant time.

js
import { createHmac, timingSafeEqual } from "crypto";

function verify(raw, header, secret) {
  const expected = createHmac("sha256", secret).update(raw).digest("hex");
  const a = Buffer.from(header, "hex");
  const b = Buffer.from(expected, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Retries

  • Non-2xx responses are retried with exponential backoff for up to 24 hours.
  • Order is not guaranteed — always trust the event's created timestamp and the resource's current status.
  • Duplicate deliveries are possible. Use the event id as an idempotency key.
  • Failed deliveries can be replayed from the dashboard.