​
Overview

This example demonstrates an ACK-ID and ACK-Pay Verifiable Credential issuer API built with Hono.

The API supports issuing, verifying, and revoking two primary credential types:

  • ControllerCredential: proves ownership of DIDs (part of ACK-ID).
  • PaymentReceiptCredential: provides proof of payment meeting a Payment Request (part of ACK-Pay).

The issuer implements credential revocation using StatusList2021, a privacy-preserving and efficient revocation list method.

​
Installation and Setup

Install dependencies and prepare your environment.

From within the issuer example directory (e.g., from project root: ./examples/issuer) execute the setup:

pnpm run setup

​
Running the Server

Start the API server locally:

pnpm run dev

The server runs at: http://localhost:3456

​
API Endpoints

​
Authentication

All endpoints require a signed payload (JWT) proving DID ownership. During local development, include the X-Payload-Issuer header with a resolvable DID-URI to bypass signature verification.

​
Response Format

All API responses use this JSON structure:

{
  "ok": true,
  "data": <data>
}

or

{
  "ok": false,
  "error": "Error message"
}

​
Controller Credential Endpoints

​
POST /credentials/controller

Issue a ControllerCredential proving DID control.

Sample cURL:

curl --request POST \
  --url http://localhost:3456/credentials/controller \
  --header 'Content-Type: application/json' \
  --header 'X-Payload-Issuer: did:web:0.0.0.0%3A3458:controller' \
  --data '{
  "controller": "did:web:0.0.0.0%3A3458:controller",
  "subject": "did:web:0.0.0.0%3A3458:agent"
}'

​
GET /credentials/controller/:id

Retrieve a ControllerCredential by ID.

Sample cURL:

curl --request GET \
  --url http://localhost:3456/credentials/controller/abc123

​
DELETE /credentials/controller

Revoke a ControllerCredential by ID.

Sample cURL:

curl --request DELETE \
  --url http://localhost:3456/credentials/controller \
  --header 'Content-Type: application/json' \
  --header 'X-Payload-Issuer: did:web:0.0.0.0%3A3458:controller' \
  --data '{
  "id": "abc123"
}'

​
Payment Receipt Endpoints

​
POST /credentials/receipts

Issue a PaymentReceiptCredential.

Sample cURL:

curl --request POST \
  --url http://localhost:3456/credentials/receipts \
  --header 'Content-Type: application/json' \
  --header 'X-Payload-Issuer: did:web:0.0.0.0%3A3458:wallet' \
  --data '{
  "metadata": { "txHash": "0x123abc456def" },
  "payerDid": "did:web:0.0.0.0%3A3458:wallet",
  "paymentToken": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "paymentOptionId": "option1"
}'

​
GET /credentials/receipts/:id

Retrieve a PaymentReceiptCredential by ID.

Sample cURL:

curl --request GET \
  --url http://localhost:3456/credentials/receipts/abc123

​
DELETE /credentials/receipts

Revoke a PaymentReceiptCredential by ID.

Sample cURL:

curl --request DELETE \
  --url http://localhost:3456/credentials/receipts \
  --header 'Content-Type: application/json' \
  --header 'X-Payload-Issuer: did:web:0.0.0.0%3A3458:payee' \
  --data '{
  "id": "abc123"
}'

​
Status List Endpoint

​
GET /status/:listId

Retrieve StatusList2021 credential for revocation checks.

Sample cURL:

curl --request GET \
  --url http://localhost:3456/status/1

​
DID Document Endpoint

​
GET /.well-known/did.json

Retrieve the issuer’s DID Document.

Sample cURL:

curl --request GET \
  --url http://localhost:3456/.well-known/did.json

​
References