Skip to main content

Stripe Payment on Steroids

Comprehensive guide to Blue-enabled payment processing

  • Step-by-step explanation of Stripe's Blue integration
  • Implementing conditional payments with verification
  • Including customers in the payment verification flow
  • Bringing issuers, card networks, and acquirers into the document
  • Timeline transparency for all payment participants

NOT READY

This guide demonstrates how Blue documents can integrate with payment processors like Stripe, creating transparent, verifiable payment processes that benefit merchants, customers, and payment providers alike.

Introduction​

Traditional payment integrations focus on API calls between merchants and payment processors, leaving customers with limited visibility into transaction details. Blue documents offer a more transparent approach that includes all participants in a single cohesive flow while maintaining compatibility with existing systems.

By implementing a /blue endpoint, payment processors like Stripe can accept Blue documents that define payment terms, processing requirements, and transparency rules that all parties can verify.

Basic Payment Document Structure​

Generic Card Payment Type​

Blue starts with a generic payment type that defines the basic structure:

name: Card Payment
amount:
  type: Double
currency:
  type: ISO 4217 Currency 3-letter Code
contracts:
  paymentBasicRules:
    type: Sequential Workflow
    description: Checks payment state transitions
    steps:
      - name: ValidateTransition
        type: JavaScript Code
        code: |
          // Prevent capturing already captured transactions
          if (event.action === 'capture' && document('/status') === 'captured') {
            return { valid: false, reason: 'Transaction already captured' };
          }
          // Other validation rules...
          return { valid: true };

Stripe-Specific Implementation​

Stripe payments extend this base type with Stripe-specific fields and processing:

name: Stripe Card Payment
type: Card Payment
stripeChargeId:
  description: Stripe-specific charge identifier
contracts:
  stripeCentralProcessing:
    type: Centralized Processing
    source: stripe.com

Basic Payment Flow​

When a merchant wants to process a payment, they send a Blue document to Stripe's /blue endpoint:

type: Stripe Card Payment
amount: 1555
currency: EUR
token: tok_8d54f71f961e5f80abf5

Stripe processes the payment using its existing infrastructure and returns an updated document:

type: Stripe Card Payment
amount: 1555
currency: EUR
token: tok_8d54f71f961e5f80abf5
stripeChargeId: char_71f961e5f80abf58d54f
status: authorized

This is already valuable because it provides a standardized document format for payment information. However, the real power comes with timeline integration.

Adding Timeline Transparency​

Requesting Timeline Integration​

Merchants can request that Stripe record all state changes to a timeline, making the payment process transparent to all authorized parties:

type: Stripe Card Payment
amount: 1555
currency: EUR
token: tok_8d54f71f961e5f80abf5
contracts:
  requestUsingCentralProcessorTimeline:
    type: Request Central Processor to Write Events to Timeline
    includeEvents: true
    contractId: centralProcessorTimeline
    timelineSchema:
      type: MyOS Timeline Source
      contracts:
        customerHasReadAccess:
          type: MyOS Account Read Access
          account: 3459203485023
  centralProcessorTimeline:
    type: Timeline Source

Stripe's Response with Timeline​

Stripe processes this request and returns the document with timeline details:

type: Stripe Card Payment
amount: 1555
currency: EUR
token: tok_8d54f71f961e5f80abf5
stripeChargeId: char_71f961e5f80abf58d54f
status: authorized
contracts:
  requestUsingCentralProcessorTimeline:
    type: Request Central Processor to Write Events to Timeline
    includeEvents: true
    contractId: centralProcessorTimeline
    timelineSchema:
      type: MyOS Timeline Source
      contracts:
        customerHasReadAccess:
          type: MyOS Account Read Access
          account: 3459203485023
  centralProcessorTimeline:
    type: MyOS Timeline Source
    timelineId: 2398u4592834u592
    timelineSchema:
      type: MyOS Timeline Source
      contracts:
        customerHasReadAccess:
          type: MyOS Account Read Access
          account: 3459203485023

Benefits of Timeline Integration​

This approach provides several benefits:

  1. Transparency: Both merchants and customers can see the exact state of the payment at any time
  2. Verifiability: All state transitions are recorded in the timeline
  3. Interoperability: The payment document can be processed by any system that understands Blue
  4. Auditability: The complete payment lifecycle is recorded in a standardized format

Flexible Token Generation​

The payment flow can accommodate various methods for generating the payment token:

1. Merchant-Provided Token​

In the simplest case, the merchant generates the token through Stripe's existing components:

type: Stripe Card Payment
amount: 1555
currency: EUR
token: tok_8d54f71f961e5f80abf5
# Other fields...

2. MyOS Token Provider​

The merchant can request that MyOS handle token generation:

type: Stripe Card Payment
amount: 1555
currency: EUR
tokenProvider:
  type: MyOS Card Token Provider
  accountId: 3459203485023
# Other fields...

Stripe would then request token information from MyOS, which would collect card details from the customer securely.

3. Stripe URL Token Provider​

Alternatively, Stripe's hosted checkout can be used:

type: Stripe Card Payment
amount: 1555
currency: EUR
tokenProvider:
  type: Stripe Url Token Provider
  url: https://checkout.stripe.com/38945u293845u92345
# Other fields...

4. Customer-Selected Provider​

The token field could be left empty, allowing the customer to choose their preferred payment method during processing.

Advanced Integration: Involving All Payment Parties​

The true potential of Blue for payments emerges when more participants in the payment ecosystem join the process:

Including Issuers and Card Networks​

By extending the payment document to include issuers, acquirers, and card networks:

  1. Enhanced Authentication: Issuers could see exactly what payment their customers are authorizing
  2. Clearer Disputes: When disputes arise, all parties have access to the same verified timeline
  3. Automated Resolution: Rules for refunds, disputes, and chargebacks could be encoded directly in the document

Benefits for All Participants​

  • Customers gain visibility into their transactions and streamlined dispute resolution
  • Merchants experience fewer fraudulent chargebacks and clearer payment terms
  • Issuers can provide better security by showing customers exactly what they're paying for
  • Acquirers and Networks benefit from standardized dispute evidence and automation