Skip to main content

Payment ID (PID) System

The Payment ID system is Pelago's decentralized identity layer, enabling secure and private payment authentication.

Overview​

PID is built on the W3C Decentralized Identifier (DID) standard, providing:

  • Self-sovereign identity: Users control their own payment identities
  • Verifiable credentials: On-chain reputation and credit scoring
  • Privacy protection: Zero-knowledge proofs hide sensitive data

DID Structure​

A Pelago DID follows the standard format:

did:pelago:network:identifier

Example:

did:pelago:stellar:GBXXX...XXX

DID Document​

Each PID has an associated DID Document stored on-chain:

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:pelago:stellar:GBXXX...XXX",
  "verificationMethod": [{
    "id": "did:pelago:stellar:GBXXX...XXX#key-1",
    "type": "Ed25519VerificationKey2020",
    "controller": "did:pelago:stellar:GBXXX...XXX",
    "publicKeyMultibase": "zH3C2..."
  }],
  "authentication": ["did:pelago:stellar:GBXXX...XXX#key-1"],
  "service": [{
    "id": "did:pelago:stellar:GBXXX...XXX#payment",
    "type": "PaymentService",
    "serviceEndpoint": "https://pay.pelago.tech"
  }]
}

Verifiable Credentials​

PIDs can hold verifiable credentials that attest to user attributes:

Credential Types​

TypeIssuerPurpose
KYCPelagoIdentity verification
Credit ScoreCredit BureausCreditworthiness
BusinessRegulatorsBusiness verification
Payment HistoryPelagoTransaction reputation

Credential Example​

{
  "@context": ["https://www.w3.org/2018/credentials/v1"],
  "type": ["VerifiableCredential", "KYCCredential"],
  "issuer": "did:pelago:issuer:pelago-kyc",
  "issuanceDate": "2025-01-15T00:00:00Z",
  "credentialSubject": {
    "id": "did:pelago:stellar:GBXXX...XXX",
    "kycLevel": "2",
    "country": "US",
    "verified": true
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2025-01-15T00:00:00Z",
    "verificationMethod": "did:pelago:issuer:pelago-kyc#key-1",
    "proofValue": "z3FXQjecWufY..."
  }
}

Zero-Knowledge Proofs​

PIDs use ZKP to prove attributes without revealing underlying data.

Example: Age Verification​

Supported Proofs​

Proof TypeRevealsHides
Age RangeAbove/below thresholdExact birthdate
LocationCountry/regionExact address
BalanceSufficient fundsExact amount
CreditScore rangeExact score

Creating a PID​

Via SDK​

import { PelagoClient } from '@pelago/sdk';

const pelago = new PelagoClient({
  apiKey: process.env.PELAGO_API_KEY!,
  environment: 'production'
});

// Create a new PID
const pid = await pelago.identity.createPID({
  network: 'stellar',
  walletAddress: 'GBXXX...',
  metadata: {
    displayName: 'My Store',
    type: 'merchant'
  }
});

console.log('PID:', pid.did);
// did:pelago:stellar:GBXXX...XXX

Via Smart Contract​

// Direct contract interaction
interface IPIDRegistry {
    function createPID(
        string calldata network,
        bytes calldata publicKey,
        bytes calldata metadata
    ) external returns (string memory did);
    
    function resolveDID(
        string calldata did
    ) external view returns (DIDDocument memory);
    
    function addCredential(
        string calldata did,
        bytes calldata credential
    ) external returns (bool);
}

KYC Integration​

PID integrates with KYC providers for compliance:

KYC Levels​

LevelRequirementsLimits
0Wallet only$100/day
1Email + Phone$1,000/day
2ID Document$10,000/day
3Full Business KYCUnlimited

KYA (Know Your Agent)​

For AI agent payments (x402 protocol):

// Register an AI agent
const agentPID = await pelago.identity.createAgentPID({
  network: 'stellar',
  agentId: 'agent-123',
  operator: 'did:pelago:stellar:GBXXX...', // Human operator
  capabilities: ['micropayments', 'subscriptions'],
  spendingLimits: {
    perTransaction: 100,
    daily: 1000,
    monthly: 10000
  }
});

Privacy Best Practices​

  1. Minimize Data: Only request necessary credentials
  2. Use ZKP: Prefer proofs over raw data
  3. Credential Revocation: Support revocation checks
  4. Secure Storage: Never store credentials server-side

Next Steps​