# SumUp Payment Gateway Extension for Bagisto

## Overview
A production-grade Bagisto payment method extension that integrates SumUp Checkout. It uses the SumUp JS widget for the inline checkout experience and robustly updates Bagisto order status via SumUp Webhooks.

## Installation Guide

1. **Place Package:** Ensure this repository maps to `packages/SumUp/Payment` in your Bagisto directory.
2. **Setup Autoloader:** Add the PSR-4 namespace to your root `composer.json` or verify it.
   ```json
   "autoload": {
       "psr-4": {
           "SumUp\\Payment\\": "packages/SumUp/Payment/src/"
       }
   }
   ```
3. **Register Service Provider:** Add the provider in `config/app.php`:
   ```php
   SumUp\Payment\Providers\SumUpPaymentServiceProvider::class,
   ```
4. **Dump Autoload:** Run `composer dump-autoload`
5. **Clear Cache:** Run `php artisan optimize:clear`
6. **Enable in Admin:** You must go to your Bagisto Admin Panel -> Configuration -> Sales -> Payment Methods. Look for "SumUp Payment Gateway" and complete the configuration.

## System Configuration Needed
- **Active:** Turn the method "on"
- **Environment:** Production or Sandbox
- **API Key:** Retrieve your server API key from your SumUp Dashboard.
- **Merchant Code:** Enter your SumUp merchant code / Profile ID.
- **Webhook Secret:** You can enter a custom string here to validate incoming calls (via `?secret=` query arg or `X-SumUp-Signature` header).

## Webhooks
Configure your webhook endpoint in your SumUp Dashboard to point to:
`https://your-domain.com/sumup/webhook?secret=YOUR_WEBHOOK_SECRET`
Subscribe to:
- `checkout.status.paid`
- `checkout.status.failed`

## Test Plan
- **Sandbox Happy Path**: Make a test purchase on frontend. Complete form. Ensure SumUp widget renders, processes test payment, verify Bagisto Order generates an Invoice (goes to Processing).
- **Failed Payment**: Deny or fail the transaction sandbox card. Verify webhook cancels the standard order.
- **Webhook Idempotency**: Simulate delivering the `PAID` payload twice. Verify that only one invoice is generated per core Bagisto order.

## Advanced Features / Edge Cases Covered
- **Multi-Currency Processing**: If your Bagisto store calculates totals in a different currency than your SumUp merchant account accepts, the plugin will automatically convert the `base_grand_total` to the configured `Supported Currency` in the Admin panel before processing the charge.
- **Refunds**: Full and partial refunds triggered from the Bagisto Admin Order interface are automatically connected to the SumUp API, reversing the exact captured transaction balance.

## Known Limitations / Assumptions
- **Stored Credit Cards (Vaulting)**: The standard SumUp form widget utilized here processes the payment and abandons the token. "1-click" future checkout for returning customers (vaulting) is not currently implemented.
- **Form Widget**: usage requires the user to stay on the page until redirected to the return_url for an immediate success page, but asynchronous webhooks will cover early exits.