### Install Playwright

Source: https://github.com/shopware/swagpaypal/blob/trunk/tests/acceptance/README.md

Install the Chromium browser and necessary system dependencies for Playwright.

```bash
npx playwright install chromium
npx playwright install-deps
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/shopware/swagpaypal/blob/trunk/tests/acceptance/README.md

Install required npm packages for the project.

```bash
npm install
```

--------------------------------

### Plugin Lifecycle Hooks

Source: https://context7.com/shopware/swagpaypal/llms.txt

Outlines the required methods for handling plugin installation, updates, and activation within the main plugin class.

```php
<?php
use Shopware	estCore	estFramework	estPlugin	estContext	estInstallContext;
use Shopware	estCore	estFramework	estPlugin	estContext	estUpdateContext;
use Shopware	estCore	estFramework	estPlugin	estContext	estActivateContext;

// SwagPayPal main plugin class handles:

// Installation - creates payment methods, settings, POS sales channel type
public function install(InstallContext $installContext): void;

// Update - migrates settings, updates webhooks, refreshes payment methods
public function update(UpdateContext $updateContext): void;

// Activation - enables payment methods
public function activate(ActivateContext $activateContext): void;

// Deactivation - disables payment methods
public function deactivate(DeactivateContext $deactivateContext): void;

// Uninstall - removes data if keepUserData is false
public function uninstall(UninstallContext $uninstallContext): void;

// Custom fields stored on order transactions:
// SwagPayPal::ORDER_TRANSACTION_CUSTOM_FIELDS_PAYPAL_ORDER_ID - PayPal order ID
// SwagPayPal::ORDER_TRANSACTION_CUSTOM_FIELDS_PAYPAL_TRANSACTION_ID - Legacy transaction ID
// SwagPayPal::ORDER_TRANSACTION_CUSTOM_FIELDS_PAYPAL_RESOURCE_ID - Capture/Authorization ID
```

--------------------------------

### Get PayPal Order Details

Source: https://context7.com/shopware/swagpaypal/llms.txt

Retrieves order information via the Admin API.

```bash
curl -X GET "https://your-shop.com/api/paypal-v2/order/{orderTransactionId}/{paypalOrderId}" \
  -H "Authorization: Bearer {access_token}"
```

--------------------------------

### GET /api/paypal/pos/product-log/{salesChannelId}

Source: https://context7.com/shopware/swagpaypal/llms.txt

Retrieves the product synchronization log for a specific sales channel.

```APIDOC
## GET /api/paypal/pos/product-log/{salesChannelId}

### Description
Fetches the logs related to product synchronization for the given sales channel.

### Method
GET

### Endpoint
/api/paypal/pos/product-log/{salesChannelId}

### Parameters
#### Path Parameters
- **salesChannelId** (string) - Required - The UUID of the sales channel.

#### Query Parameters
- **limit** (integer) - Optional - Number of records to return.
- **page** (integer) - Optional - Page number for pagination.
```

--------------------------------

### GET /api/_action/paypal/merchant-information

Source: https://context7.com/shopware/swagpaypal/llms.txt

Retrieves merchant integration status and capabilities from PayPal. This endpoint helps in understanding the current PayPal integration status for a given sales channel.

```APIDOC
## GET /api/_action/paypal/merchant-information

### Description
Retrieves merchant integration status and capabilities from PayPal.

### Method
GET

### Endpoint
/api/_action/paypal/merchant-information

### Parameters
#### Query Parameters
- **salesChannelId** (string) - Required - The ID of the sales channel.

### Response
#### Success Response (200)
- **merchantIntegrations** (object) - An object containing merchant integration statuses.
  - **paypalOnboardingStatus** (string) - PayPal onboarding status.
  - **paypalPaymentStatus** (string) - PayPal payment status.
  - **acdcStatus** (string) - ACDC status.
  - **puiStatus** (string) - PUI status.
  - **vaultingStatus** (string) - Vaulting status.
- **merchantPayerId** (string) - The merchant payer ID.
- **email** (string) - The merchant's email address.

### Response Example
```json
{
  "merchantIntegrations": {
    "paypalOnboardingStatus": "SUBSCRIBED",
    "paypalPaymentStatus": "ACTIVE",
    "acdcStatus": "ACTIVE",
    "puiStatus": "ACTIVE",
    "vaultingStatus": "ACTIVE"
  },
  "merchantPayerId": "MERCHANT123",
  "email": "merchant@example.com"
}
```
```

--------------------------------

### GET /api/paypal-v2/order/{orderTransactionId}/{paypalOrderId}

Source: https://context7.com/shopware/swagpaypal/llms.txt

Retrieves full PayPal order details from the Admin API.

```APIDOC
## GET /api/paypal-v2/order/{orderTransactionId}/{paypalOrderId}

### Description
Retrieves full PayPal order details from the Admin API.

### Method
GET

### Endpoint
/api/paypal-v2/order/{orderTransactionId}/{paypalOrderId}

### Parameters
#### Path Parameters
- **orderTransactionId** (string) - Required - The internal order transaction ID.
- **paypalOrderId** (string) - Required - The PayPal order ID.

### Request Example
curl -X GET "https://your-shop.com/api/paypal-v2/order/{orderTransactionId}/{paypalOrderId}" \
  -H "Authorization: Bearer {access_token}"
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/shopware/swagpaypal/blob/trunk/tests/acceptance/README.md

Define required credentials and configuration in the .env file within the acceptance test directory.

```bash
APP_URL="<shop base url>"
PAYPAL_CLIENT_ID="<...>"
PAYPAL_CLIENT_SECRET="<...>"
PAYPAL_MERCHANT_ID="<...>"

# optional with default dev setup
SHOPWARE_ACCESS_KEY_ID="<your-api-client-id>"
SHOPWARE_SECRET_ACCESS_KEY="<your-api-secret>"
```

--------------------------------

### Navigate to Acceptance Test Directory

Source: https://github.com/shopware/swagpaypal/blob/trunk/tests/acceptance/README.md

Change the working directory to the acceptance test folder.

```bash
cd tests/acceptance
```

--------------------------------

### Create Order via Store API

Source: https://context7.com/shopware/swagpaypal/llms.txt

Initiates a PayPal order creation process using the Store API.

```bash
curl -X POST "https://your-shop.com/store-api/paypal/create-order" \
  -H "sw-access-key: {sales-channel-access-key}" \
  -H "sw-context-token: {context-token}" \
  -H "Content-Type: application/json"
```

--------------------------------

### Synchronize POS (Zettle) Products

Source: https://context7.com/shopware/swagpaypal/llms.txt

Use the API endpoints to trigger synchronization of products, images, and inventory, or manage sync logs and resets.

```bash
# Sync all (products, images, inventory)
curl -X POST "https://your-shop.com/api/_action/paypal/pos/sync/{salesChannelId}" \
  -H "Authorization: Bearer {access_token}"

# Response
{
  "runId": "sync-run-uuid-123"
}

# Sync products only
curl -X POST "https://your-shop.com/api/_action/paypal/pos/sync/{salesChannelId}/products" \
  -H "Authorization: Bearer {access_token}"

# Sync images only
curl -X POST "https://your-shop.com/api/_action/paypal/pos/sync/{salesChannelId}/images" \
  -H "Authorization: Bearer {access_token}"

# Sync inventory only
curl -X POST "https://your-shop.com/api/_action/paypal/pos/sync/{salesChannelId}/inventory" \
  -H "Authorization: Bearer {access_token}"

# Abort running sync
curl -X POST "https://your-shop.com/api/_action/paypal/pos/sync/abort/{runId}" \
  -H "Authorization: Bearer {access_token}"

# Reset sync (clears all sync data)
curl -X POST "https://your-shop.com/api/_action/paypal/pos/sync/reset/{salesChannelId}" \
  -H "Authorization: Bearer {access_token}"

# Get product sync log
curl -X GET "https://your-shop.com/api/paypal/pos/product-log/{salesChannelId}?limit=10&page=1" \
  -H "Authorization: Bearer {access_token}"
```

--------------------------------

### Execute Playwright Tests

Source: https://github.com/shopware/swagpaypal/blob/trunk/tests/acceptance/README.md

Run the acceptance test suite using the Playwright CLI.

```bash
npx playwright test
```

--------------------------------

### Settings Configuration

Source: https://context7.com/shopware/swagpaypal/llms.txt

Demonstrates how to access and retrieve PayPal plugin settings using Shopware's SystemConfigService. Settings can be accessed globally or scoped per sales channel.

```APIDOC
## Settings Configuration

The plugin uses Shopware's SystemConfig for configuration. Settings are stored under the `SwagPayPal.settings.` domain and can be scoped per sales channel.

```php
<?php
// Access PayPal settings via SystemConfigService
use Shopware\Core\System\SystemConfig\SystemConfigService;
use Swag\PayPal\Setting\Settings;

// Inject SystemConfigService via dependency injection
$systemConfigService = $container->get(SystemConfigService::class);

// Get client ID (sales channel specific or global)
$clientId = $systemConfigService->getString(Settings::CLIENT_ID, $salesChannelId);

// Check if sandbox mode is enabled
$isSandbox = $systemConfigService->getBool(Settings::SANDBOX, $salesChannelId);

// Get payment intent (capture or authorize)
$intent = $systemConfigService->getString(Settings::INTENT, $salesChannelId);

// Express Checkout settings
$ecsEnabled = $systemConfigService->getBool(Settings::ECS_DETAIL_ENABLED, $salesChannelId);
$ecsButtonColor = $systemConfigService->getString(Settings::ECS_BUTTON_COLOR, $salesChannelId);

// Vaulting settings for recurring payments
$vaultingWallet = $systemConfigService->getBool(Settings::VAULTING_ENABLED_WALLET, $salesChannelId);
$vaultingAcdc = $systemConfigService->getBool(Settings::VAULTING_ENABLED_ACDC, $salesChannelId);

// Default configuration values are defined in Settings::DEFAULT_VALUES
// Example defaults: SANDBOX => false, INTENT => 'CAPTURE', ECS_BUTTON_COLOR => 'gold'
```
```

--------------------------------

### POST /api/_action/paypal/pos/sync/{salesChannelId}

Source: https://context7.com/shopware/swagpaypal/llms.txt

Synchronizes products, images, and inventory from Shopware to the PayPal POS (Zettle) system.

```APIDOC
## POST /api/_action/paypal/pos/sync/{salesChannelId}

### Description
Synchronizes all products, images, and inventory for a specific sales channel.

### Method
POST

### Endpoint
/api/_action/paypal/pos/sync/{salesChannelId}

### Parameters
#### Path Parameters
- **salesChannelId** (string) - Required - The UUID of the sales channel to sync.

### Response
#### Success Response (200)
- **runId** (string) - The unique identifier for the sync process.

#### Response Example
{
  "runId": "sync-run-uuid-123"
}
```

--------------------------------

### Access PayPal Settings via SystemConfigService

Source: https://context7.com/shopware/swagpaypal/llms.txt

Retrieve plugin configuration values scoped by sales channel using the Shopware SystemConfigService.

```php
<?php
// Access PayPal settings via SystemConfigService
use Shopware\\Core\\System\\SystemConfig\\SystemConfigService;
use Swag\\PayPal\\Setting\\Settings;

// Inject SystemConfigService via dependency injection
$systemConfigService = $container->get(SystemConfigService::class);

// Get client ID (sales channel specific or global)
$clientId = $systemConfigService->getString(Settings::CLIENT_ID, $salesChannelId);

// Check if sandbox mode is enabled
$isSandbox = $systemConfigService->getBool(Settings::SANDBOX, $salesChannelId);

// Get payment intent (capture or authorize)
$intent = $systemConfigService->getString(Settings::INTENT, $salesChannelId);

// Express Checkout settings
$ecsEnabled = $systemConfigService->getBool(Settings::ECS_DETAIL_ENABLED, $salesChannelId);
$ecsButtonColor = $systemConfigService->getString(Settings::ECS_BUTTON_COLOR, $salesChannelId);

// Vaulting settings for recurring payments
$vaultingWallet = $systemConfigService->getBool(Settings::VAULTING_ENABLED_WALLET, $salesChannelId);
$vaultingAcdc = $systemConfigService->getBool(Settings::VAULTING_ENABLED_ACDC, $salesChannelId);

// Default configuration values are defined in Settings::DEFAULT_VALUES
// Example defaults: SANDBOX => false, INTENT => 'CAPTURE', ECS_BUTTON_COLOR => 'gold'
```

--------------------------------

### Generate Integration Access Key

Source: https://github.com/shopware/swagpaypal/blob/trunk/tests/acceptance/README.md

Use the Symfony console to create an integration access key for the acceptance tests.

```bash
bin/console integration:create AcceptanceTest --admin
```

--------------------------------

### Prepare Express Checkout

Source: https://context7.com/shopware/swagpaypal/llms.txt

Finalizes the checkout process by creating a customer account from PayPal data.

```bash
curl -X POST "https://your-shop.com/store-api/paypal/express/prepare-checkout" \
  -H "sw-access-key: {sales-channel-access-key}" \
  -H "sw-context-token: {context-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "paypalOrderId": "5O190127TN364715T"
  }'
```

--------------------------------

### POST /store-api/paypal/create-order

Source: https://context7.com/shopware/swagpaypal/llms.txt

Creates a standard PayPal order via the Store API.

```APIDOC
## POST /store-api/paypal/create-order

### Description
Creates a PayPal order and returns the PayPal order token.

### Method
POST

### Endpoint
/store-api/paypal/create-order

### Request Example
curl -X POST "https://your-shop.com/store-api/paypal/create-order" \
  -H "sw-access-key: {sales-channel-access-key}" \
  -H "sw-context-token: {context-token}" \
  -H "Content-Type: application/json"

### Response
#### Success Response (200)
- **token** (string) - The PayPal order token.

#### Response Example
{
  "token": "5O190127TN364715T"
}
```

--------------------------------

### POST /store-api/paypal/express/prepare-checkout

Source: https://context7.com/shopware/swagpaypal/llms.txt

Prepares the checkout process by creating a customer account from PayPal data.

```APIDOC
## POST /store-api/paypal/express/prepare-checkout

### Description
Prepares checkout by creating a customer account from PayPal data and updating the sales channel context.

### Method
POST

### Endpoint
/store-api/paypal/express/prepare-checkout

### Request Body
- **paypalOrderId** (string) - Required - The ID of the approved PayPal order.

### Request Example
curl -X POST "https://your-shop.com/store-api/paypal/express/prepare-checkout" \
  -H "sw-access-key: {sales-channel-access-key}" \
  -H "sw-context-token: {context-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "paypalOrderId": "5O190127TN364715T"
  }'

### Response
#### Success Response (200)
- **contextToken** (string) - The new context token containing the customer information.

#### Response Example
{
  "contextToken": "new-context-token-with-customer"
}
```

--------------------------------

### Retrieve Merchant Information

Source: https://context7.com/shopware/swagpaypal/llms.txt

Fetch the current integration status and capabilities for a specific sales channel.

```bash
# Get merchant information
curl -X GET "https://your-shop.com/api/_action/paypal/merchant-information?salesChannelId=abc123" \
  -H "Authorization: Bearer {access_token}"

# Response includes merchant capabilities
{
  "merchantIntegrations": {
    "paypalOnboardingStatus": "SUBSCRIBED",
    "paypalPaymentStatus": "ACTIVE",
    "acdcStatus": "ACTIVE",
    "puiStatus": "ACTIVE",
    "vaultingStatus": "ACTIVE"
  },
  "merchantPayerId": "MERCHANT123",
  "email": "merchant@example.com"
}
```

--------------------------------

### Save Plugin Settings

Source: https://context7.com/shopware/swagpaypal/llms.txt

Update configuration settings via the Admin API, which triggers automatic webhook registration.

```bash
# Save settings via Admin API
curl -X POST "https://your-shop.com/api/_action/paypal/save-settings" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "null": {
      "SwagPayPal.settings.clientId": "live-client-id",
      "SwagPayPal.settings.clientSecret": "live-client-secret",
      "SwagPayPal.settings.sandbox": false,
      "SwagPayPal.settings.intent": "CAPTURE",
      "SwagPayPal.settings.brandName": "My Shop",
      "SwagPayPal.settings.ecsDetailEnabled": true,
      "SwagPayPal.settings.spbCheckoutEnabled": true
    },
    "sales-channel-id-here": {
      "SwagPayPal.settings.sandbox": true,
      "SwagPayPal.settings.clientIdSandbox": "sandbox-client-id"
    }
  }'

# Response includes webhook registration result
{
  "null": {
    "webhookStatus": "REGISTERED",
    "webhookId": "WH-xxx"
  }
}
```

--------------------------------

### Test PayPal API Credentials

Source: https://context7.com/shopware/swagpaypal/llms.txt

Validate PayPal API credentials before saving them to the system configuration.

```bash
# Test API credentials via Admin API
curl -X POST "https://your-shop.com/api/_action/paypal/test-api-credentials" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-paypal-client-id",
    "clientSecret": "your-paypal-client-secret",
    "merchantPayerId": "your-merchant-payer-id",
    "sandboxActive": true
  }'

# Response
{
  "valid": true,
  "errors": []
}

# Invalid credentials response
{
  "valid": false,
  "errors": [
    {
      "code": "PAYPAL_API_AUTHENTICATION_ERROR",
      "detail": "Authentication failed"
    }
  ]
}
```

--------------------------------

### Implement Custom Payment Handler

Source: https://context7.com/shopware/swagpaypal/llms.txt

Extend AbstractPaymentMethodHandler to manage payment initiation, finalization, and recurring billing logic.

```php
<?php
use Shopware\\Core\\Checkout\\Payment\\Cart\\PaymentTransactionStruct;
use Shopware\\Core\\Framework\\Context;
use Swag\\PayPal\\Checkout\\Payment\\Method\\AbstractPaymentMethodHandler;
use Symfony\\Component\\HttpFoundation\\RedirectResponse;
use Symfony\\Component\\HttpFoundation\\Request;

// Payment handlers implement these key methods:
class CustomPayPalHandler extends AbstractPaymentMethodHandler
{
    // Called when payment is initiated
    public function pay(
        Request $request,
        PaymentTransactionStruct $transaction,
        Context $context,
        ?Struct $validateStruct
    ): ?RedirectResponse {
        // 1. Validate settings
        // 2. Create PayPal order or use existing order ID
        // 3. Store PayPal order ID in transaction custom fields
        // 4. Return redirect to PayPal if needed, or null if completed
        return parent::pay($request, $transaction, $context, $validateStruct);
    }

    // Called when customer returns from PayPal
    public function finalize(
        Request $request,
        PaymentTransactionStruct $transaction,
        Context $context
    ): void {
        // 1. Check for cancellation
        // 2. Execute (capture/authorize) the PayPal order
        // 3. Store resource IDs in custom fields
        parent::finalize($request, $transaction, $context);
    }

    // Called for subscription/recurring payments
    public function recurring(
        PaymentTransactionStruct $transaction,
        Context $context
    ): void {
        // Uses stored vault token for payment
        parent::recurring($transaction, $context);
    }

    protected function isVaultable(): bool
    {
        return true; // Enable token vaulting
    }

    protected function requirePreparedOrder(): bool
    {
        return false; // Create order server-side
    }
}
```

--------------------------------

### Refund Capture via Admin API

Source: https://context7.com/shopware/swagpaypal/llms.txt

Processes a refund for a previously captured payment.

```bash
# Refund a capture
curl -X POST "https://your-shop.com/api/_action/paypal-v2/refund-capture/{orderTransactionId}/{captureId}/{paypalOrderId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "currency": "EUR",
    "invoiceNumber": "REF-2024-001",
    "noteToPayer": "Partial refund for returned item"
  }'

# Response
{
  "id": "1JU08902781691411",
  "status": "COMPLETED",
  "amount": {
    "currency_code": "EUR",
    "value": "25.00"
  }
}
```

--------------------------------

### Manage Webhook Registrations

Source: https://context7.com/shopware/swagpaypal/llms.txt

Check status, register, or deregister webhooks for a specific sales channel.

```bash
# Check webhook status
curl -X GET "https://your-shop.com/api/_action/paypal/webhook/status/{salesChannelId}" \
  -H "Authorization: Bearer {access_token}"

# Response
{
  "result": "REGISTERED"
}

# Register webhook
curl -X POST "https://your-shop.com/api/_action/paypal/webhook/register/{salesChannelId}" \
  -H "Authorization: Bearer {access_token}"

# Deregister webhook
curl -X DELETE "https://your-shop.com/api/_action/paypal/webhook/deregister/{salesChannelId}" \
  -H "Authorization: Bearer {access_token}"
```

--------------------------------

### Create Order via OrderResource

Source: https://context7.com/shopware/swagpaypal/llms.txt

Uses the V2 Orders API to create a PayPal order programmatically.

```php
<?php
use Shopware\PayPalSDK\Struct\V2\Order;
use Shopware\PayPalSDK\Struct\V2\Order\PurchaseUnit;
use Shopware\PayPalSDK\Struct\V2\Order\PurchaseUnit\Amount;
use Swag\PayPal\RestApi\PartnerAttributionId;
use Swag\PayPal\RestApi\V2\Resource\OrderResource;

/** @var OrderResource $orderResource */

// Build the PayPal order
$paypalOrder = new Order();
$paypalOrder->setIntent('CAPTURE');

$purchaseUnit = new PurchaseUnit();
$amount = new Amount();
$amount->setCurrencyCode('EUR');
$amount->setValue('99.99');
$purchaseUnit->setAmount($amount);
$purchaseUnit->setReferenceId('shopware-order-123');
$paypalOrder->setPurchaseUnits([$purchaseUnit]);

// Create order with PayPal
$response = $orderResource->create(
    $paypalOrder,
    $salesChannelId,
    PartnerAttributionId::PAYPAL_PPCP,
    true, // minimalResponse
    'unique-request-id',
    null // metaDataId
);

$paypalOrderId = $response->getId();
$status = $response->getStatus(); // CREATED, APPROVED, COMPLETED, etc.
```

--------------------------------

### Create Express Checkout Order

Source: https://context7.com/shopware/swagpaypal/llms.txt

Creates an Express Checkout order with support for dynamic shipping calculations.

```bash
curl -X POST "https://your-shop.com/store-api/paypal/express/create-order" \
  -H "sw-access-key: {sales-channel-access-key}" \
  -H "sw-context-token: {context-token}" \
  -H "Content-Type: application/json"
```

```php
<?php
// Programmatic Express Checkout order creation
use Swag\PayPal\Checkout\ExpressCheckout\SalesChannel\ExpressCreateOrderRoute;
use Symfony\Component\HttpFoundation\Request;

// The route automatically:
// 1. Gets cart from current context
// 2. Validates cart has non-zero value
// 3. Builds PayPal order with shipping callback URL
// 4. Creates order via PayPal API

/** @var ExpressCreateOrderRoute $route */
$response = $route->createPayPalOrder($request, $salesChannelContext);
$paypalOrderId = $response->getToken();
```

--------------------------------

### Void Authorization via Admin API

Source: https://context7.com/shopware/swagpaypal/llms.txt

Releases held funds by voiding an existing authorization.

```bash
# Void an authorization
curl -X POST "https://your-shop.com/api/_action/paypal-v2/void-authorization/{orderTransactionId}/{authorizationId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerAttributionId": "Shopware_Cart_PPCP"
  }'

# Response: 204 No Content
```

--------------------------------

### POST /api/_action/paypal/pos/sync/abort/{runId}

Source: https://context7.com/shopware/swagpaypal/llms.txt

Aborts a currently running synchronization process.

```APIDOC
## POST /api/_action/paypal/pos/sync/abort/{runId}

### Description
Stops an active synchronization task identified by the runId.

### Method
POST

### Endpoint
/api/_action/paypal/pos/sync/abort/{runId}

### Parameters
#### Path Parameters
- **runId** (string) - Required - The UUID of the running sync process.
```

--------------------------------

### Set Default Payment Method

Source: https://context7.com/shopware/swagpaypal/llms.txt

Configures PayPal as the default payment method for a specific sales channel via the Admin API.

```bash
# Set PayPal as default
curl -X POST "https://your-shop.com/api/_action/paypal/saleschannel-default" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "salesChannelId": "sales-channel-uuid"
  }'
```

--------------------------------

### Check Payment Method Eligibility

Source: https://context7.com/shopware/swagpaypal/llms.txt

Queries the Store API to determine which payment methods are eligible based on cart and location context.

```bash
# Check payment method eligibility
curl -X POST "https://your-shop.com/store-api/paypal/payment-method-eligibility" \
  -H "sw-access-key: {sales-channel-access-key}" \
  -H "sw-context-token: {context-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethods": ["paypal", "card", "paylater", "venmo"]
  }'
```

--------------------------------

### Create PayPal Order (Store API)

Source: https://context7.com/shopware/swagpaypal/llms.txt

Creates a PayPal order from the current cart for checkout. This endpoint is part of the Store API and is used for initiating the PayPal payment process on the storefront.

```APIDOC
## Create PayPal Order (Store API)

### Description
Creates a PayPal order from the current cart for checkout.

### Method
POST

### Endpoint
/store-api/paypal/create-order

### Parameters
#### Request Body
- **cartId** (string) - Optional - The ID of the cart to create the order from. If not provided, the current cart is used.
- **paymentMethodId** (string) - Required - The ID of the PayPal payment method.

### Request Example
```json
{
  "cartId": "a1b2c3d4e5f6",
  "paymentMethodId": "paypal_payment_method_id"
}
```

### Response
#### Success Response (200)
- **orderId** (string) - The ID of the created PayPal order.
- **paypalCreateOrderUrl** (string) - The URL to redirect the user to for PayPal checkout.

#### Response Example
```json
{
  "orderId": "paypal_order_id_12345",
  "paypalCreateOrderUrl": "https://www.paypal.com/checkoutnow?token=EC-xxxxxxxxxxxxxxx"
}
```
```

--------------------------------

### POST /api/_action/paypal/save-settings

Source: https://context7.com/shopware/swagpaypal/llms.txt

Saves plugin configuration settings, including automatic webhook registration and validation. This endpoint allows for updating global and sales channel-specific settings.

```APIDOC
## POST /api/_action/paypal/save-settings

### Description
Saves plugin configuration with automatic webhook registration and validation.

### Method
POST

### Endpoint
/api/_action/paypal/save-settings

### Parameters
#### Request Body
- **null** (object) - Global settings.
  - **SwagPayPal.settings.clientId** (string) - The PayPal Client ID for live environment.
  - **SwagPayPal.settings.clientSecret** (string) - The PayPal Client Secret for live environment.
  - **SwagPayPal.settings.sandbox** (boolean) - Whether sandbox mode is enabled.
  - **SwagPayPal.settings.intent** (string) - The payment intent (e.g., 'CAPTURE', 'AUTHORIZE').
  - **SwagPayPal.settings.brandName** (string) - The brand name displayed on PayPal transactions.
  - **SwagPayPal.settings.ecsDetailEnabled** (boolean) - Enables Express Checkout on the detail page.
  - **SwagPayPal.settings.spbCheckoutEnabled** (boolean) - Enables Smart Payment Buttons on the checkout page.
- **sales-channel-id-here** (object) - Sales channel specific settings.
  - **SwagPayPal.settings.sandbox** (boolean) - Whether sandbox mode is enabled for this sales channel.
  - **SwagPayPal.settings.clientIdSandbox** (string) - The PayPal Client ID for sandbox environment.

### Request Example
```json
{
  "null": {
    "SwagPayPal.settings.clientId": "live-client-id",
    "SwagPayPal.settings.clientSecret": "live-client-secret",
    "SwagPayPal.settings.sandbox": false,
    "SwagPayPal.settings.intent": "CAPTURE",
    "SwagPayPal.settings.brandName": "My Shop",
    "SwagPayPal.settings.ecsDetailEnabled": true,
    "SwagPayPal.settings.spbCheckoutEnabled": true
  },
  "sales-channel-id-here": {
    "SwagPayPal.settings.sandbox": true,
    "SwagPayPal.settings.clientIdSandbox": "sandbox-client-id"
  }
}
```

### Response
#### Success Response (200)
- **null** (object) - Webhook registration status.
  - **webhookStatus** (string) - The status of webhook registration (e.g., 'REGISTERED').
  - **webhookId** (string) - The ID of the registered webhook.

#### Response Example
```json
{
  "null": {
    "webhookStatus": "REGISTERED",
    "webhookId": "WH-xxx"
  }
}
```
```

--------------------------------

### Implement Custom Webhook Handler

Source: https://context7.com/shopware/swagpaypal/llms.txt

Extend AbstractWebhookHandler to process specific PayPal events. Ensure the getEventType method returns the correct event string.

```php
<?php
use Shopware\Core\Framework\Context;
use Shopware\PayPalSDK\Struct\V1\Webhook\Event;
use Swag\PayPal\Webhook\Handler\AbstractWebhookHandler;

// Custom webhook handler example
class CustomWebhookHandler extends AbstractWebhookHandler
{
    public function getEventType(): string
    {
        return 'PAYMENT.CAPTURE.COMPLETED';
    }

    public function invoke(Event $webhook, Context $context): void
    {
        // Get the related order transaction
        $orderTransaction = $this->getOrderTransactionV2(
            $webhook->getResource(),
            $context
        );

        // Process the webhook event
        $paypalOrderId = $webhook->getResource()->getId();

        // Update order state, send notifications, etc.
    }
}

// Supported event types include:
// PAYMENT.AUTHORIZATION.CREATED, PAYMENT.AUTHORIZATION.VOIDED
// PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.REFUNDED
// CHECKOUT.ORDER.APPROVED, CHECKOUT.ORDER.COMPLETED
// VAULT.PAYMENT-TOKEN.CREATED, VAULT.PAYMENT-TOKEN.DELETED
// CUSTOMER.DISPUTE.CREATED, CUSTOMER.DISPUTE.RESOLVED
```

--------------------------------

### Capture Authorization via Admin API

Source: https://context7.com/shopware/swagpaypal/llms.txt

Captures a previously authorized payment using the order transaction and authorization IDs.

```bash
# Capture an authorization
curl -X POST "https://your-shop.com/api/_action/paypal-v2/capture-authorization/{orderTransactionId}/{authorizationId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "50.00",
    "currency": "EUR",
    "invoiceNumber": "INV-2024-001",
    "noteToPayer": "Thank you for your order",
    "isFinal": false
  }'

# Response
{
  "id": "3C679366HH908993F",
  "status": "COMPLETED",
  "amount": {
    "currency_code": "EUR",
    "value": "50.00"
  }
}
```

--------------------------------

### POST /store-api/paypal/express/create-order

Source: https://context7.com/shopware/swagpaypal/llms.txt

Creates a PayPal Express Checkout order with support for dynamic shipping calculations.

```APIDOC
## POST /store-api/paypal/express/create-order

### Description
Creates a PayPal Express Checkout order with shipping callback support.

### Method
POST

### Endpoint
/store-api/paypal/express/create-order

### Request Example
curl -X POST "https://your-shop.com/store-api/paypal/express/create-order" \
  -H "sw-access-key: {sales-channel-access-key}" \
  -H "sw-context-token: {context-token}" \
  -H "Content-Type: application/json"

### Response
#### Success Response (200)
- **token** (string) - The Express Checkout token.

#### Response Example
{
  "token": "EC-1234567890"
}
```

--------------------------------

### Authorize Order

Source: https://context7.com/shopware/swagpaypal/llms.txt

Authorizes an order to hold funds for later capture.

```php
<?php
use Swag\PayPal\RestApi\V2\Resource\OrderResource;
use Swag\PayPal\RestApi\PartnerAttributionId;

/** @var OrderResource $orderResource */

// Authorize the order (hold funds without capturing)
$authorizedOrder = $orderResource->authorize(
    $paypalOrderId,
    $salesChannelId,
    PartnerAttributionId::PAYPAL_PPCP,
    false
);

$authorization = $authorizedOrder->getPurchaseUnits()[0]->getPayments()->getAuthorizations()[0];
$authorizationId = $authorization->getId();
// Authorization is valid for up to 29 days
```

--------------------------------

### Capture and Void Authorization

Source: https://context7.com/shopware/swagpaypal/llms.txt

Uses the AuthorizationResource to perform partial captures or void existing PayPal authorizations.

```php
<?php
use Shopware	estPayPalSDK	estStruct	estV2	estOrder	estPurchaseUnit	estPayments	estCapture;
use Shopware	estPayPalSDK	estStruct	estV2	estOrder	estPurchaseUnit	estAmount;
use Swag	estPayPal	estRestApi	estV2	estResource	estAuthorizationResource;
use Swag	estPayPal	estRestApi	estPartnerAttributionId;

/** @var AuthorizationResource $authorizationResource */

// Create capture object for partial capture
$capture = new Capture();
$amount = new Amount();
$amount->setCurrencyCode('EUR');
$amount->setValue('50.00');
$capture->setAmount($amount);
$capture->setInvoiceId('INV-123');
$capture->setFinalCapture(false); // Allow additional captures

// Execute capture
$captureResponse = $authorizationResource->capture(
    $authorizationId,
    $capture,
    $salesChannelId,
    PartnerAttributionId::PAYPAL_PPCP,
    false
);

// Void an authorization
$authorizationResource->void(
    $authorizationId,
    $salesChannelId,
    PartnerAttributionId::PAYPAL_PPCP
);
```

--------------------------------

### POST /api/_action/paypal/saleschannel-default

Source: https://context7.com/shopware/swagpaypal/llms.txt

Sets PayPal as the default payment method for a specific sales channel.

```APIDOC
## POST /api/_action/paypal/saleschannel-default

### Description
Sets PayPal as the default payment method for a sales channel.

### Method
POST

### Endpoint
/api/_action/paypal/saleschannel-default

### Request Body
- **salesChannelId** (string) - Required - The UUID of the sales channel.

### Request Example
{
  "salesChannelId": "sales-channel-uuid"
}
```

--------------------------------

### POST /api/_action/paypal/test-api-credentials

Source: https://context7.com/shopware/swagpaypal/llms.txt

Validates PayPal API credentials by sending them to the PayPal API. This endpoint is useful for ensuring that the provided credentials are correct before saving them.

```APIDOC
## POST /api/_action/paypal/test-api-credentials

### Description
Validates PayPal API credentials before saving them in configuration.

### Method
POST

### Endpoint
/api/_action/paypal/test-api-credentials

### Parameters
#### Request Body
- **clientId** (string) - Required - The PayPal Client ID.
- **clientSecret** (string) - Required - The PayPal Client Secret.
- **merchantPayerId** (string) - Required - The PayPal Merchant Payer ID.
- **sandboxActive** (boolean) - Required - Indicates if the sandbox environment is active.

### Request Example
```json
{
  "clientId": "your-paypal-client-id",
  "clientSecret": "your-paypal-client-secret",
  "merchantPayerId": "your-merchant-payer-id",
  "sandboxActive": true
}
```

### Response
#### Success Response (200)
- **valid** (boolean) - Indicates if the credentials are valid.
- **errors** (array) - A list of errors if the credentials are not valid.

#### Response Example
```json
{
  "valid": true,
  "errors": []
}
```

#### Error Response Example
```json
{
  "valid": false,
  "errors": [
    {
      "code": "PAYPAL_API_AUTHENTICATION_ERROR",
      "detail": "Authentication failed"
    }
  ]
}
```
```

--------------------------------

### Capture Approved Order

Source: https://context7.com/shopware/swagpaypal/llms.txt

Captures funds for an approved PayPal order.

```php
<?php
use Swag\PayPal\RestApi\V2\Resource\OrderResource;
use Swag\PayPal\RestApi\PartnerAttributionId;

/** @var OrderResource $orderResource */

// Capture the approved order
$capturedOrder = $orderResource->capture(
    $paypalOrderId,
    $salesChannelId,
    PartnerAttributionId::PAYPAL_PPCP,
    false // full response
);

// Access capture details
$payments = $capturedOrder->getPurchaseUnits()[0]->getPayments();
$capture = $payments->getCaptures()[0];
$captureId = $capture->getId();
$status = $capture->getStatus(); // COMPLETED, PENDING, etc.
```

--------------------------------

### POST /api/_action/paypal-v2/refund-capture/{orderTransactionId}/{captureId}/{paypalOrderId}

Source: https://context7.com/shopware/swagpaypal/llms.txt

Refunds a captured payment.

```APIDOC
## POST /api/_action/paypal-v2/refund-capture/{orderTransactionId}/{captureId}/{paypalOrderId}

### Description
Refunds a captured payment.

### Method
POST

### Endpoint
/api/_action/paypal-v2/refund-capture/{orderTransactionId}/{captureId}/{paypalOrderId}

### Parameters
#### Path Parameters
- **orderTransactionId** (string) - Required - The ID of the order transaction.
- **captureId** (string) - Required - The ID of the capture to refund.
- **paypalOrderId** (string) - Required - The PayPal order ID.

#### Request Body
- **amount** (string) - Required - The amount to refund.
- **currency** (string) - Required - The currency code.
- **invoiceNumber** (string) - Optional - The invoice number.
- **noteToPayer** (string) - Optional - A note to the payer.

### Request Example
{
  "amount": "25.00",
  "currency": "EUR",
  "invoiceNumber": "REF-2024-001",
  "noteToPayer": "Partial refund for returned item"
}

### Response
#### Success Response (200)
- **id** (string) - The refund ID.
- **status** (string) - The status of the refund.
- **amount** (object) - The refunded amount details.

#### Response Example
{
  "id": "1JU08902781691411",
  "status": "COMPLETED",
  "amount": {
    "currency_code": "EUR",
    "value": "25.00"
  }
}
```

--------------------------------

### Manage Order Tracking

Source: https://context7.com/shopware/swagpaypal/llms.txt

Adds or removes shipment tracking information for PayPal orders via the OrderResource.

```php
<?php
use Shopware	estPayPalSDK	estStruct	estV2	estOrder	estTracker;
use Swag	estPayPal	estRestApi	estV2	estResource	estOrderResource;
use Swag	estPayPal	estRestApi	estPartnerAttributionId;

/** @var OrderResource $orderResource */

// Create tracker
$tracker = new Tracker();
$tracker->setTransactionId($paypalOrderId);
$tracker->setTrackingNumber('1Z999AA10123456784');
$tracker->setCarrier('UPS');
$tracker->setNotifyPayer(true);

// Add tracking to order
$orderResource->addTracker(
    $tracker,
    $paypalOrderId,
    $salesChannelId,
    PartnerAttributionId::PAYPAL_PPCP
);

// Remove tracking
$orderResource->removeTracker(
    $tracker,
    $paypalOrderId,
    $salesChannelId,
    PartnerAttributionId::PAYPAL_PPCP
);
```

--------------------------------

### Webhook Management API

Source: https://context7.com/shopware/swagpaypal/llms.txt

Endpoints for checking status, registering, and deregistering PayPal webhooks.

```APIDOC
## GET /api/_action/paypal/webhook/status/{salesChannelId}

### Description
Checks the registration status of a webhook for a specific sales channel.

### Method
GET

### Endpoint
/api/_action/paypal/webhook/status/{salesChannelId}

## POST /api/_action/paypal/webhook/register/{salesChannelId}

### Description
Registers a webhook for a specific sales channel.

### Method
POST

### Endpoint
/api/_action/paypal/webhook/register/{salesChannelId}

## DELETE /api/_action/paypal/webhook/deregister/{salesChannelId}

### Description
Deregisters a webhook for a specific sales channel.

### Method
DELETE

### Endpoint
/api/_action/paypal/webhook/deregister/{salesChannelId}
```

--------------------------------

### POST /api/_action/paypal-v2/capture-authorization/{orderTransactionId}/{authorizationId}

Source: https://context7.com/shopware/swagpaypal/llms.txt

Captures a previously authorized payment from the admin panel.

```APIDOC
## POST /api/_action/paypal-v2/capture-authorization/{orderTransactionId}/{authorizationId}

### Description
Captures a previously authorized payment from the admin panel.

### Method
POST

### Endpoint
/api/_action/paypal-v2/capture-authorization/{orderTransactionId}/{authorizationId}

### Parameters
#### Path Parameters
- **orderTransactionId** (string) - Required - The ID of the order transaction.
- **authorizationId** (string) - Required - The ID of the authorization to capture.

#### Request Body
- **amount** (string) - Required - The amount to capture.
- **currency** (string) - Required - The currency code.
- **invoiceNumber** (string) - Optional - The invoice number.
- **noteToPayer** (string) - Optional - A note to the payer.
- **isFinal** (boolean) - Optional - Whether this is the final capture.

### Request Example
{
  "amount": "50.00",
  "currency": "EUR",
  "invoiceNumber": "INV-2024-001",
  "noteToPayer": "Thank you for your order",
  "isFinal": false
}

### Response
#### Success Response (200)
- **id** (string) - The capture ID.
- **status** (string) - The status of the capture.
- **amount** (object) - The captured amount details.

#### Response Example
{
  "id": "3C679366HH908993F",
  "status": "COMPLETED",
  "amount": {
    "currency_code": "EUR",
    "value": "50.00"
  }
}
```

--------------------------------

### POST /api/_action/paypal-v2/void-authorization/{orderTransactionId}/{authorizationId}

Source: https://context7.com/shopware/swagpaypal/llms.txt

Voids an authorization to release the held funds.

```APIDOC
## POST /api/_action/paypal-v2/void-authorization/{orderTransactionId}/{authorizationId}

### Description
Voids an authorization to release the held funds.

### Method
POST

### Endpoint
/api/_action/paypal-v2/void-authorization/{orderTransactionId}/{authorizationId}

### Parameters
#### Path Parameters
- **orderTransactionId** (string) - Required - The ID of the order transaction.
- **authorizationId** (string) - Required - The ID of the authorization to void.

#### Request Body
- **partnerAttributionId** (string) - Optional - The partner attribution ID.

### Request Example
{
  "partnerAttributionId": "Shopware_Cart_PPCP"
}

### Response
#### Success Response (204)
- No content returned.
```

--------------------------------

### POST /store-api/paypal/payment-method-eligibility

Source: https://context7.com/shopware/swagpaypal/llms.txt

Checks and stores payment method eligibility based on cart content and customer location.

```APIDOC
## POST /store-api/paypal/payment-method-eligibility

### Description
Checks and stores payment method eligibility based on cart content and customer location.

### Method
POST

### Endpoint
/store-api/paypal/payment-method-eligibility

### Request Body
- **paymentMethods** (array) - Required - List of payment methods to check (e.g., ["paypal", "card", "paylater", "venmo"])

### Request Example
{
  "paymentMethods": ["paypal", "card", "paylater", "venmo"]
}
```

--------------------------------

### Refund Captured Payments

Source: https://context7.com/shopware/swagpaypal/llms.txt

Process a refund for a specific capture ID using the CaptureResource and PayPal SDK structures.

```php
<?php
use Shopware\\PayPalSDK\\Struct\\V2\\Order\\PurchaseUnit\\Payments\\Refund;
use Shopware\\PayPalSDK\\Struct\\V2\\Order\\PurchaseUnit\\Amount;
use Swag\\PayPal\\RestApi\\V2\\Resource\\CaptureResource;
use Swag\\PayPal\\RestApi\\PartnerAttributionId;

/** @var CaptureResource $captureResource */

// Create refund object
$refund = new Refund();
$amount = new Amount();
$amount->setCurrencyCode('EUR');
$amount->setValue('25.00');
$refund->setAmount($amount);
$refund->setInvoiceId('REFUND-123');
$refund->setNoteToPayer('Refund for returned item');

// Execute refund
$refundResponse = $captureResource->refund(
    $captureId,
    $refund,
    $salesChannelId,
    PartnerAttributionId::PAYPAL_PPCP,
    false // full response
);

$refundId = $refundResponse->getId();
$refundStatus = $refundResponse->getStatus(); // COMPLETED, PENDING, etc.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.