Pyle

Payments ​

What This Is ​

Payments are the records and workflows your team uses to collect money on an order, verify what was captured or refunded, and understand what amount is still due.

In the shared package, the strongest payment capabilities are operator-facing. Shopper-facing payment activity is mostly indirect through checkout and saved-card management.

When You Would Use It ​

Use Payments when you need to:

  • review how an order was paid
  • check the remaining amount due on an order
  • charge a saved Stripe card
  • record a manual payment such as cash, bank transfer, or check
  • sync or verify a payment imported from Stripe
  • confirm whether a payment is still refundable

Before You Start ​

Before you review or create a payment, make sure:

  • the order already exists
  • the correct payment gateway is configured
  • you know whether you are using a saved card, a manual payment method, or a checkout-link flow
  • your project exposes the payment controls you need on top of the shared order APIs

The shared package defines payment creation and review strongly, but it does not ship a dedicated shared admin payment-management page in the repo inspected in this pass.

How To Use It In The Admin ​

  1. Open the order you want to review.
  2. Check the financial context first:
    • total price
    • paid amount
    • refunded amount
    • amount due
  3. Use your project’s payment workflow or payment panel backed by the shared order-payment API.
  4. When creating a payment, choose the right collection path:
    • saved Stripe card
    • manual payment
    • checkout-link flow
  5. For manual payments, enter:
    • amount
    • payment method type
    • payment reference number
  6. For saved-card payments, choose the correct customer card and confirm the amount.
  7. Sync the payment when needed if the charge originated in Stripe and the local record is stale.
  8. Re-check the order amount due and refundability after the payment is saved or synced.

What It Changes In The Storefront ​

Payments mostly change storefront behavior indirectly:

  • checkout completion can close the amount-due gap
  • saved cards can become available for later operator capture
  • invoice or refund communication becomes easier to interpret

Customers do not get a standalone shared payment-history page in the inspected storefront package.

Common Tasks ​

Record a manual payment ​

Use the manual payment path when the money was collected outside a direct gateway charge and you need a local payment record with a reference number.

Charge a saved card ​

Use the saved-card path when the customer already has a Stripe-backed card on file.

Review whether a payment can be refunded ​

Check the payment status, refunded amount, and whether the related gateway allows refunds.

Rules, Limits, And Things To Watch ​

  • You cannot create a payment for more than the order amount due.
  • Manual payment reference numbers must be unique per order.
  • Payment gateway type and payment method type are not the same thing.
  • Shopper payment methods and order payments are related, but they are not the same record type.

Troubleshooting ​

The payment cannot be created ​

Check the amount due, payment-gateway setup, and required fields for the chosen payment path.

The payment exists in Stripe but not locally ​

Use the sync workflow if your project exposes it.

The customer sees saved cards, but the order still shows money due ​

Saved cards only enable future charge workflows. They do not settle an order until a payment is actually created or checkout completes.

For the full operator recovery checklist, see How to troubleshoot a payment that did not settle an order.

Sources ​

  • packages/framework/src/Http/Controllers/Api/Admin/OrderPaymentsController.php
  • packages/framework/src/Models/OrderPayment.php
  • packages/framework/src/Actions/Stripe/ChargeStripeCustomerCard.php
  • packages/framework/src/Actions/Stripe/SyncStripeCheckoutToOrderPayment.php
  • packages/framework/src/Actions/PaymentGateway/Manual/CreateOrderPayment.php
  • packages/framework/src/Actions/PaymentGateway/CreditLine/CreateOrderPayment.php