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
paymentstable 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.secretfor 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
createPaymentIntentbefore displaying cart on the reader. - Handle errors on reader actions using try/catch and
cancelPayment. - Use
updatePaymentIntentto reflect cart modifications prior to payment. - Persist and audit
Paymentrecords 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.