Credential Issuer Example

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

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

ACK Reference Code

Demos

Code Examples

Resources

Overview

Installation and Setup

Running the Server

API Endpoints

Authentication

Response Format

Controller Credential Endpoints

`POST /credentials/controller`

`GET /credentials/controller/:id`

`DELETE /credentials/controller`

Payment Receipt Endpoints

`POST /credentials/receipts`

`GET /credentials/receipts/:id`

`DELETE /credentials/receipts`

Status List Endpoint

`GET /status/:listId`

DID Document Endpoint

`GET /.well-known/did.json`

References

​Overview

​Installation and Setup

​Running the Server

​API Endpoints

​Authentication

​Response Format

​Controller Credential Endpoints

​POST /credentials/controller

​GET /credentials/controller/:id

​DELETE /credentials/controller

​Payment Receipt Endpoints

​POST /credentials/receipts

​GET /credentials/receipts/:id

​DELETE /credentials/receipts

​Status List Endpoint

​GET /status/:listId

​DID Document Endpoint

​GET /.well-known/did.json

​References

Overview

Installation and Setup

Running the Server

API Endpoints

Authentication

Response Format

Controller Credential Endpoints

`POST /credentials/controller`

`GET /credentials/controller/:id`

`DELETE /credentials/controller`

Payment Receipt Endpoints

`POST /credentials/receipts`

`GET /credentials/receipts/:id`

`DELETE /credentials/receipts`

Status List Endpoint

`GET /status/:listId`

DID Document Endpoint

`GET /.well-known/did.json`

References