Skip to main content
1

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
2

Register User

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.
3

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
4

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
5

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

StepEndpointCallerInputOutput
1POST /onboarding/generate-keysCard Issuer App-keyId, publicKey, privateKey
2POST /onboarding/registerCard Issuer ApphashedPan, publicKey, keyIduserId
3POST /payments/{gateway}/createMerchant POSreceipt data, recipientHashedPanpaymentId
4POST /keys/grant-accessCard Issuer AppuserId, keyIdtokenId (2-3 min TTL)
5POST /payments/decryptCard Issuer ApppaymentId, tokenId, privateKeyDecrypted 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.