Verifiable Credentials Management

The Verifiable Credentials Management API enables the creation, issuance, and management of verifiable credentials for secure digital payments and identity verification. The service handles user enrollment with cryptographic key generation, credential issuance for payment authorization, presentation signing for user consent, payment processing using signed credentials, and credential verification for banks and other verifiers. These endpoints provide a complete cryptographic payment system that ensures secure, verifiable transactions with full user consent and audit trails.

The verifiable credentials model

The verifiable credentials model handles the data fields used in the VC Management API endpoints for managing enrollments, credentials, and payments. It enables secure enrollment of users, issuance of payment authorization credentials, and processing of verifiable payments.

Properties

Name
partnershipId
Type
string
Description
Unique identifier of the business partnership between the recipient and the agent. Required for partnership-based operations.
Name
userDid
Type
string
Description
Decentralized Identifier (DID) assigned to the user during enrollment. Required for credential verification.
Name
agentDid
Type
string
Description
Developer Decentralized Identifier (DID) created when the partnership is set up. Required for agent-side operations.
Name
recipientDid
Type
string
Description
Operator Decentralized Identifier (DID) created when the partnership is set up. Required for recipient-side operations.
Name
userId
Type
string
Description
Unique identifier for the user (UUID format). Required for user-related operations.
Name
name
Type
string
Description
Display name of the user. Can be updated via the update-user endpoint.
Name
email
Type
string
Description
Email address of the user. Can be updated via the update-user endpoint.
Name
metadata
Type
object
Description
Custom metadata object containing additional entity information..
Name
amount
Type
decimal
Description
Payment amount limit for the credential. Required for credential issuance and payment processing.
Name
currency
Type
string
Description
Payment currency code (ISO 4217, default "USD"). Used in payment processing.
Name
scope
Type
string
Description
Payment scope or category (e.g., "restaurant", "retail"). Required for credential issuance.
Name
purpose
Type
string
Description
Purpose of the payment.
Name
expirationMinutes
Type
integer
Description
Credential expiration time in minutes (1–1440, default 30). Used in credential issuance.
Name
verifiableCredential
Type
object
Description
Verifiable Credential object containing credentials and cryptographic proof. Required for payment processing and verification.

Enroll a User

The enroll endpoint registers a user in the VC service by generating a DID and key pair. It validates the partnership and user details, creates an enrollment record, and returns the user’s DID, public key, and verification method for credential management.

Required attributes

Name
partnershipId
Type
string
Description
Unique identifier of the business partnership between the recipient and the agent.
Name
userId
Type
string
Description
Unique identifier for the user (UUID format).
Name
name
Type
string
Description
Display name of the user.
Name
email
Type
string
Description
Email address of the user.
Name
metadata
Type
object
Description
Custom metadata object containing additional entity information.

Request

POST

/vc/v1/enroll

curl -X POST https://localhost:4901/vc/v1/enroll \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "partnershipId": "3d21870c-496c-419b-a8a6-5b222990e357",
    "userId": "270412fe-c49d-405d-bbcc-e376b636700e",
    "name": "John Doe",
    "email": "johasdn.doe@example.com",
    "metadata": {
      "site": "https://www.example.com",
      "purpose": "Flights",
      "destination": "UK, London"
    }
  }'

Response True (1/3)

{
  "success": true,
  "message": "User enrolled successfully.",
  "data": {
    "id": "cea46f73-8745-4b45-bf7c-76563d5862d2",
    "userId": "270412fe-c49d-405d-bbcc-e376b636700e",
    "userDid": "did:key:z6Mke0a9ecf79cf6a1ff7665178c91d17486",
    "publicKey": "MCowBQYDK2VwAyEAGnd4XFADAtxhTWMSwoPomayi9p95gDGKhitheIW5TGw=",
    "verificationMethod": "did:key:z6Mke0a9ecf79cf6a1ff7665178c91d17486#key-1",
    "metadata": {
      "entityType": "user",
      "name": "John Doe",
      "email": "johasdn.doe@example.com"
    }
  }
}

Issue a Credential

The issue-credential endpoint issues a payment consent credential between a user and agent. It validates enrollment and partnership, checks consent, creates a unique credential with cryptographic proof, stores it, and returns the signed credential with payment limits and authorization details.

Required attributes

Name
userDid
Type
string
Description
Decentralized Identifier (DID) assigned to the user during enrollment.
Name
agentDid
Type
string
Description
Developer Decentralized Identifier (DID) created when the partnership is set up.
Name
amount
Type
decimal
Description
Payment amount limit for the credential.
Name
currency
Type
string
Description
Payment currency code (ISO 4217, default "USD").
Name
scope
Type
string
Description
Payment scope or category (e.g., "restaurant", "retail").
Name
purpose
Type
string
Description
Purpose of the payment.

Optional attributes

Name
expirationMinutes
Type
integer
Description
Credential expiration time in minutes (1–1440, default 30).

Request

POST

/vc/v1/issue-credential

curl -X POST https://localhost:4901/vc/v1/issue-credential \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userDid": "did:key:z6Mk2b84e6986130ed411d0e386722b0ebb5",
    "agentDid": "did:key:z6Mk7b4bcd19d9dee0182ae9e9ef05c9779c",
    "amount": 250.00,
    "currency": "USD",
    "scope": "restaurant",
    "purpose": "Dinner payment",
    "expirationMinutes": 30
  }'

Response True (1/3)

{
  "success": true,
  "message": "Credential issued successfully.",
  "data": {
    "credential": {
      "id": "http://localhost:4901/vc/v1/credentials/b83e33a1-e3b9-4fac-b9ed-67b3a0777275",
      "type": [
        "VerifiableCredential",
        "PaymentConsentCredential"
      ],
      "issuer": "did:key:z6Mk219e5375d032a5327dd96f8eef556cd0",
      "credentialSubject": {
        "id": "did:key:z6Mk25efee2a2279a09098d92d90a1370954",
        "authorizedAgent": "did:key:z6Mk59c4d049129b0e9beacf813968a5b618",
        "paymentLimit": 250.00,
        "currency": "USD",
        "scope": "restaurant",
        "purpose": "Dinner payment"
      },
      "proof": {
        "type": "Ed25519Signature2020",
        "verificationMethod": "did:key:z6Mk219e5375d032a5327dd96f8eef556cd0#key-1",
        "proofValue": "platform_signature_using_issuer_private_key"
      }
    }
  }
}

Sign a Presentation

The sign-presentation endpoint signs a verifiable presentation to prove credential ownership and authorization. It validates the request, checks the credential’s status and data, verifies user and partnership details, and signs the presentation with the user’s private key. Returns the signed presentation for use in transactions.

Required attributes

Name
userDid
Type
string
Description
Decentralized Identifier (DID) assigned to the user during enrollment.
Name
verifiableCredential
Type
object
Description
Verifiable Credential object containing credentials and cryptographic proof.

Request

POST

/vc/v1/sign-presentation

curl -X POST https://localhost:4901/vc/v1/sign-presentation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "userDid": "did:key:z6Mk25efee2a2279a09098d92d90a1370954",
    "presentation": {
      "context": ["https://www.w3.org/2018/credentials/v1"],
      "type": ["VerifiablePresentation"],
        "verifiableCredential": [
          {
            "id": "http://localhost:4901/vc/v1/credentials/17318cfe-5fbf-48f5-bbcd-3d6b23f4d9cd",
            "type": [
              "VerifiableCredential",
              "PaymentConsentCredential"
            ],
            "issuer": "did:key:z6Mk7d898958db08d3c8a841ed6ee34ab9b3",
            "credentialSubject": {
              "id": "did:key:z6Mk25efee2a2279a09098d92d90a1370954",
              "authorizedAgent": "did:key:z6Mk59c4d049129b0e9beacf813968a5b618",
              "paymentLimit": 250,
              "currency": "USD",
              "scope": "restaurant",
              "purpose": "Dinner payment"
            },
            "proof": {
              "type": "Ed25519Signature2020",
              "verificationMethod": "did:key:z6Mk7d898958db08d3c8a841ed6ee34ab9b3#key-1",
              "proofValue": "platform_signature_using_issuer_private_key"
            }
          }
        ]
    }
  }'

Response True (1/3)

{
  "success": true,
  "message": "Presentation signed successfully.",
  "data": {
    "signedPresentation": {
      "context": [
        "https://www.w3.org/2018/credentials/v1"
      ],
      "type": [
        "VerifiablePresentation"
      ],
      "verifiableCredential": [
        {
          "credentialSubject": {
            "id": "did:key:z6Mk25efee2a2279a09098d92d90a1370954"
          }
        }
      ],
      "proof": {
        "type": "Ed25519Signature2020",
        "verificationMethod": "did:key:z6Mk25efee2a2279a09098d92d90a1370954#key-1",
        "proofValue": "user_signature_using_enrollment_private_key"
      }
    }
  }
}

Make Payment

The pay endpoint processes a payment using a verifiable presentation. It verifies the recipient DID, validates the credential and signatures, checks limits and scope, creates a payment record, forwards it to the bank, and updates the status. Returns payment ID, transaction ID, amount, and status.

Required attributes

Name
recipientDid
Type
string
Description
Operator Decentralized Identifier (DID) created when the partnership is set up.
Name
verifiableCredential
Type
object
Description
Verifiable Credential object containing credentials and cryptographic proof.

Request

POST

/vc/v1/pay

curl -X POST https://localhost:4901/vc/v1/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "recipientDid": "did:key:restaurant-recipient-did",
    "presentation": {
      "verifiableCredential": [
        {
          "id": "http://localhost:4901/vc/v1/credentials/7675096e-2a81-4a54-b0af-edf4d7911dff",
          "type": ["VerifiableCredential", "PaymentConsentCredential"],
          "issuer": "did:key:z6Mk32e43c89afd5fe93a5f4fb3357fca1a7",
          "credentialSubject": {
            "id": "did:key:z6Mk6ca07c6450c9cd121d7a2501aa70e683",
            "authorizedAgent": "did:key:z6Mk4995e182da53f26eca27afa5fe0eee70",
            "paymentLimit": 250,
            "currency": "USD",
            "scope": "restaurant",
            "purpose": "Dinner payment"
          },
          "proof": {
            "type": "Ed25519Signature2020",
            "verificationMethod": "did:key:z6Mk32e43c89afd5fe93a5f4fb3357fca1a7#key-1",
            "proofValue": "platform_signature_using_issuer_private_key"
          }
        }
      ],
      "proof": {
        "proofValue": "user_signature_using_enrollment_private_key"
      }
    }
  }'

Response True (1/5)

{
  "success": true,
  "message": "Payment accepted and processing",
  "data": {
    "paymentId": "a61a62d5-c245-49cb-bab3-8741ff5fc33a",
    "transactionId": "1abc212e-16ea-4983-a9a7-153c8bb411b0",
    "amount": {
      "value": 250,
      "currency": "USD"
    },
    "status": "processing",
    "recipient": {
      "did": "did:key:restaurant-recipient-did",
      "type": "system"
    }
  }
}

Verifiable Credentials Management

The verifiable credentials model

Properties

Payment Consent

Enroll a User

Required attributes

Issue a Credential

Required attributes

Optional attributes

Sign a Presentation

Required attributes

Make Payment

Required attributes