# Issuing paid credentials (KVAC algorithm integration)

This guide provides step-by-step instructions for implementing the KVAC algorithm to issue and verify paid credentials using a series of API endpoints. Follow these instructions to integrate KVAC into your system effectively.

Download a sample Postman collection [here](https://github.com/docknetwork/knowledgebase-docs/blob/main/Postman_collections/Issuing%20KVAC%20credentials/README.md).

## Prerequisites

Before starting, ensure you have:

* DIDs for issuer (`did:dock:issuer`) and verifier (`did:dock:verifier`)
* A trust registry (`trust_registry_id`)
* A schema (`http://example.org/schema/kvac`)

## Step-by-step guide

### 1. Invite participants to trust registry (issuer and verifier)

Invite issuers and verifiers to the trust registry and assign them the schema that will be used in the `KVAC` credential.

**POST /trust-registries/{trust\_registry\_id}/participants** This endpoint invites a participant to the trust registry with specified schemas they are allowed to issue or verify. Will be called by the trust registry convenor.

**Body:**

```json
{
  "issuerSchemas": ["http://example.org/schema/kvac"]
}
```

**POST /trust-registries/invitations/accept** This endpoint accepts an invitation to join a trust registry using a provided token. Will be called by a trust registry future member.

**Body:**

```json
{
  "did": "did:dock:issuer",
  "infoUrl": "https://info.org/issuer",
  "token": "inviteTokenIssuer"
}
```

**POST /trust-registries/{trust\_registry\_id}/participants** This endpoint invites a participant to the trust registry with specified schemas they are allowed to issue or verify. Will be called by the trust registry convenor.

**Body:**

```json
{
  "verifierSchemas": ["http://example.org/schema/kvac"]
}
```

**POST /trust-registries/invitations/accept** This endpoint accepts an invitation to join a trust registry using a provided token. Will be called by a trust registry future member.

**Body:**

```json
{
  "did": "did:dock:verifier",
  "infoUrl": "https://info.org/verifier",
  "token": "inviteTokenVerifier"
}
```

### 2. Assign prices to schemas

Assign a price to the schema in the trust registry. Prices are specified in "digits" to support fractional cents, where 1 cent is represented as 1,000,000 digits. This ensures precision in transactions and avoids issues related to floating-point arithmetic.

**POST /trust-registries/{trust\_registry\_id}/schemas/{schema\_id}/price** This endpoint assigns a price to a schema within the trust registry, enabling it to be used for paid credentials.

**Body:**

```json
{
  "currency": "USD",
  "digits": 1000000  // Represents 1 cent
}
```

### 3. List schemas with prices

Retrieve and verify the list of schemas with their assigned prices.

**GET /trust-registries/{trust\_registry\_id}/schemas** This endpoint retrieves all schemas within a trust registry, including the prices assigned to each schema.

**Response:**

```json
[
  {
    "schema": "http://example.org/schema/kvac",
    "prices": [
      {
        "digits": 1000000,
        "currency": "USD",
        "trustRegistryId": "trust_registry_id",
        "trustRegistryMetadata": {
          ...
        }
      }
    ]
  }
]
```

### 4. Issue credentials

Issue credentials using the schemas. The credential must be a KVAC credential to enable paid credentials. The use of the `bbdt16` algorithm is required to enable KVAC and paid credentials.

**POST /credentials** This endpoint issues a KVAC credential based on the specified schema and issuer details.

**Body:**

```json
{
  "algorithm": "bbdt16",
  "credential": {
    "schema": "http://example.org/schema/kvac",
    "issuer": "did:dock:issuer",
    "name": "KVAC Credential",
    "issuanceDate": "2019-12-03T12:19:52Z",
    "expirationDate": "2029-12-03T12:19:52Z",
    "subject": {
      "id": "did:dock:subject",
      "name": "Subject Name",
      "favouriteDrink": "Coffee"
    }
  }
}
```

### 5. Create proof template

Create a proof template using the schema with a price associated and request for verification.

**POST /proof-templates** This endpoint creates a proof template specifying the requirements for verifying a credential.

**Body:**

```json
{
  "name": "KVAC Proof Template",
  "nonce": "1234567890",
  "request": {
    "name": "KVAC Request",
    "purpose": "KVAC Purpose",
    "input_descriptors": [
      {
        "id": "Credential 1",
        "name": "KVAC Request",
        "purpose": "KVAC Purpose",
        "constraints": {
          "fields": [
            { "path": ["$.credentialSchema.id"], "filter": { "const": "http://example.org/schema/kvac" } }
          ]
        }
      }
    ]
  }
}
```

### 6. Add the proof template to the trust registry

Add the proof template to the trust registry to enable it being used by other participants.

**POST /trust-registries/{trust\_registry\_id}/proof-templates** This endpoint adds a proof template to the trust registry, enabling it to be used for verification.

**Body:**

```json
{
  "id": "proof_template_id",
}
```

### 7. Create proof request

Create a proof request based on the proof template to verify the credential.

**POST /proof-templates/{template\_id}/request** This endpoint creates a proof request based on the specified proof template, which can then be used to verify a credential.

**Body:**

```json
{
  "did": "did:dock:verifier"
}
```

**Note:** Verifier DID is required when using paid schemas.

**Errors:**

* If using a did that is part of the trust registry but is not assigned as a verifier for that schema the verification process on step 6 will fail with the following error message: `Presentation could not be verified: Error: Verifier DID does not have permission to verify this credential`
* If using a did that is not part of the trust registry the verification process on step 6 will fail with the following message: `Presentation could not be verified: Error: This credential can only be verified by participants in the ${trust_registry_name} ecosystem. You can learn about the ecosystem by visiting this website: ${trust_registry_url}`

### 8. Verify presentation

Using the [Truvera Wallet](broken://pages/famFFWGPSQb2hQXJZLId), scan the QR code received and follow the process to submit the verification.

### 9. Retrieve trust registry reports

Fetch and verify trust registry reports to ensure proper billing and tracking.

**GET /trust-registries/{trust\_registry\_id}/reports** This endpoint retrieves reports from the trust registry, detailing verifications, fees, and other relevant information for auditing purposes.

**Response:**

```json
[
  {
    "trustRegistryId": "trust_registry_id",
    "verificationId": "572350a8-673a-490a-bed3-c001aa3f58a0",
    "verifierDID": "did:dock:verifier",
    "issuerDID": "did:dock:issuer",
    "schemaId": "http://example.org/schema/kvac",
    "currency": "USD",
    "verifierFee": "123456",
    "vendorFee": "6172",
    "created": "2024-08-08T08:53:50.524Z"
  }
]
```

### 10. Assigning additional schemas to participants

Add new schemas to the Ecosystem by assigning them to each participant.

**PATCH/trust-registries/{registryId}/participants/{participantId}** This endpoint allows updating the Trust Registry participant.

```json
{
  "name": "string",
  "logoUrl": "string",
  "infoUrl": "string",
  "status": "string",
  "suspendedAt": "string",
  "issuerSchemas": [
    "http://example.org/schema/kvac2",
    "http://example.org/schema/kvac3"
  ],
  "verifierSchemas": [
    "http://example.org/schema/kvac2",
    "http://example.org/schema/kvac3"
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.truvera.io/truvera-api/kvac.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.