Feat: authorize and capture payment

[lohanidamodar]

• Hold amount first and capture later

Summary by CodeRabbit

• New Features

  • Added authorization and capture workflow enabling payment holds with subsequent charge or cancellation
  • Enabled partial capture for authorized payments
  • Added authorization cancellation capability

• Documentation

  • Enhanced README with comprehensive examples for purchases, customer management, payment methods, and refunds

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

This pull request introduces an authorization and capture payment workflow to the payment library. Three new abstract methods are added to the Adapter interface (authorize, capture, cancelAuthorization), implemented in the Stripe adapter class, exposed through the Pay facade with delegation, and covered by comprehensive test cases. Documentation is updated with usage examples demonstrating the new payment hold-and-charge pattern. No existing code is modified, only new functionality is added following established patterns.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Areas requiring attention:

• Stripe adapter method implementations verify correct API endpoint paths and parameter mapping (authorize POST to /payment_intents, capture POST to /payment_intents/{paymentId}/capture, cancelAuthorization POST to /payment_intents/{paymentId}/cancel)
• Test assertions in StripeTest.php confirm correct response structure and status values for authorization, capture, and cancellation flows
• Ensure parameter handling aligns between abstract interface, Stripe implementation, and Pay facade delegates (particularly nullable paymentMethodId in authorize and optional amount in capture)

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Feat: authorize and capture payment' clearly and concisely summarizes the main feature addition, which is exactly what the PR implements.
Docstring Coverage	✅ Passed	Docstring coverage is 95.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat-capture

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/Pay/Adapter/Stripe.php (1)

94-101: Consider simplifying the empty array merge.

Line 97 merges an empty array with $additionalParams, which is redundant. You can simplify this to:

-    $requestBody = array_merge([], $additionalParams);
+    $requestBody = $additionalParams;

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fb39b22 and bfd5d2c.

📒 Files selected for processing (5)

• README.md (1 hunks)
• src/Pay/Adapter.php (1 hunks)
• src/Pay/Adapter/Stripe.php (1 hunks)
• src/Pay/Pay.php (1 hunks)
• tests/Pay/Adapter/StripeTest.php (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (3)

src/Pay/Adapter/Stripe.php (2)

src/Pay/Adapter.php (3)

• authorize (93-93)
• capture (104-104)
• cancelAuthorization (114-114)

src/Pay/Pay.php (3)

• authorize (101-104)
• capture (116-119)
• cancelAuthorization (130-133)

src/Pay/Pay.php (2)

src/Pay/Adapter.php (3)

• authorize (93-93)
• capture (104-104)
• cancelAuthorization (114-114)

src/Pay/Adapter/Stripe.php (3)

• authorize (54-71)
• capture (76-89)
• cancelAuthorization (94-101)

tests/Pay/Adapter/StripeTest.php (3)

src/Pay/Adapter.php (6)

• createPaymentMethod (164-164)
• createCustomer (213-213)
• authorize (93-93)
• capture (104-104)
• cancelAuthorization (114-114)
• deleteCustomer (248-248)

src/Pay/Adapter/Stripe.php (6)

• createPaymentMethod (191-208)
• createCustomer (289-305)
• authorize (54-71)
• capture (76-89)
• cancelAuthorization (94-101)
• deleteCustomer (349-355)

src/Pay/Pay.php (6)

• createPaymentMethod (205-208)
• createCustomer (284-287)
• authorize (101-104)
• capture (116-119)
• cancelAuthorization (130-133)
• deleteCustomer (321-324)

🔇 Additional comments (11)

README.md (1)

43-124: Excellent documentation structure!

The new Features section provides clear, practical examples for all major payment operations. The authorization/capture flow example effectively demonstrates the hold-and-charge pattern with proper error handling.

src/Pay/Pay.php (1)

89-134: LGTM! Clean facade delegation.

The three new methods (authorize, capture, cancelAuthorization) follow the established delegation pattern perfectly. The PHPDoc comments are clear and describe the business purpose of each operation.

src/Pay/Adapter.php (1)

83-114: LGTM! Well-defined adapter contract.

The three new abstract methods establish a clear interface for authorization/capture workflows. The optional $amount parameter in capture() enables partial capture scenarios, and $additionalParams across all methods provides good extensibility.

src/Pay/Adapter/Stripe.php (2)

54-71: LGTM! Correct Stripe authorization implementation.

The authorize() method correctly creates a payment intent with capture_method set to 'manual', which is the proper way to hold funds in Stripe. The inclusion of off_session and confirm parameters ensures the authorization happens immediately.

---

76-89: LGTM! Partial capture support implemented correctly.

The capture() method properly handles both full and partial captures using Stripe's amount_to_capture parameter. The conditional logic ensures the parameter is only sent when needed.

tests/Pay/Adapter/StripeTest.php (6)

593-619: LGTM! Good test setup pattern.

The testAuthorizeCaptureCancelFlow() method properly sets up the test data (customer and payment method) for the authorization/capture test chain using PHPUnit's @depends annotation.

---

621-646: LGTM! Comprehensive authorization test.

The test verifies all critical aspects of the authorization: object type, amount, status (requires_capture), and capture method (manual). The assertions confirm the payment is held correctly.

---

648-669: LGTM! Full capture test validates the workflow.

The test confirms that capturing a held payment succeeds and the full amount is received. The status transition from requires_capture to succeeded is verified.

---

671-697: LGTM! Partial capture test ensures flexibility.

This test validates that Stripe's partial capture functionality works correctly—authorizing 15000 but only capturing 10000. This is crucial for use cases where the final charge amount may be less than the authorization.

---

699-726: LGTM! Cancellation test validates the void flow.

The test confirms that authorized payments can be properly cancelled, releasing the hold on funds. The status transition to canceled is verified.

---

728-765: LGTM! Metadata test with proper cleanup.

This test validates that additional parameters (metadata and description) are correctly passed through to Stripe's API. The cleanup at lines 763-764 properly releases resources by cancelling the authorization and deleting the customer.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if the referenced guide file exists
fd -t f "payment-authorization-capture.md" docs/

Repository: utopia-php/pay

Length of output: 40

---

Verify the linked guide exists.

The documentation references docs/tutorials/payment-authorization-capture.md, but this file does not exist in the repository. Either add this file or update the link to an existing guide.

🤖 Prompt for AI Agents

In README.md around line 86, the link targets
docs/tutorials/payment-authorization-capture.md which is missing from the repo;
either add that markdown file with the referenced payment authorization and
capture tutorial to docs/tutorials/, or update the README to point to an
existing guide (e.g., correct path or alternate filename) and ensure the link is
valid and committed so it does not 404.