API Developer Guide - SA Verifiable Credential Issuance Platform

API Connection Details

Production Environment Variables

⚠️ IMPORTANT: The base URL should be https://issuer.wyzetree.tech with NO trailing slash and NO path. Your code should append the path.

✅ CORRECT Configuration:

# Set ONLY the base domain (no path, no trailing slash)
SARB_API_URL=https://issuer.wyzetree.tech

# Then in your code, append the path:
url = SARB_API_URL + "/api/offers/"
# Result: https://issuer.wyzetree.tech/api/offers/ ✓

❌ WRONG Configuration:

# DO NOT include the path in base URL!
SARB_API_URL=https://issuer.wyzetree.tech/api/offers/

# This causes double paths:
url = SARB_API_URL + "/api/offers/"
# Result: https://issuer.wyzetree.tech/api/offers//api/offers/ ✗

Alternative: Full Endpoint URLs

# If you prefer full URLs without code concatenation:
SARB_OFFERS_ENDPOINT=https://issuer.wyzetree.tech/api/offers/
SARB_TEMPLATES_ENDPOINT=https://issuer.wyzetree.tech/api/templates/
SARB_ISSUERS_ENDPOINT=https://issuer.wyzetree.tech/api/issuers/

# Use directly (no concatenation):
url = SARB_OFFERS_ENDPOINT  # Already complete

Available Endpoints

Method	Endpoint	Purpose
`POST`	`/api/offers/`	Create credential offer (primary endpoint)
`GET`	`/api/templates/`	List available credential templates
`GET`	`/api/issuers/`	List available issuers
`GET`	`/api/offers/{offer_id}`	Get specific offer details

Banking Credential Configuration

For Capitec Banking Credentials:

# Required IDs
Template ID: 4
Issuer ID: 4

# Required credential_data fields
{
  "full_names": "First Name",       # User's first name
  "surname": "Last Name",           # User's surname
  "bank_acc_type": "Savings",       # Account type
  "bank_account_number": "123456",  # Account number
  "credit_risk": "low"              # Risk profile (low/medium/high)
}

Test Connection

# 1. Test basic connectivity
curl https://issuer.wyzetree.tech/

# 2. List templates (requires API key)
curl https://issuer.wyzetree.tech/api/templates/ \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. List issuers (requires API key)
curl https://issuer.wyzetree.tech/api/issuers/ \
  -H "Authorization: Bearer YOUR_API_KEY"

# 4. Create test banking credential offer
curl -X POST https://issuer.wyzetree.tech/api/offers/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 4,
    "issuer_id": 4,
    "credential_data": {
      "full_names": "Test User",
      "surname": "Example",
      "bank_acc_type": "Savings",
      "bank_account_number": "123456789",
      "credit_risk": "low"
    },
    "expires_in_days": 30
  }'

Credential Issuance Workflow

1. External Service

Creates credential offer via API

→

2. Platform

Returns QR code + offer URI

→

3. Display QR

Show QR code to end user

→

4. Wallet App

Scans QR and retrieves credential

Important: External services do NOT retrieve credentials themselves. The wallet app handles credential retrieval using OpenID4VCI endpoints.

What You Get in the API Response

Field	Type	Description
`qr_code_data`	Base64 PNG	Ready-to-use QR code image. No generation needed - just display it!
`offer_uri`	String	OpenID4VCI credential offer URI (embedded in QR code)
`pre_authorized_code`	String	Authorization code for wallet to retrieve credential
`status`	String	Offer status: pending, claimed, or expired

Discovering Template and Issuer IDs

💡 Important: Before creating credential offers, you need to know which template_id and issuer_id to use. Use the GET endpoints below to discover available options.

1. List Available Templates

Get all credential templates with their IDs, names, and associated issuer IDs:

curl https://issuer.wyzetree.tech/api/templates/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

[
  {
    "id": 8,                              // ← Use this as template_id
    "name": "sarb_dfid",
    "display_name": "SARB DFID",
    "issuer_id": 2,                       // ← Use this as issuer_id
    "credential_type": "W3C_VC",
    "credential_format": "jwt_vc_json",
    "requires_photo": "true"
  },
  {
    "id": 9,
    "name": "capitec_proof_of_account",
    "display_name": "Capitec Proof of account",
    "issuer_id": 5,
    "credential_type": "W3C_VC",
    "credential_format": "jwt_vc_json",
    "requires_photo": "false"
  }
]

2. List Available Issuers

Get all credential issuers with their IDs and names:

curl https://issuer.wyzetree.tech/api/issuers/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

[
  {
    "id": 2,
    "name": "sarb_dfid_issuer",
    "display_name": "SARB DFID Issuer",
    "status": "active"
  },
  {
    "id": 5,
    "name": "capitec",
    "display_name": "Capitec Credential Issuer",
    "status": "active"
  }
]

⚠️ Important Relationship:

The template_id and issuer_id in your request must match. Each template belongs to a specific issuer. Use the issuer_id field from the template response.

            Example: Template ID 8 (SARB DFID) → Issuer ID 2 (SARB DFID Issuer)

            ✅ Correct: {"template_id": 8, "issuer_id": 2}

            ❌ Wrong: {"template_id": 8, "issuer_id": 5}

3. Production Template Reference

Current production templates (verify via API as IDs may change):

Template ID	Issuer ID	Template Name	Use Case
8	2	SARB DFID	Digital Financial ID
9	5	Capitec Proof of account	Banking credentials
5	3	South African National PID	National ID
3	1	ISO 18013-5 mDL	Driver's License

Code Examples

Create Credential Offer (cURL)

curl -X POST https://issuer.wyzetree.tech/api/offers/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 4,
    "issuer_id": 4,
    "credential_data": {
      "full_names": "John",
      "surname": "Doe",
      "bank_acc_type": "Savings",
      "bank_account_number": "1234567890",
      "credit_risk": "low"
    },
    "expires_in_days": 30
  }'

Display the QR Code

<!-- In your HTML -->
<img src="data:image/png;base64,RESPONSE_QR_CODE_DATA" 
     alt="Scan to claim credential" 
     style="width: 300px; height: 300px;" />

Create Credential Offer (Python)

import requests
import base64

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://issuer.wyzetree.tech"

# Create credential offer
response = requests.post(
    f"{BASE_URL}/api/offers/",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "template_id": 4,
        "issuer_id": 4,
        "credential_data": {
            "full_names": "John",
            "surname": "Doe",
            "bank_acc_type": "Savings",
            "bank_account_number": "1234567890",
            "credit_risk": "low"
        },
        "expires_in_days": 30
    }
)

if response.status_code == 200:
    data = response.json()
    qr_code = data["qr_code_data"]  # Base64 PNG - ready to use!
    offer_uri = data["offer_uri"]
    status = data["status"]
    
    # Save QR code to file
    with open("credential_qr.png", "wb") as f:
        f.write(base64.b64decode(qr_code))
    
    print(f"✓ Offer created with status: {status}")
    print(f"✓ QR code saved to credential_qr.png")
else:
    print(f"✗ Error: {response.status_code} - {response.text}")

Display QR in Web App (Flask)

from flask import Flask, render_template_string

app = Flask(__name__)

@app.route('/show-credential')
def show_credential():
    # qr_code_data from API response
    html = '''
    <h1>Scan to Claim Your Credential</h1>
    <img src="data:image/png;base64," 
         alt="Credential QR Code" 
         style="width: 300px; height: 300px;" />
    '''
    return render_template_string(html, qr_code=qr_code_data)

Create Credential Offer (JavaScript/Node.js)

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://issuer.wyzetree.tech';

async function createCredentialOffer() {
  try {
    const response = await fetch(`${BASE_URL}/api/offers/`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        template_id: 4,
        issuer_id: 4,
        credential_data: {
          full_names: "John",
          surname: "Doe",
          bank_acc_type: "Savings",
          bank_account_number: "1234567890",
          credit_risk: "low"
        },
        expires_in_days: 30
      })
    });

    if (response.ok) {
      const data = await response.json();
      console.log('✓ Offer created:', data.status);
      return data;
    } else {
      console.error('✗ Error:', response.status, await response.text());
    }
  } catch (error) {
    console.error('✗ Request failed:', error);
  }
}

// Use the offer
createCredentialOffer().then(offer => {
  if (offer) {
    // Display QR code in browser
    const img = document.createElement('img');
    img.src = `data:image/png;base64,${offer.qr_code_data}`;
    img.alt = 'Scan to claim credential';
    img.style.width = '300px';
    img.style.height = '300px';
    document.body.appendChild(img);
  }
});

React Component Example

import React, { useState } from 'react';

function CredentialOffer() {
  const [qrCode, setQrCode] = useState(null);
  const [loading, setLoading] = useState(false);

  const createOffer = async () => {
    setLoading(true);
    try {
      const response = await fetch('https://your-domain.com/api/offers/', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          template_id: 1,
          issuer_id: 1,
          credential_data: {
            account_holder: "John Doe",
            account_number: "1234567890",
            account_type: "Savings",
            bank_name: "Capitec Bank",
            verified_date: "2025-11-10"
          }
        })
      });

      const data = await response.json();
      setQrCode(data.qr_code_data);
    } catch (error) {
      console.error('Failed to create offer:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    
      
      
      {qrCode && (
        
          Scan to Claim Your Credential
          
        
      )}
    
  );
}

Responsibilities

Your Service Handles:

✓ Creating credential offers via API
✓ Displaying QR codes to end users
✓ Managing user sessions/context
✓ Tracking offer status (optional)

Wallet App Handles:

✓ Scanning QR codes
✓ Token exchange (OAuth 2.0)
✓ Credential retrieval from platform
✓ Secure credential storage

API Reference

For complete API documentation including all endpoints, request/response schemas, and authentication details:

View Interactive API Documentation →