### Install via Composer

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Install the srmklive/paypal package using Composer.

```bash
composer require srmklive/paypal
```

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

### Basic subscription setup example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Creates a subscription for 'Jane Doe' with email 'jane@example.com'. After success, the response contains 'id', 'status', and an approve link at 'links[0].href'.

```php
$subscription = $provider->setupSubscription('Jane Doe', 'jane@example.com');

// $subscription['id'], $subscription['status'], approve link:
// $subscription['links'][0]['href']
```

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

### Example: addProduct with monthly plan and setup fee

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Shows a chained call to addProduct, addMonthlyPlan, addSetupFee, addTaxes, addShippingAddress, and addCustomId. addProduct() calls createProduct() and omits empty description; addSetupFee() enables has_setup_fee and builds payment_preferences with setup_fee (auto_bill_outstanding: true, setup_fee_failure_action: CONTINUE).

```php
$provider
    ->addProduct('Monthly Coffee', 'Subscription box', 'SERVICE', 'DIGITAL_GOODS')
    ->addMonthlyPlan('Coffee Plan', 'One bag monthly', 19.99)
    ->addSetupFee(5.00)
    ->addTaxes(8.25)
    ->addShippingAddress('Jane Doe', '1 Main St', '', 'San Jose', 'CA', '95131', 'US')
    ->addCustomId('customer-123');
```

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

### Create partner referral example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/identity.md

Example of creating a partner referral with operations, products, and legal consents. Extracts the approval URL from the response links.

```php
$referral = $provider->createPartnerReferral([
    'operations' => [[
        'operation' => 'API_INTEGRATION',
        'api_integration_preference' => [
            'rest_api_integration' => [
                'integration_method' => 'PAYPAL',
                'integration_type' => 'THIRD_PARTY',
                'third_party_details' => ['features' => ['PAYMENT', 'REFUND']],
            ],
        ],
    ]],
    'products' => ['EXPRESS_CHECKOUT'],
    'legal_consents' => [['type' => 'SHARE_DATA_CONSENT', 'granted' => true]],
]);
$referralId = $referral['links'][0]['href'] ?? null;  // extract approval URL for the seller
```

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

### Full checkout example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/experience-context.md

Complete example showing how to set brand name, return/cancel URLs, and payment source PayPal, then create an order with payment source.

```php
$provider
    ->setBrandName('Acme Store')
    ->setReturnAndCancelUrl('https://example.com/success', 'https://example.com/cancel')
    ->setPaymentSourcePayPal([]); // paypal method receives the experience context

$order = $provider->createOrderWithPaymentSource([
    'intent' => 'CAPTURE',
    'purchase_units' => [['amount' => ['currency_code' => 'USD', 'value' => '20.00']]],
]);
```

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

### Create a billing plan with trial periods and setup fee

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Builds a plan with multiple trial cycles, a regular monthly cycle, a setup fee, and tax. Cycles are sequenced automatically in the order added; totalCycles: 0 means indefinite.

```php
$response = BillingPlanBuilder::make()
    ->forProduct('PROD-XXCD1234QWER65782')
    ->named('Video Streaming Plan', 'Video Streaming Service basic plan')
    ->trialMonthly(3.00, totalCycles: 2)   // $3/mo for 2 months
    ->trialMonthly(6.00, totalCycles: 3)   // $6/mo for 3 months
    ->monthly(10.00, totalCycles: 12)      // $10/mo for 12 months
    ->withSetupFee(10.00)
    ->withTax(10.0)
    ->create($provider);
```

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

### Example: addProduct with trial pricing and monthly plan

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Shows a chained call to addProduct, addPlanTrialPricing, and addMonthlyPlan. When addPlanTrialPricing() is called first, the plan gets a TRIAL cycle (sequence 1) followed by the regular cycle (sequence 2). A plan already set short-circuits the shortcuts.

```php
$provider
    ->addProduct('SaaS Pro', '', 'SERVICE', 'SOFTWARE')
    ->addPlanTrialPricing('MONTH', 1, 0, 1)   // 1 free month
    ->addMonthlyPlan('Pro', 'Pro tier', 29.00, 12);
```

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

### create() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/billing-plan-builder.md

Creates a premium plan with a trial period, monthly billing, setup fee, and tax. The provider must be initialized with a valid access token. Checks for an 'error' key in the response and extracts the plan ID from 'id'.

```php
use Srmklive\PayPal\Builders\BillingPlanBuilder;

$response = BillingPlanBuilder::make()
    ->forProduct('PROD-XXCD1234QWER65782')
    ->named('Premium Plan', 'Monthly premium access')
    ->trialMonthly(3.00, totalCycles: 2)
    ->monthly(10.00, totalCycles: 12)
    ->withSetupFee(10.00)
    ->withTax(10.0)
    ->create($provider);

if (isset($response['error'])) {
    // PayPal rejected the plan — inspect $response['error']
}
$planId = $response['id'] ?? null;
```

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

### BillingPlanBuilder::withSetupFee()

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/billing-plan-builder.md

Sets a setup fee charged when the subscription starts. The failure action determines what happens if the setup fee payment fails.

```APIDOC
## BillingPlanBuilder::withSetupFee()

### Description
Sets a setup fee charged when the subscription starts. The failure action determines what happens if the setup fee payment fails.

### Method
`public function withSetupFee(float $amount, string $failureAction = 'CONTINUE'): static`

### Parameters
- **$amount** (float) - Required - The setup fee amount.
- **$failureAction** (string) - Optional - The action to take on failure. Must be 'CONTINUE' or 'CANCEL'. 'CANCEL_SUBSCRIPTION' is accepted as a deprecated alias for 'CANCEL'. Anything else throws \InvalidArgumentException. Defaults to 'CONTINUE'.

### Return Value
- **static** - The builder instance for method chaining.

### Example
```php
$builder->withSetupFee(10.00, 'CANCEL');
```
```

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

### Payment Method Tokens - Fluent Helper

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Use the fluent helper to convert a setup token into a payment token. setTokenSource() requires a token source and a type. sendPaymentMethodRequest(true) creates a setup token instead, but only with card/PayPal/Venmo sources, not with a token source.

```php
$response = $provider->setTokenSource('5C991763VB2781612', 'SETUP_TOKEN')
    ->setCustomerId('customer_4029352050')
    ->sendPaymentMethodRequest(); // converts the setup token into a payment token
// ->sendPaymentMethodRequest(true) creates a setup token instead; use it with
// card/PayPal/Venmo sources (setPaymentSourceCard() etc.), not with a token source
```

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

### createOrderWithPaymentSource() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/orders.md

Example showing how to set a card payment source, billing address, return/cancel URLs, and create an order with CAPTURE intent.

```php
$provider
    ->setPaymentSourceCard([
        'number' => '4111111111111111',
        'expiry' => '2027-01',
        'name' => 'Test User',
    ])
    ->setCardBillingAddress('1 Main St', 'San Jose', 'CA', '95131', 'US')
    ->setReturnAndCancelUrl('https://example.com/success', 'https://example.com/cancel');

$order = $provider->createOrderWithPaymentSource([
    'intent' => 'CAPTURE',
    'purchase_units' => [['amount' => ['currency_code' => 'USD', 'value' => '10.00']]],
]);
```

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

### Generate QR Code Example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/invoices.md

Example of generating a QR code and displaying it as an image.

```php
$qr = $provider->generateQRCodeInvoice($invoiceId, width: 300, height: 300);
echo '<img src="data:image/png;base64,'.$qr.'">';
```

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

### showRefundDetails() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/payments.md

Example call to retrieve refund details using the provider.

```php
$refund = $provider->showRefundDetails($refundId);
```

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

### Show seller status example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/identity.md

Example of retrieving seller status using partner ID and merchant ID. The response contains fields like `merchant_id` and `payments_receivable`.

```php
$status = $provider->showSellerStatus($partnerId, $merchantId);
// $status['merchant_id'], $status['payments_receivable'] etc.
```

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

### Make offer example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/disputes.md

Example call to makeOfferToResolveDispute() with a partial refund offer of 25.00 and refund type REFUND.

```php
$provider->makeOfferToResolveDispute($disputeId, 'Partial refund offer', 25.00, 'REFUND');
```

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

### addSetupFee

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Enables a setup fee and builds payment preferences with a setup fee, auto_bill_outstanding true, and setup_fee_failure_action CONTINUE.

```APIDOC
## addSetupFee

### Description
Enables a setup fee and builds payment preferences with a setup fee, auto_bill_outstanding true, and setup_fee_failure_action CONTINUE.

### Method
PHP method

### Signature
```php
public function addSetupFee(float $price): PayPal
```

### Parameters
- **price** (float) - Required - Setup fee amount

### Return Value
Returns the PayPal provider instance for chaining.
```

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

### Provide dispute evidence example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/disputes.md

Example call to provideDisputeEvidence() with two file paths and one evidence entry. The evidence array is sent as a JSON part named 'input' containing {"evidences": [...]}.

```php
$response = $provider->provideDisputeEvidence($disputeId, [
    '/storage/evidence/invoice.pdf',
    '/storage/evidence/tracking.png',
], [
    ['evidence_type' => 'PROOF_OF_FULFILLMENT', 'notes' => 'Tracking number 1Z…'],
]);
```

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

### Catching RuntimeException from PayPal setup

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/errors.md

Wrap setup calls like addProduct() and addMonthlyPlan() in a try/catch block to handle RuntimeException conditions such as missing product, PayPal validation failure, or unexpected response format.

```php
try {
    $provider->addProduct('SaaS', '', 'SERVICE', 'SOFTWARE');
    $provider->addMonthlyPlan('Pro', 'Pro plan', 29.00);
} catch (\RuntimeException $e) {
    // missing product, PayPal validation failure, unexpected response format
}
```

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

### Status transition usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Example calls to activate, suspend, and reactivate a subscription. The reactivate call uses the default reason.

```php
$provider->activateSubscription($subId, 'Customer confirmed by phone');
$provider->suspendSubscription($subId, 'Failed payment');
$provider->reactivateSubscription($subId); // default reason
```

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

### Full subscription setup with error handling

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Complete workflow: adds a product, monthly plan, and setup fee, then creates a subscription. Handles PayPal-level errors (silent mode) and local validation failures like missing plan/product.

```php
try {
    $provider->addProduct('SaaS Pro', '', 'SERVICE', 'SOFTWARE');
    $provider->addMonthlyPlan('Pro', 'Pro tier', 29.00);
    $provider->addSetupFee(10.00);

    $subscription = $provider->setupSubscription('Jane Doe', 'jane@example.com');

    if (isset($subscription['error'])) {
        // PayPal-level error (silent mode)
    }
} catch (\RuntimeException $e) {
    // local validation failure, e.g. missing plan/product
}
```

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

### showPaymentSetupTokenDetails() method signature

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/payment-method-tokens.md

Method signature for retrieving setup token details via GET /v3/vault/setup-tokens/{token}.

```php
public function showPaymentSetupTokenDetails(string $token)  // GET /v3/vault/setup-tokens/{token}
```

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

### GET /v3/vault/setup-tokens/{token}

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/endpoints.md

Retrieves details of a payment setup token. This endpoint is used to show the setup token details for a specific token ID.

```APIDOC
## GET /v3/vault/setup-tokens/{token}

### Description
Retrieves details of a payment setup token.

### Method
GET

### Endpoint
/v3/vault/setup-tokens/{token}

### Parameters
#### Path Parameters
- **token** (string) - Required - The setup token ID.

### Response
#### Success Response (200)
- **Setup token detail** - The setup token details.

```

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

### Use Existing Product & Billing Plan: addProductById and addBillingPlanById

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Sets up a subscription using an existing product ID and billing plan ID, with return/cancel URLs.

```php
$response = $provider->addProductById('PROD-XYAB12ABSB7868434')
    ->addBillingPlanById('P-5ML4271244454362WXNWU5NQ')
    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
    ->setupSubscription('John Doe', 'john@example.com', '2025-01-01');
```

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

### Set setup fee with failure action

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/billing-plan-builder.md

Adds a setup fee charged at subscription start. `$failureAction` accepts `CONTINUE` or `CANCEL`; `CANCEL_SUBSCRIPTION` is deprecated alias for `CANCEL`. Invalid values throw `\InvalidArgumentException`.

```php
public function withSetupFee(float $amount, string $failureAction = 'CONTINUE'): static
```

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

### showPaymentSourceTokenDetails() method signature

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/payment-method-tokens.md

Shows details for a specific payment token via GET /v3/vault/payment-tokens/{token}.

```php
public function showPaymentSourceTokenDetails(string $token)  // GET /v3/vault/payment-tokens/{token}
```

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

### Delete payment token example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/payment-method-tokens.md

Deletes a payment token and returns an empty string on success (HTTP 204).

```php
$provider->deletePaymentSourceToken($tokenId); // 204 → ''
```

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

### Set up subscription with Subscriptions v2

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Use this snippet to create a subscription using existing product and billing plan IDs. Redirect the buyer to the approval link in the response. Requires PHP 8.2+ and Laravel 12/13.

```php
// New subscriptions flow
$response = $provider->addProductById('PROD-XYAB12ABSB7868434')
    ->addBillingPlanById('P-5ML4271244454362WXNWU5NQ')
    ->setReturnAndCancelUrl('https://example.com/success', 'https://example.com/cancel')
    ->setupSubscription('John Doe', 'john@example.com');

// Redirect the buyer to: $response['links'][href where rel === 'approve']
```

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

### Initialization

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Initialize the PayPal client using the service class or facade.

```APIDOC
## Initialization

### Description
Initialize the PayPal client to start making API calls.

### Method
Constructor / Facade

### Usage
```php
use Srmklive\PayPal\Services\PayPal as PayPalClient;

$provider = new PayPalClient;

// Or via facade
$provider = \PayPal::setProvider();
```
```

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

### Daily Subscription: addDailyPlan with trial pricing

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Creates a daily subscription with a 7-day trial and return/cancel URLs. addPlanTrialPricing() and setReturnAndCancelUrl() are optional; return/cancel URLs require real domains, not localhost.

```php
$response = $provider->addProduct('Demo Product', 'Demo Product', 'SERVICE', 'SOFTWARE')
    ->addPlanTrialPricing('DAY', 7)
    ->addDailyPlan('Demo Plan', 'Demo Plan', 1.50)
    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
    ->setupSubscription('John Doe', 'john@example.com', '2025-01-01');
```

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

### listPaymentSourceTokens() method signature

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/payment-method-tokens.md

Lists payment source tokens via GET /v3/vault/payment-tokens. Requires a customer ID set via setCustomerId() before calling; otherwise throws RuntimeException.

```php
public function listPaymentSourceTokens(int $page = 1, int $page_size = 5, bool $totals = true)  // GET /v3/vault/payment-tokens?customer_id&page&page_size&total_required
```

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

### Pay Upon Invoice: setPaymentSourcePayUponInvoice and createOrderWithPaymentSource

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Sets up a Pay Upon Invoice payment source with buyer details and experience context, then creates and captures an order. Requires a DE/AT merchant account and buyer name, email, date of birth, phone, and billing address.

```php
$provider->getAccessToken();

$provider->setPaymentSourcePayUponInvoice([
    'name'       => ['given_name' => 'John', 'surname' => 'Doe'],
    'email'      => 'john.doe@example.com',
    'birth_date' => '1990-01-01',
    'phone'      => ['country_code' => '49', 'national_number' => '1234567890'],
    'billing_address' => [
        'address_line_1' => 'Hauptstraße 1',
        'admin_area_2'   => 'Berlin',
        'postal_code'    => '10115',
        'country_code'   => 'DE',
    ],
    'experience_context' => [
        'locale'     => 'de-DE',
        'return_url' => 'https://example.com/paypal-success',
        'cancel_url' => 'https://example.com/paypal-cancel',
    ],
]);

$order = $provider->createOrderWithPaymentSource([
    'intent'         => 'CAPTURE',
    'purchase_units' => [
        ['amount' => ['currency_code' => 'EUR', 'value' => '99.00']],
    ],
]);

$capture = $provider->capturePaymentOrder($order['id']);
```

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

### Use vaulted token in checkout with error handling

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/payment-method-tokens.md

Example of using a vaulted token via setTokenSource() to create and capture an order, with try-catch for PayPalApiException. The catch block notes a possible PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED error.

```php
use Srmklive\PayPal\Exceptions\PayPalApiException;

$provider->setTokenSource($paymentTokenId, 'PAYMENT_METHOD_TOKEN');

try {
    $order = $provider->createOrderWithPaymentSource([
        'intent' => 'CAPTURE',
        'purchase_units' => [['amount' => ['currency_code' => 'USD', 'value' => '10.00']]],
    ]);
    $capture = $provider->capturePaymentOrder($order['id']);
} catch (PayPalApiException $e) {
    // e.g. PAYMENT_SOURCE_INFO_CANNOT_BE_VERIFIED
}
```

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

### Catalog Products: list, create, update, show

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Use the provider to list products with optional pagination and show details. Create a product with a unique reference ID, update it using JSON Patch operations, and retrieve product details by ID.

```php
$products = $provider->listProducts();
$products = $provider->listProducts(1, 30, true);

$product = $provider->createProduct($data, 'create-product-'.time());

$provider->updateProduct('72255d4849af8ed6e0df1173', [
    ['op' => 'replace', 'path' => '/description', 'value' => 'Updated description'],
]);

$product = $provider->showProductDetails('72255d4849af8ed6e0df1173');
```

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

### Vault a card and send payment method request

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/payment-method-tokens.md

Example of setting a card payment source with vaulting and a customer ID, then sending the payment method request to create a payment method token. The returned token ID is extracted from the response.

```php
$provider
    ->setPaymentSourceCard([
        'number' => '4111111111111111',
        'expiry' => '2027-01',
        'name' => 'Test User',
    ])
    ->setCardVaulting('ON_SUCCESS')
    ->setCustomerId('customer-123');

$token = $provider->sendPaymentMethodRequest();
$paymentTokenId = $token['id'] ?? null;
```

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

### createMerchantApplication and setAccountProperties usage

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/identity.md

Creates a merchant application and sets account properties. The example shows required parameters for createMerchantApplication and a call to setAccountProperties.

```php
$app = $provider->createMerchantApplication(
    'My Partner App',
    ['https://example.com/callback'],
    [['email' => 'owner@example.com', 'phone' => ['country_code' => '1', 'national_number' => '4085555555']]],
    'merchant-payer-id',
    'APP-80W284485P519543T'
);

$provider->setAccountProperties(['PAYMENTS'], 'BRAINTREE_MERCHANT');
```

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

### Dispute Actions: Accept, Offer, Escalate, Update, Evidence, Appeal, Supporting Info

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Perform various dispute actions: accept claim, accept offer resolution, acknowledge item returned, make offers, escalate, update status, provide evidence, appeal, and provide supporting info. Evidence files must be jpg, png, or pdf. The amount is ignored for REPLACEMENT_WITHOUT_REFUND. Appeal requires an 'appeal' link on the dispute. Supporting info is for CHARGEBACK, PRE_ARBITRATION, or ARBITRATION.

```php
$provider->acceptDisputeClaim('PP-D-27803', 'Wrong item shipped');
$provider->acceptDisputeOfferResolution('PP-D-27803', 'Accepting discount offer');
$provider->acknowledgeItemReturned('PP-D-27803', 'Items received', 'ITEM_RECEIVED');

$provider->makeOfferToResolveDispute('PP-D-27803', 'Offering refund', 10.00, 'REFUND');
$provider->makeOfferToResolveDispute('PP-D-27803', 'Please return the item', 10.00, 'REFUND_WITH_RETURN', [
    'return_shipping_address' => ['address_line_1' => '1 Main St', 'admin_area_2' => 'San Jose', 'postal_code' => '95131', 'country_code' => 'US'],
]);
$provider->makeOfferToResolveDispute('PP-D-27803', 'Sending a replacement', 0, 'REPLACEMENT_WITHOUT_REFUND'); // amount ignored
$provider->escalateDisputeToClaim('PP-D-27803', 'Escalating unresolved dispute');
$provider->updateDisputeStatus('PP-D-27803', $data);

// Provide evidence (jpg, png, pdf only)
$provider->provideDisputeEvidence('PP-D-27803', [
    '/path/to/invoice.pdf',
    '/path/to/screenshot.jpg',
]);

// Optionally describe the evidence (sent as a JSON "input" part)
$provider->provideDisputeEvidence('PP-D-27803', ['/path/to/proof-of-delivery.pdf'], [
    [
        'evidence_type' => 'PROOF_OF_FULFILLMENT',
        'evidence_info' => ['tracking_info' => [['carrier_name' => 'UPS', 'tracking_number' => '1Z999AA10123456784']]],
        'notes'         => 'Delivered on 2026-09-30.',
    ],
]);

// Appeal a decision with new evidence (requires an "appeal" link on the dispute)
$provider->appealDispute('PP-D-27803', ['/path/to/refund-receipt.pdf'], [
    ['evidence_type' => 'PROOF_OF_REFUND', 'evidence_info' => ['refund_ids' => ['1CX12345AB678901C']]],
]);

// Supporting information during CHARGEBACK, PRE_ARBITRATION or ARBITRATION
$provider->provideDisputeSupportingInfo('PP-D-27803', 'The item was delivered on time.', ['/path/to/tracking.pdf']);
```

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

### Partner Referrals: Create referral, show referral data, list seller tracking/status, and merchant credentials

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Shows how to create a partner referral and retrieve referral data using the returned token. Also lists seller tracking info, seller status, and merchant credentials.

```php
$provider->createPartnerReferral($data);
$provider->showReferralData('ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=');

$provider->listSellerTrackingInfo('tracking-id');
$provider->listSellerStatus('partner-id', 'merchant-id');
$provider->listMerchantCredentials();
```

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

### createPlan() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/billing-plans.md

Creates a new billing plan with a monthly frequency, regular tenure, 12 total cycles, and a fixed price of $9.99 USD. The payment preferences set auto-billing for outstanding amounts, continue on setup fee failure, and allow up to 3 payment failures.

```php
$plan = $provider->createPlan([
    'product_id' => 'PROD-XXCD1234QWER65782',
    'name' => 'Premium Plan',
    'billing_cycles' => [[
        'frequency' => ['interval_unit' => 'MONTH', 'interval_count' => 1],
        'tenure_type' => 'REGULAR',
        'sequence' => 1,
        'total_cycles' => 12,
        'pricing_scheme' => ['fixed_price' => ['value' => '9.99', 'currency_code' => 'USD']],
    ]],
    'payment_preferences' => [
        'auto_bill_outstanding' => true,
        'setup_fee_failure_action' => 'CONTINUE',
        'payment_failure_threshold' => 3,
    ],
]);
```

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

### Combined example with error handling

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/orders.md

Shows how to enable exceptions, create an order, capture payment, and extract the capture ID, catching PayPalApiException.

```php
use Srmklive\PayPal\Exceptions\PayPalApiException;

$provider->withExceptions();

try {
    $order = $provider->createOrderWithPaymentSource([...]);
    $response = $provider->capturePaymentOrder($order['id']);
    $captureId = $provider->getCaptureIdFromOrder($response);
} catch (PayPalApiException $e) {
    $issue = $e->getPayPalError()['details'][0]['issue'] ?? 'UNKNOWN';
    // rethrow or report
}
```

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

### Create a billing plan with BillingPlanBuilder

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Builds a billing plan payload with a product ID, name, description, and monthly price, then creates it via the provider. Use for simple recurring plans without trials or setup fees.

```php
use Srmklive\PayPal\Builders\BillingPlanBuilder;

$response = BillingPlanBuilder::make()
    ->forProduct('PROD-XXCD1234QWER65782')
    ->named('Premium Plan', 'Monthly premium access')
    ->monthly(9.99)
    ->create($provider);
```

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

### getCaptureIdFromOrder() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/orders.md

Usage example that throws a RuntimeException if the order is not captured.

```php
$captureId = $provider->getCaptureIdFromOrder($captured) ?? throw new RuntimeException('Not captured');
```

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

### listDisputes() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/disputes.md

Example call to list disputes with dispute_state filter.

```php
$disputes = $provider->listDisputes(['dispute_state' => ['OPEN', 'WAITING_FOR_BUYER_RESPONSE']]);
```

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

### isSubscriptionActive() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Example usage to grant access when the subscription is active.

```php
if ($provider->isSubscriptionActive($subId)) {
    // grant access
}
```

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

### Weekly, Monthly, and Annual Subscription Helpers

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Shows three subscription variants: weekly, monthly, and annual. The weekly example includes a 7-day trial and return/cancel URLs; monthly and annual are shown as abbreviated chains with addMonthlyPlan and addAnnualPlan.

```php
// Weekly
$response = $provider->addProduct('Demo Product', 'Demo Product', 'SERVICE', 'SOFTWARE')
    ->addPlanTrialPricing('DAY', 7)
    ->addWeeklyPlan('Demo Plan', 'Demo Plan', 30)
    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
    ->setupSubscription('John Doe', 'john@example.com', '2025-01-01');

// Monthly
$response = $provider->addProduct(...)->addMonthlyPlan('Demo Plan', 'Demo Plan', 100)->...->setupSubscription(...);

// Annual
$response = $provider->addProduct(...)->addAnnualPlan('Demo Plan', 'Demo Plan', 600)->...->setupSubscription(...);
```

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

### updateTrackingDetails() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/trackers.md

Example of updating tracking details to DELIVERED status.

```php
$provider->updateTrackingDetails($trackingId, [
    'tracking_number' => '1Z999AA10123456784',
    'status' => 'DELIVERED',
    'carrier' => 'UPS',
]);
```

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

### createPartnerReferral()

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/identity.md

Creates a partner referral for onboarding a seller. Returns the referral object with an approval URL.

```APIDOC
## POST /v2/customer/partner-referrals

### Description
Creates a partner referral for onboarding a seller. Returns the referral object with an approval URL.

### Method
POST

### Endpoint
/v2/customer/partner-referrals

### Parameters
#### Request Body
- `$partner_data` (array<string, mixed>) - Required - Contains `operations[]` (with `apiCall` / `api` and `payer` data), `products[]`, `legal_consents[]`, `partner_config_override`…

### Request Example
```php
$referral = $provider->createPartnerReferral([
    'operations' => [[
        'operation' => 'API_INTEGRATION',
        'api_integration_preference' => [
            'rest_api_integration' => [
                'integration_method' => 'PAYPAL',
                'integration_type' => 'THIRD_PARTY',
                'third_party_details' => ['features' => ['PAYMENT', 'REFUND']],
            ],
        ],
    ]],
    'products' => ['EXPRESS_CHECKOUT'],
    'legal_consents' => [['type' => 'SHARE_DATA_CONSENT', 'granted' => true]],
]);
$referralId = $referral['links'][0]['href'] ?? null;  // extract approval URL for the seller
```

### Response
#### Success Response (200)
- `links` (array) - Contains approval URL for the seller.

#### Response Example
```json
{
  "links": [
    {
      "href": "https://www.paypal.com/..."
    }
  ]
}
```
```

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

### setupSubscription()

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Assembles and POSTs a PayPal subscription with the given customer details and optional start date. Returns the subscription response annotated with billing plan and product IDs, and resets accumulated state on success.

```APIDOC
## setupSubscription()

### Description
Assembles and POSTs a subscription to PayPal using the provided customer name, email, and optional start date. The subscription includes plan ID, quantity, subscriber details, and optional fields like start time, setup fee, shipping address, application context, taxes, and custom ID. On success, it annotates the response with billing plan and product IDs and resets all accumulated state.

### Method
POST (implied by "POSTs the subscription")

### Endpoint
Not explicitly provided in source

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- `$customer_name` (string) - Required - Used as `subscriber.name.given_name`.
- `$customer_email` (string) - Required - Used as `subscriber.email_address`.
- `$start_date` (string) - Optional - ISO date; omitted when empty.

### Request Example
```php
$subscription = $provider->setupSubscription('Jane Doe', 'jane@example.com');
```

### Response
#### Success Response (200)
- `id` (string) - Subscription ID
- `status` (string) - Subscription status
- `links` (array) - Contains approval link at `[0]['href']`
- `billing_plan_id` (string) - Annotated when known
- `product_id` (string) - Annotated when known

#### Response Example
```php
$subscription['id'], $subscription['status'], approve link: $subscription['links'][0]['href']
```

### Error Handling
- Throws `RuntimeException` when no billing plan is set.
- Returns an array with `error` key on PayPal-level error (silent mode).
```

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

### showPaymentSetupTokenDetails()

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/payment-method-tokens.md

Retrieves details of a specific payment setup token.

```APIDOC
## GET /v3/vault/setup-tokens/{token}

### Description
Retrieves details of a specific payment setup token.

### Method
GET

### Endpoint
/v3/vault/setup-tokens/{token}

### Parameters
#### Path Parameters
- `token` (string) - Required - The ID of the setup token to retrieve.

### Response
#### Success Response (200)
- Returns the setup token details.

#### Response Example
```json
{
  "id": "SETUP_TOKEN_ID",
  "status": "APPROVED",
  "payment_source": {
    "card": {
      "last_digits": "1111",
      "expiry": "2027-01"
    }
  }
}
```
```

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

### deletePaymentSetupToken()

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/payment-method-tokens.md

Deletes a payment setup token. Deprecated: PayPal's Vault v3 API has no endpoint to delete setup tokens, so this call returns an error. Scheduled for removal in the next major version.

```APIDOC
## DELETE /v3/vault/setup-tokens/{token}

### Description
Deletes a payment setup token. Deprecated: PayPal's Vault v3 API has no endpoint to delete setup tokens, so this call returns an error. Scheduled for removal in the next major version.

### Method
DELETE

### Endpoint
/v3/vault/setup-tokens/{token}

### Parameters
#### Path Parameters
- `token` (string) - Required - The ID of the setup token to delete.

### Response
#### Success Response (200)
- Returns a success message if deletion is successful.

#### Response Example
```json
{
  "status": "success"
}
```
```

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

### listSubscriptionTransactions() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Example call to list transactions for a subscription within a date range.

```php
$txns = $provider->listSubscriptionTransactions($subId, '2026-01-01', '2026-02-01');
```

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

### Additional Subscription Options: Setup Fee, Shipping Address, Payment Failure Threshold

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Shows three optional subscription helpers: addSetupFee, addShippingAddress, and addPaymentFailureThreshold. Each is chained with addProductById and setupSubscription; the ellipses (...) indicate omitted intermediate calls.

```php
// Setup fee
$provider->addSetupFee(9.99)->addProductById(...)->...->setupSubscription(...);

// Shipping address
$provider->addShippingAddress('John Doe', '123 Main St', 'Suite 1', 'Austin', 'TX', 78701, 'US')
    ->addProductById(...)->...->setupSubscription(...);

// Payment failure threshold
$provider->addPaymentFailureThreshold(5)->addProductById(...)->...->setupSubscription(...);
```

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

### showTrackingDetails() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/trackers.md

Example of retrieving tracking details and checking for errors before accessing status.

```php
$tracker = $provider->showTrackingDetails($trackingId);

if (! isset($tracker['error'])) {
    $status = $tracker['tracking_details'][0]['status'] ?? null;
}
```

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

### setupSubscription() method signature

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Defines the method signature for setting up a PayPal subscription. Parameters include customer name, email, and optional start date. Throws Throwable on errors.

```php
public function setupSubscription(string $customer_name, string $customer_email, string $start_date = '')  // @return array<string, mixed>|StreamInterface|string — @throws Throwable
```

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

### addTracking() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/trackers.md

Example of adding tracking for a transaction. Returns tracking ID from the response.

```php
$tracking = $provider->addTracking([
    'transaction_id' => '5O190127TN364715T',
    'tracking_number' => '1Z999AA10123456784',
    'status' => 'SHIPPED',
    'carrier' => 'UPS',
]);
$trackingId = $tracking['id'] ?? null;
```

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

### Initialize PayPal Provider

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Create a PayPal client instance using the Srmklive PayPal service. Can be instantiated directly or via the PayPal facade.

```php
use Srmklive\PayPal\Services\PayPal as PayPalClient;

$provider = new PayPalClient;

// Or via facade
$provider = \PayPal::setProvider();
```

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

### Send Invoice Example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/invoices.md

Example of sending an invoice with an additional recipient email address.

```php
$provider->sendInvoice($invoiceId, recipients: ['cc-accounting@example.com']);
```

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

### Product and plan setup method signatures

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/subscriptions.md

Lists the public methods for adding product, plan, setup fee, shipping address, taxes, and custom ID. addProduct() calls createProduct() and omits empty description; addProductById() and addBillingPlanById() register existing IDs without API calls. addSetupFee() enables has_setup_fee and builds payment_preferences with setup_fee; addTaxes() formats percentage via Amount::percentage() and stores as plan override taxes.

```php
public function addProduct(string $name, string $description, string $type, string $category): PayPal
public function addProductById(string $product_id): PayPal
public function addBillingPlanById(string $plan_id): PayPal
public function addPaymentFailureThreshold(int $threshold): PayPal   // default 3
public function addSetupFee(float $price): PayPal
public function addShippingAddress(string $full_name, string $address_line_1, string $address_line_2, string $admin_area_2, string $admin_area_1, string $postal_code, string $country_code): PayPal
public function addTaxes(float $percentage, bool $inclusive = false): PayPal
public function addCustomId(string $custom_id): PayPal
```

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

### showDisputeDetails() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/disputes.md

Example call to show dispute details and check for CHARGEBACK stage to access appeal link.

```php
$dispute = $provider->showDisputeDetails($disputeId);

if (! isset($dispute['error']) && ($dispute['dispute_life_cycle_stage'] ?? null) === 'CHARGEBACK') {
    // appeal link available
}
```

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

### createMerchantApplication()

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/identity.md

Creates a merchant application for a partner.

```APIDOC
## [POST] /v1/identity/applications

### Description
Creates a merchant application for a partner.

### Method
POST

### Endpoint
/v1/identity/applications

### Parameters
#### Request Body
- **client_name** (string) - Required - Application name.
- **redirect_uris** (list<string>) - Required - Redirect URIs.
- **contacts** (array<string, mixed>) - Required - Contact objects (email, phone…).
- **payer_id** (string) - Required - Merchant PayPal account payer ID.
- **migrated_app** (string) - Required - App ID of the app being migrated.
- **application_type** (string) - Optional - Default `'web'`. Sent in `application_type`.
- **logo_url** (string) - Optional - Default `''`. Logo URI; omitted when empty (`logo_uri`).

### Request Example
```php
$app = $provider->createMerchantApplication(
    'My Partner App',
    ['https://example.com/callback'],
    [['email' => 'owner@example.com', 'phone' => ['country_code' => '1', 'national_number' => '4085555555']]],
    'merchant-payer-id',
    'APP-80W284485P519543T'
);
```

### Response
#### Success Response (200)
- **id** (string) - Application ID.

#### Response Example
```json
{
  "id": "APP-12345"
}
```
```

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

### Custom Interval Subscription: addCustomPlan

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Creates a subscription with a custom billing interval (every 3 months) using addCustomPlan, plus return/cancel URLs.

```php
$response = $provider->addProduct('Demo Product', 'Demo Product', 'SERVICE', 'SOFTWARE')
    ->addCustomPlan('Demo Plan', 'Demo Plan', 150, 'MONTH', 3)
    ->setReturnAndCancelUrl('https://example.com/paypal-success', 'https://example.com/paypal-cancel')
    ->setupSubscription('John Doe', 'john@example.com', '2025-01-01');
```

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

### setupOrderConfirmation() usage example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/orders.md

Sets payment source (e.g., PayPal) and then calls setupOrderConfirmation(). The payment_source is sent as {} when nothing is set, causing PayPal's normal validation error.

```php
$provider->setPaymentSourcePayPal(['experience_context' => ['...']]); // or card/venmo/apple pay…
$response = $provider->setupOrderConfirmation($orderId);
```

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

### Register and Delete Payment Example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/invoices.md

Example of registering a bank payment and then deleting it using the transaction ID.

```php
$provider->registerPaymentInvoice($invoiceId, '2026-01-15', 'BANK', 150.00, payment_id: 'bank-txn-1');
$provider->deleteExternalPaymentInvoice($invoiceId, 'bank-txn-1');
```

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

### Settle Dispute and Send Message Example

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/api-reference/disputes.md

Example calls to settle a dispute in favor of the seller and send a message requesting tracking information.

```php
$provider->settleDispute($disputeId, merchant: true);   // SELLER_FAVOR
$provider->sendDisputeMessage($disputeId, 'Please provide the tracking number.');
```

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

### Create and manage billing agreements (Reference Transactions)

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Use these methods to create an agreement token, retrieve token details, create a billing agreement from a token, and show, update, or cancel an agreement. Requires access to PayPal's limited-release Reference Transactions API.

```php
// Create an agreement token (first step)
$provider->createBillingAgreementToken($data);

// Get details of an existing agreement token
$provider->getBillingAgreementTokenDetails('token-id');

// Create a billing agreement from a token
$provider->createBillingAgreement('token-id');

// Show / Update / Cancel a billing agreement
$provider->showBillingAgreementDetails('agreement-id');
$provider->updateBillingAgreement('agreement-id', $patchData);
$provider->cancelBillingAgreement('agreement-id');
```

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

### Payment Experience: Manage web experience profiles

Source: https://github.com/blendbyte/laravel-paypal/blob/main/README.md

Demonstrates CRUD operations on web experience profiles, including create, show, update, patch, and delete using a profile ID.

```php
$provider->listWebExperienceProfiles();
$provider->createWebExperienceProfile($data);
$provider->showWebExperienceProfileDetails('XP-A88A-LYLW-8Y3X-E5ER');
$provider->updateWebExperienceProfile('XP-A88A-LYLW-8Y3X-E5ER', $data);
$provider->patchWebExperienceProfile('XP-A88A-LYLW-8Y3X-E5ER', $patchData);
$provider->deleteWebExperienceProfile('XP-A88A-LYLW-8Y3X-E5ER');
```

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

### POST /v3/vault/setup-tokens

Source: https://github.com/blendbyte/laravel-paypal/blob/main/_autodocs/endpoints.md

Creates a payment setup token. This endpoint allows you to create a setup token and returns an approval link.

```APIDOC
## POST /v3/vault/setup-tokens

### Description
Creates a payment setup token.

### Method
POST

### Endpoint
/v3/vault/setup-tokens

### Request Body
- **payment_source** (object) - Required - The payment source.

### Request Example
{
  "payment_source": {}
}

### Response
#### Success Response (200)
- **Setup token** - The setup token.
- **Approval link** - The approval link.

```