Technical Flow

Generate Key Pair

Endpoint: POST /api/v1/onboarding/generate-keysCaller: Card Issuer Application (when user enables DRP)Request: NoneResponse:

{
  "success": true,
  "data": {
    "keyId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...",
    "privateKey": "MIIEvgIBADANBgkqhkiG9w0BAQEFAASC...",
    "algorithm": "RSA-OAEP-256"
  }
}

Copy these values:

keyId → Steps 2, 4
publicKey → Step 2
privateKey → Step 5

Endpoint: POST /api/v1/onboarding/registerCaller: Card Issuer ApplicationRequest:

{
  "hashedPan": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
  "publicKey": "<from Step 1>",
  "keyId": "<from Step 1>"
}

Response:

{
  "success": true,
  "data": {
    "userId": "usr_f8e7d6c5-b4a3-4c2d-1e0f-9a8b7c6d5e4f",
    "status": "active",
    "registeredAt": "2025-12-18T10:30:00Z"
  }
}

Copy: userId → Step 4

hashedPan is SHA-256 hash of Primary Account Number. Card issuer application computes this—DRP never sees the actual PAN.

Create Payment with Encrypted Receipt

Endpoint: POST /api/v1/payments/{gateway}/createCaller: Merchant POS (when user taps card)Request:

{
  "version": "1.0",
  "receiptId": "550e8400-e29b-41d4-a716-446655440003",
  "merchantId": "550e8400-e29b-41d4-a716-446655440004",
  "merchantName": "Coffee Shop",
  "merchantStreet": "123 Main St",
  "merchantCity": "New York",
  "merchantState": "NY",
  "merchantPostalCode": "10001",
  "merchantCountry": "US",
  "transactionId": "550e8400-e29b-41d4-a716-446655440005",
  "transactionDate": "2025-12-18T12:30:00Z",
  "transactionTimezone": "America/New_York",
  "paymentMethod": "card",
  "cardLast4": "4242",
  "cardBrand": "visa",
  "currency": "USD",
  "subtotal": 420,
  "taxAmount": 34,
  "totalAmount": 454,
  "items": [
    {
      "lineItemId": "550e8400-e29b-41d4-a716-446655440006",
      "name": "Latte",
      "quantity": 1,
      "unitPrice": 420,
      "totalPrice": 420
    }
  ],
  "recipientHashedPan": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
  "amount": 454,
  "cardNonce": "cnon:card-nonce-ok"
}

Response:

{
  "success": true,
  "data": {
    "paymentId": "pi_stripe_abc123",
    "clientSecret": "pi_stripe_abc123_secret_xyz",
    "drpMetadata": {
      "receiptId": "550e8400-e29b-41d4-a716-446655440003",
      "transactionId": "550e8400-e29b-41d4-a716-446655440005"
    }
  }
}

Copy: paymentId and gateway name (stripe or square) → Step 5

recipientHashedPan must match Step 2 hash

Grant Decrypt Access

Endpoint: POST /api/v1/keys/grant-accessCaller: Card Issuer Application (when user taps “View Receipt”)Request:

{
  "userId": "<from Step 2>",
  "keyId": "<from Step 1>"
}

Response:

{
  "success": true,
  "data": {
    "tokenId": "tok_9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
    "userId": "usr_f8e7d6c5-b4a3-4c2d-1e0f-9a8b7c6d5e4f",
    "keyId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "purpose": "decrypt",
    "grantedAt": "2025-12-18T10:35:00Z",
    "expiresAt": "2025-12-18T10:38:00Z",
    "sourceIp": "192.168.1.100"
  }
}

Copy: tokenId → Step 5 as accessTokenId

Token expires in 2-3 minutes

Decrypt Receipt

Endpoint: POST /api/v1/payments/decryptCaller: Card Issuer ApplicationRequest:

{
  "paymentId": "<from Step 3>",
  "gateway": "stripe",
  "accessTokenId": "<from Step 4>",
  "privateKey": "<from Step 1>"
}

Response:

{
  "success": true,
  "data": {
    "version": "1.0",
    "receiptId": "550e8400-e29b-41d4-a716-446655440003",
    "merchant": {
      "merchantId": "550e8400-e29b-41d4-a716-446655440004",
      "name": "Coffee Shop",
      "address": {
        "street": "123 Main St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US"
      }
    },
    "transaction": {
      "transactionId": "550e8400-e29b-41d4-a716-446655440005",
      "datetime": "2025-12-18T12:30:00Z",
      "paymentMethod": "card",
      "cardDetails": {
        "last4": "4242",
        "brand": "visa"
      }
    },
    "items": [
      {
        "lineItemId": "550e8400-e29b-41d4-a716-446655440006",
        "name": "Latte",
        "quantity": 1,
        "unitPrice": 420,
        "totalPrice": 420
      }
    ],
    "summary": {
      "subtotal": 420,
      "totalTax": 34,
      "total": 454,
      "currency": "USD",
      "itemCount": 1
    },
    "createdAt": "2025-12-18T12:30:00Z"
  }
}

Summary

Step	Endpoint	Caller	Input	Output
1	`POST /onboarding/generate-keys`	Card Issuer App	-	keyId, publicKey, privateKey
2	`POST /onboarding/register`	Card Issuer App	hashedPan, publicKey, keyId	userId
3	`POST /payments/{gateway}/create`	Merchant POS	receipt data, recipientHashedPan	paymentId
4	`POST /keys/grant-access`	Card Issuer App	userId, keyId	tokenId (2-3 min TTL)
5	`POST /payments/decrypt`	Card Issuer App	paymentId, tokenId, privateKey	Decrypted receipt

Security

End-to-End Encryption

Receipt encrypted with user’s public key. Only user’s private key can decrypt.

Zero Knowledge

DRP stores only hashed PAN. No access to account data or plaintext receipts.

User Consent

Decryption requires biometric/PIN. Tokens expire in 2-3 minutes.

Private Key Security

Stored in device secure enclave. Never transmitted over network.

Getting Started

User Onboarding (Card Issuer)

Payment (Merchant, Gateway)

Receipt Decryption (Card Issuer)

Receipt Encryption (Merchant)

Summary

Security

End-to-End Encryption

Zero Knowledge

User Consent

Private Key Security

​Summary

​Security

End-to-End Encryption

Zero Knowledge

User Consent

Private Key Security

Summary

Security