Stripe Terminal Support

A suite of helper methods enabling on-site, card-present payment flows using Stripe Terminal. These methods live in the shared Stripe service layer, leveraging the StripeClient to:

  • Create and update PaymentIntents for in-person transactions
  • Discover and interact with Stripe Readers
  • Display cart details on the physical reader
  • Process and cancel terminal checkouts

πŸ“¦ Context & Purpose

Stripe Terminal support complements the online checkout by:

  • Allowing event staff to accept payments in person via card readers
  • Ensuring a seamless β€œcard_present” workflow alongside existing web flows
  • Recording each terminal payment into the payments table for reporting

These helpers are invoked by on-site checkout controllers or Livewire components to orchestrate terminal interactions.


Key Components

Method Description Returns / Effects
createPaymentIntent Initialize a new PaymentIntent configured for card_present transactions and record it locally. Stripe\PaymentIntent and a Payment record with status requires_payment_method
retrievePaymentIntent Fetch an existing PaymentIntent by its Stripe ID. Stripe\PaymentIntent
updatePaymentIntent Modify the amount of an existing PaymentIntent (e.g., when cart changes). Updated Stripe\PaymentIntent
retrieveReader Lookup a Stripe Terminal reader by its ID. Stripe\Terminal\Reader or null
setReaderDisplay Push cart details to the reader screen: currency, line items, and total. – (void)
stripeReaderCheckout Instruct the reader to process the prepared PaymentIntent, triggering the physical card swipe/tap. The captured Stripe\PaymentIntent
cancelPayment Cancel an in-flight PaymentIntent or abort reader action if possible. Cancelled Stripe\PaymentIntent or null

Method Signatures

/**
 * Create a card_present PaymentIntent and store it.
 *
 * @param int $amount
 * @return StripePaymentIntent
 */
public function createPaymentIntent(int $amount);

/**
 * Retrieve a PaymentIntent by ID.
 *
 * @param string $payment_id
 * @return StripePaymentIntent
 */
public function retrievePaymentIntent(string $payment_id);

/**
 * Update an existing PaymentIntent's amount.
 *
 * @param string $payment_id
 * @param int    $amount
 * @return StripePaymentIntent
 */
public function updatePaymentIntent(string $payment_id, int $amount);

/**
 * Get a Stripe Terminal reader instance.
 *
 * @param string|null $reader_id
 * @return StripeReader|null
 */
public function retrieveReader(?string $reader_id);

/**
 * Display the in-person cart on a reader device.
 *
 * @param string $reader_id
 * @param array  $line_items  // Each item: ['amount' => int, 'label' => string]
 * @return void
 */
public function setReaderDisplay(string $reader_id, array $line_items);

/**
 * Process a PaymentIntent on a reader (card_present flow).
 *
 * @param string $reader_id
 * @param string $payment_intent
 * @return StripePaymentIntent
 */
public function stripeReaderCheckout(string $reader_id, string $payment_intent);

/**
 * Cancel a PaymentIntent or reader action where supported.
 *
 * @param string|null $payment_id
 * @param string|null $reader_id
 * @return StripePaymentIntent|null
 */
public function cancelPayment(?string $payment_id = null, ?string $reader_id = null);

πŸ“ˆ Terminal Flow Chart

flowchart TD
  A[Start In-Person Checkout] --> B[createPaymentIntent(amount)]
  B --> C{Intent Created?}
  C -- Yes --> D[Save Payment record]
  D --> E[retrieveReader(reader_id)]
  E --> F[setReaderDisplay(reader_id, line_items)]
  F --> G[Wait for card_present]
  G --> H[stripeReaderCheckout(reader_id, intent_id)]
  H --> I{Payment Succeeded?}
  I -- Yes --> J[Mark Order Completed]
  I -- No  --> K[cancelPayment(intent_id, reader_id)]
  J --> L[Print Receipt]
  K --> L

πŸ”— Dependencies & Integration

  • Stripe PHP SDK: via StripeClient (getStripeClient()) for all API calls.
  • Payment Eloquent Model: records the PaymentIntent on creation.
  • Config: Reads services.stripe.secret for API credentials.
  • Session / Cart: Can be combined with existing cart logic to derive line_items.

These helpers integrate seamlessly with existing web-based checkout flows (StripeTrait) and the SaveOrderService for online order persistence.


βœ… Best Practices & Considerations

  • Always call createPaymentIntent before displaying cart on the reader.
  • Handle errors on reader actions using try/catch and cancelPayment.
  • Use updatePaymentIntent to reflect cart modifications prior to payment.
  • Persist and audit Payment records for reconciliation and refunds.
{
    "title": "Test Reader Before Event",
    "content": "Verify reader connectivity and credentials prior to any event day usage."
}

Stripe Terminal support bridges the gap between online and on-site payments, ensuring your event operations remain flexible and fully tracked within the Prep Network platform.