Api Platform Payze Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require daniil-trukhan/api_platform_payze
   

   Ensure your project uses API Platform (api/platform-core).

2. Configure Payze API Key Add your Payze API key to .env:

   PAYZE_API_KEY=your_api_key_here
   

3. Basic Usage Inject the PayzeService into a controller or command:

   use DaniilTrukhan\ApiPlatformPayze\PayzeService;
   
   public function __construct(private PayzeService $payze) {}
   

4. First Use Case: Create a Payment

   $payment = $this->payze->createPayment(
       amount: 1000, // in minor units (e.g., cents)
       currency: 'USD',
       description: 'Order #123',
       email: 'customer@example.com'
   );
   

Implementation Patterns

Workflows

1. Payment Processing

   • Create Payment: Use createPayment() for one-time payments.
   • Subscription Management: Use createSubscription() for recurring payments.
   • Webhook Handling: Extend PayzeWebhookHandler to process Payze callbacks (e.g., payment success/failure).

2. Integration with API Platform

   • State Provider: Use PayzeStateProvider to sync payment states (e.g., pending, completed).
   • Resource Classes: Extend PayzePayment or PayzeSubscription to expose endpoints:

     #[ApiResource(
         operations: [new Get(), new Post()],
         stateProvider: PayzeStateProvider::class
     )]
     class Payment {}
     

3. Command-Based Tasks

   • Schedule refunds or subscription cancellations via Artisan commands:

     $this->payze->refundPayment($paymentId);
     

Tips for Daily Use

• Logging: Enable debug logs for Payze API calls in config/logging.php.
• Testing: Mock PayzeService in unit tests:

  $this->mock(PayzeService::class)->shouldReceive('createPayment')->once();
  

Gotchas and Tips

Pitfalls

1. Currency/Amount Units

   • Payze expects amounts in minor units (e.g., 1000 for $10.00). Misconfiguration causes failed transactions.

2. Webhook Verification

   • Always validate Payze webhook signatures. Use PayzeWebhookHandler::verifySignature():

     if (!$handler->verifySignature($request->getContent(), $request->headers->get('X-Signature'))) {
         abort(403);
     }
     

3. Rate Limits

   • Payze API has rate limits. Cache responses for non-critical operations.

Debugging

• API Errors: Check PayzeService logs for HTTP errors (e.g., 429 Too Many Requests).
• Webhook Failures: Test locally with PAYZE_WEBHOOK_SECRET and PAYZE_WEBHOOK_URL.

Extension Points

1. Custom Fields Override PayzeService to add metadata:

   $payment = $this->payze->createPayment(..., [
       'custom_field' => 'value'
   ]);
   

2. State Transitions Extend PayzeStateProvider to handle custom states (e.g., fraud_review).

3. Retry Logic Implement exponential backoff for failed API calls in PayzeClient.