Docs/Public API/Issuances API

Issuances API

Store signed issuance actions and read completed issuance events.

POST /issuances#

Create an issuance session with a Loyfin API key.

Request bodyjson

{
  "issuance": {
    "issuer": "0x1111111111111111111111111111111111111111",
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "1000",
    "expiresAt": "0",
    "deadline": "0",
    "nonce": "0x7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a",
    "chainId": "8453",
    "verifyingContract": "0x3333333333333333333333333333333333333333",
    "operationHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "metadata": {
      "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
      "name": "Bloom Coffee Rewards",
      "symbol": "BLOOM",
      "media": "ipfs://bafy.../bloom.png",
      "description": "Rewards for Bloom Coffee customers.",
      "contractURI": "",
      "tokenURI": ""
    },
    "data": "0x"
  },
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
}

TypeScript SDK — Upcoming releasetypescript

import { Loyfin, issuanceTypedData } from "@loyfin/server";

const loyfin = new Loyfin({ apiKey: process.env.LOYFIN_API_KEY });

const typedData = issuanceTypedData(issuance);
const signature = await issuerSigner.signTypedData(typedData);

const { issuance: session, duplicate } = await loyfin.issuances.create({
  issuance,
  signature
});

// Show session.checkoutUrl when the recipient still needs to sign.

JavaScript fetchjavascript

const response = await fetch("https://api.loyfin.com/issuances", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-loyfin-api-key": process.env.LOYFIN_API_KEY
  },
  body: JSON.stringify({
    issuance,
    signature,
    signatureScheme: "dual"
  })
});

if (!response.ok) {
  throw new Error(await response.text());
}

const { issuance: session, duplicate } = await response.json();

curlbash

curl https://api.loyfin.com/issuances \
  -X POST \
  -H "content-type: application/json" \
  -H "x-loyfin-api-key: $LOYFIN_API_KEY" \
  -d '{
  "issuance": {
    "issuer": "0x1111111111111111111111111111111111111111",
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "1000",
    "expiresAt": "0",
    "deadline": "0",
    "nonce": "0x7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a",
    "chainId": "8453",
    "verifyingContract": "0x3333333333333333333333333333333333333333",
    "operationHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
    "metadata": {
      "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
      "name": "Bloom Coffee Rewards",
      "symbol": "BLOOM",
      "media": "ipfs://bafy.../bloom.png",
      "description": "Rewards for Bloom Coffee customers.",
      "contractURI": "",
      "tokenURI": ""
    },
    "data": "0x"
  },
  "signature": "0xababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
}'

Responsejson

{
  "ok": true,
  "duplicate": false,
  "issuance": {
    "id": "11111111-1111-4111-8111-111111111111",
    "operationId": "128",
    "kind": "issuance",
    "status": "requires_holder_signature",
    "chainId": "8453",
    "issuer": "0x1111111111111111111111111111111111111111",
    "to": null,
    "loyaltyId": "0x4242424242424242424242424242424242424242424242424242424242424242",
    "amount": "1000",
    "expiresAt": "0",
    "deadline": "0",
    "nonce": "0x7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a7a",
    "checkoutUrl": "https://loyfin.com/issuances/11111111-1111-4111-8111-111111111111?claim=..."
  }
}

GET /issuances#

List completed issuance events.

List completed issuancesbash

curl "https://api.loyfin.com/issuances?issuer=0x1111111111111111111111111111111111111111&limit=25"

Filters: cursor, limit, issuer, to, loyaltyId, token, and operationHash.

Objects#

POST /issuances requires a Loyfin API key and returns an issuance session. If the recipient signature is missing, the response includes a checkout URL that carries an opaque claim token. The UUID alone is not a bearer secret; the query-string claim token is. Keep the complete URL out of logs, analytics, support tickets, and referrer data. GET /issuances returns completed Issuance event objects.