Skip to main content

Smart Card Payment

Payment processors like Stripe could transform their capabilities using Blue documents. By upgrading static payment transactions into dynamic, programmable documents with built-in rules, verification, and multi-party capabilities, they can offer unprecedented flexibility while maintaining compatibility with existing systems.

For technical implementation details, see the /blue Endpoint page. This page focuses on the document types themselves and how they could function in a payment context.

Card Payment: The Foundation​

Below is a simplified version of the Card Payment type from the repo.blue Payments Package:

name: Card Payment
amount:
  type: Double
currency:
  type: Text
captured:
  type: Boolean
  default: false
failed:
  type: Boolean
  default: false
error:
  type: Card Processing Error
paymentProcessorId:
  type: Text
  description: Reference ID in the payment processor's system
refunds:
  type: List
  itemType: Refund
disputes:
  type: List
  itemType: Dispute
token:
  type: Card Token
contracts:
  paymentProcessor:
    type: Channel
    description: Channel for payment processor events

  # Core payment operations
  refund:
    type: Operation
    description: Records a refund that has been processed, adding it to the payment's refund history and triggering a Payment Refunded event
    request:
      type: RefundRequest
      amount:
        type: Integer
        description: Amount that was refunded
      reason:
        type: Text
        description: Reason for the refund

  # Additional operations and their implementations for refund, void, dispute, and others

This document type would be used by processors like Stripe to represent payment transactions and manage their lifecycle within the Blue ecosystem.

Classic Card Payment: The Gateway to Blue​

The Classic Card Payment extends the base type to provide a direct equivalent to what Stripe's API experience could be:

name: Classic Card Payment
type: Card Payment
contracts:
  paymentProcessor:
    type: Internal Logic Channel
    description: Untrackable internal system of the payment processor
  merchantApi:
    type: REST API Channel
    provider: stripe.com
    endpointScheme:
      type: Resource Path Pattern
      basePath: /api
      paths:
        - path: /charge/{chargeId}/capture
          method: POST
          operation: capture
        - path: /charge/{chargeId}/refund
          method: POST
          operation: refund
        # Other operations like authorize, update, void are also supported

The Internal Logic Channel represents the potential internal systems where payment processing would happen without external verification. The REST API Channel maps standard API endpoints to operations on the document.

When you might submit a Classic Card Payment to a /blue endpoint:

type: Classic Card Payment
amount: 100
currency: USD
captured: false
token: tok_1234

A payment processor could handle this similar to how they would process a standard API request to create a charge. The resulting payment could potentially:

  • Be visible in the processor's dashboard alongside other charges
  • Trigger webhooks similar to standard charges
  • Be accessible through standard API endpoints
  • Generate reports and analytics

The returned document would include the payment processor's charge ID:

type: Classic Card Payment
amount: 100
currency: USD
captured: false
token: tok_1234
paymentProcessorId: ch_123456

This approach would allow using Blue documents while maintaining existing integrations and workflows.

This is particularly useful in Recurring Payment scenarios where you need to create regular payments based on non-standard processes. For example, a variable billing amount based on usage, complex trial periods, or custom billing cycles that don't fit standard subscription models could all be implemented through Blue documents while still creating standard payments in the processor's system.

Smart Card Payment: Beyond Traditional Processing​

The Smart Card Payment introduces transparency, verification, and programmable behavior while maintaining compatibility with existing systems:

name: Smart Card Payment
type: Card Payment
contracts:
  paymentProcessor:
    type: Timeline Channel
    description: Auditable timeline of payment processor events
  
  paymentProcessorMerchantTimeline:
    type: Timeline Channel
    description: Timeline where payment processor records merchant API requests
  
  merchantTimeline:
    type: Timeline Channel
    description: Timeline for direct merchant events
  
  customerTimeline:
    type: Timeline Channel
    description: Timeline for customer-initiated events
  
  merchantApi:
    type: REST API Channel
    provider: stripe.com
    proxy: paymentProcessorMerchantTimeline
    endpointScheme:
      type: Resource Path Pattern
      basePath: /api
      paths:
        - path: /charge/{chargeId}/capture
          method: POST
          operation: capture
        - path: /charge/{chargeId}/refund
          method: POST
          operation: refund

The paymentProcessorMerchantTimeline serves a special purpose - it's where the payment processor would record all API requests received from the merchant. When standard API calls are made, these calls could be translated into timeline events, creating a complete audit trail.

If implemented by a payment processor like Stripe, Smart Card Payments could potentially:

  • Be visible alongside standard transactions in a payment dashboard
  • Generate the same types of webhook notifications as regular payments
  • Be accessible through standard API endpoints with additional verification capabilities

Example: Guaranteed Delivery Discount Promise​

Imagine shopping at an online store that promises: "If your order takes more than 4 days to deliver, you automatically get an 80% discount." This is a great offer, but how can you trust the shop will honor it?

Enter the Smart Card Payment with third-party verification:

type: Smart Card Payment
amount: 1000
currency: USD
captured: false
token: tok_1234
orderTimestamp: "2023-08-15T12:30:00Z"
contracts:
  merchant:
    type: MyOS Account
    email: shop@example.com
  customer:
    type: MyOS Account
    email: buyer@example.com
  deliveryTimeline:
    type: MyOS Account
    email: dhl-tracking@example.com
  
  # Delivery guarantee workflow
  deliveryGuaranteeWorkflow:
    type: Sequential Workflow
    channel: deliveryTimeline
    event:
      type: Package Delivered
    steps:
      - name: ProcessDelivery
        type: JavaScript Code
        code: |
          // Extract order and delivery timestamps
          const orderTime = new Date(document('/orderTimestamp'));
          const deliveryTime = new Date(event.timestamp);
          
          // Calculate delivery duration in days
          const deliveryDays = (deliveryTime - orderTime) / (1000 * 60 * 60 * 24);
          
          // Determine payment action based on delivery time
          if (deliveryDays <= 4) {
            return {
              events: [
                {
                  type: "Capture Payment",
                  reason: "Package delivered in " + deliveryDays.toFixed(1) + " days",
                  amount: document('/amount')
                }
              ]
            };
          } else {
            // Apply 80% discount for late delivery
            const discountedAmount = document('/amount') * 0.2;
            return {
              events: [
                {
                  type: "Capture Payment",
                  reason: "Late delivery discount applied (80% off)",
                  amount: discountedAmount
                }
              ]
            };
          }

In this example, trust is established through trusted third parties rather than relying solely on the merchant:

  1. The payment processor (like Stripe) would hold the payment authorization but not capture funds until delivery is confirmed
  2. DHL (or another delivery service) would provide independent verification of when the package was actually delivered
  3. The Blue document contains the agreed-upon rules that automatically determine the final payment amount

This creates a triangle of trust where:

  • The shop cannot change the rules after purchase
  • DHL provides independent delivery confirmation
  • The payment processor ensures payment rules are followed
  • The customer can verify the entire process

The shop demonstrates commitment to their promise by putting the guarantee into a verification system outside their control. All parties can independently verify that the rules were followed correctly.

Example: Cryptocurrency Exchange with Payment Protection​

Imagine a scenario where a merchant is selling Bitcoin to a customer. The challenge: how can the customer be sure they'll receive the BTC after paying? And how can the merchant ensure they'll get paid once they transfer the cryptocurrency?

Here's how it could work using an Smart Card Payment with cryptographic verification:

type: Smart Card Payment no API Access
amount: 5000
currency: USD
captured: false
token: tok_1234
btcKey:
  publicKey: "03abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  keyProvided: false
contracts:
  merchant:
    type: MyOS Account
    email: merchant@example.com
  customer:
    type: MyOS Account
    email: customer@example.com
  
  # Merchant provides their private key
  merchantPrivateKeyWorkflow:
    type: Sequential Workflow
    channel: merchantTimeline
    event:
      type: Provide BTC Key
    steps:
      - name: ValidatePrivateKey
        type: JavaScript Code
        code: |
          import { bitcoinjs } from 'blue:FaTx83nVvz7K5uA9RwQhP2bY1LdJtE6mX4G';
          
          // Extract key from event and document
          const privateKeyWIF = event.privateKey;
          const expectedPublicKey = document('/btcKey/publicKey');
          
          // Verify the private key matches the public key
          function verifyPrivateKeyMatchesPublicKey(privateKeyWIF, expectedPublicKeyHex) {
            try {
              const keyPair = bitcoinjs.ECPair.fromWIF(privateKeyWIF);
              const actualPublicKey = keyPair.publicKey.toString('hex');
              return actualPublicKey === expectedPublicKeyHex;
            } catch (error) {
              return false;
            }
          }
          
          const isValid = verifyPrivateKeyMatchesPublicKey(privateKeyWIF, expectedPublicKey);
          
          if (!isValid) {
            return {
              events: [
                {
                  type: "Illegal Request",
                  message: "Private key does not match required public key"
                }
              ]
            };
          }
          
          // Valid key provided
          return {
            events: [
              {
                type: "BTC Key Verified",
                publicKey: expectedPublicKey
              },
              {
                type: "Capture Payment",
                reason: "Cryptographic verification completed"
              }
            ],
            keyValid: true
          };
      
      - name: UpdateKeyStatus
        type: Update Document
        changeset:
          - op: replace
            path: /btcKey/keyProvided
            val: ${steps.ValidatePrivateKey.keyValid}

Here's how this scenario works:

  1. The merchant places BTC in a special 2-of-2 multisignature wallet
  2. The customer already has one private key but needs the merchant's private key to access the funds
  3. The customer authorizes a card payment but it's not captured yet
  4. The merchant provides their private key through the document workflow
  5. The document verifies the key matches the expected public key
  6. Upon verification, the card payment is captured and the customer can now access the BTC

By using "Smart Card Payment no API Access," the merchant can only receive payment by providing the correct private key through the timeline - they cannot capture the payment through the payment processor's API. This creates a trustless exchange where:

  • The customer doesn't need to trust the merchant will deliver the BTC
  • The merchant doesn't need to trust the customer will pay
  • The payment processor ensures funds only move when cryptographic proof is provided
  • Both parties can independently verify the entire process

This approach could be extended to various high-value exchanges where trust between parties is limited, and cryptographic verification serves as an objective arbitrator.

Implementation Example​

When sending an Smart Card Payment to a /blue endpoint:

type: Smart Card Payment
amount: 1000
currency: USD
captured: false
token: tok_1234
contracts:
  merchant:
    type: MyOS Account
    email: merchant@example.com
  customer:
    type: MyOS Account
    email: customer@example.com

The payment processor could return the document with timeline IDs and payment details:

type: Smart Card Payment
amount: 1000
currency: USD
captured: false
token: tok_1234
paymentProcessorId: ch_123456
contracts:
  merchant:
    type: MyOS Account
    email: merchant@example.com
    timelineId: 1234
  customer:
    type: MyOS Account
    email: customer@example.com
    timelineId: 2345
  paymentProcessor:
    type: MyOS Account
    account: stripe-payments
    timelineId: 3456
  paymentProcessorMerchantTimeline:
    type: MyOS Account
    account: stripe-merchant-proxy
    timelineId: 4567

The payment would then exist both in the payment processor's systems and as a Blue document with timelines. You could potentially interact with it through either the standard API or through timeline events.