Skip to main content

​
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 Bitstring Status List, 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",
  "paymentRequestToken": "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 Bitstring Status List 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

⌘I