$provider->createPlan($payload);
```
**Available cycle methods:**
| Method | Interval | Tenure |
|---|---|---|
| `daily(price, totalCycles)` | DAY / 1 | REGULAR |
| `weekly(price, totalCycles)` | WEEK / 1 | REGULAR |
| `monthly(price, totalCycles)` | MONTH / 1 | REGULAR |
| `annual(price, totalCycles)` | YEAR / 1 | REGULAR |
| `trialDaily(price, totalCycles)` | DAY / 1 | TRIAL |
| `trialWeekly(price, totalCycles)` | WEEK / 1 | TRIAL |
| `trialMonthly(price, totalCycles)` | MONTH / 1 | TRIAL |
| `trialAnnual(price, totalCycles)` | YEAR / 1 | TRIAL |
| `regularCycle(unit, count, price, totalCycles)` | custom | REGULAR |
| `trialCycle(unit, count, price, totalCycles)` | custom | TRIAL |
`totalCycles: 0` means the cycle repeats indefinitely.
### Raw API
```php
// List (page, count, show_total, fields)
$plans = $provider->listPlans();
$plans = $provider->listPlans(1, 30, true, ['id', 'name', 'description']);
// Create
$plan = $provider->createPlan($data);
// Update
$provider->updatePlan('P-7GL4271244454362WXNWU5NQ', [
['op' => 'replace', 'path' => '/payment_preferences/payment_failure_threshold', 'value' => 7],
]);
// Show / Activate / Deactivate
$plan = $provider->showPlanDetails('P-7GL4271244454362WXNWU5NQ');
$provider->activatePlan('P-7GL4271244454362WXNWU5NQ');
$provider->deactivatePlan('P-7GL4271244454362WXNWU5NQ');
// Update pricing
$provider->updatePlanPricing('P-7GL4271244454362WXNWU5NQ', $pricingData);
```
---
## Catalog Products
```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');
```
---
## Orders
```php
// Create
$order = $provider->createOrder([
'intent' => 'CAPTURE',
'purchase_units' => [
['amount' => ['currency_code' => 'USD', 'value' => '100.00']],
],
]);
// Update, show, authorize
$provider->updateOrder('5O190127TN364715T', $patchData);
$order = $provider->showOrderDetails('5O190127TN364715T');
$provider->authorizePaymentOrder('5O190127TN364715T');
// Capture — and extract the capture/transaction ID from the response
$capture = $provider->capturePaymentOrder($order['id']);
$captureId = $provider->getCaptureIdFromOrder($capture);
// $captureId is the value you store in your database and use for refunds,
// dispute lookups, and shipment tracking (see Trackers section).
```
---
## Payments
### Authorizations
```php
$provider->showAuthorizedPaymentDetails('0VF52814937998046');
$provider->captureAuthorizedPayment('0VF52814937998046', 'INVOICE-123', 10.99, 'Payment note');
$provider->reAuthorizeAuthorizedPayment('0VF52814937998046', 10.99);
$provider->voidAuthorizedPayment('0VF52814937998046');
```
### Captures & Refunds
```php
$provider->showCapturedPaymentDetails('2GG279541U471931P');
$provider->refundCapturedPayment('2GG279541U471931P', 'INVOICE-123', 10.99, 'Defective product');
$provider->showRefundDetails('1JU08902781691411');
```
---
## Payouts
```php
$provider->createBatchPayout($data);
$provider->showBatchPayoutDetails('FYXMPQTX4JC9N');
$provider->showPayoutItemDetails('8AELMXH8UB2P8');
$provider->cancelUnclaimedPayoutItem('8AELMXH8UB2P8');
```
---
## Referenced Payouts
```php
// Create batch
$provider->createReferencedBatchPayout([
'referenced_payouts' => [
['reference_id' => '2KP03934U4415543C', 'reference_type' => 'TRANSACTION_ID'],
],
], 'some-request-id', 'some-attribution-id');
$provider->listItemsReferencedInBatchPayout('KHbwO28lWlXwi2IlToJ2IYNG4juFv6kpbFx4J9oQ5Hb24RSp96Dk5FudVHd6v4E=');
$provider->createReferencedBatchPayoutItem(
['reference_id' => 'CAPTURETXNID', 'reference_type' => 'TRANSACTION_ID'],
'some-request-id', 'some-attribution-id'
);
$provider->showReferencedPayoutItemDetails('CDZEC5MJ8R5HY', 'some-attribution-id');
```
---
## Reference Transactions (Billing Agreements)
> **Note:** This is a [limited-release PayPal API](https://developer.paypal.com/limited-release/reference-transactions/). You must request access from PayPal before using it.
```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');
```
---
## Invoices
```php
$invoiceNo = $provider->generateInvoiceNumber();
$invoices = $provider->listInvoices();
$invoices = $provider->listInvoices(2, 50);
$invoice = $provider->createInvoice($data);
$provider->deleteInvoice('INV2-Z56S-5LLA-Q52L-CPZ5');
$provider->updateInvoice('INV2-Z56S-5LLA-Q52L-CPZ5', $data);
$invoice = $provider->showInvoiceDetails('INV2-Z56S-5LLA-Q52L-CPZ5');
$provider->cancelInvoice('INV2-Z56S-5LLA-Q52L-CPZ5', $data);
$provider->generateQRCodeInvoice('INV2-Z56S-5LLA-Q52L-CPZ5');
$provider->generateQRCodeInvoice('INV2-Z56S-5LLA-Q52L-CPZ5', 50, 50); // custom dimensions
$provider->sendInvoice('INV2-Z56S-5LLA-Q52L-CPZ5', 'Subject', 'Note');
$provider->sendInvoice('INV2-Z56S-5LLA-Q52L-CPZ5', 'Subject', 'Note', true, true, ['cc@example.com']);
$provider->sendInvoiceReminder('INV2-Z56S-5LLA-Q52L-CPZ5', 'Subject', 'Note');
$provider->sendInvoiceReminder('INV2-Z56S-5LLA-Q52L-CPZ5', 'Subject', 'Note', true, true, ['cc@example.com']);
$provider->registerPaymentInvoice('INV2-Z56S-5LLA-Q52L-CPZ5', '2024-05-21', 'BANK_TRANSFER', 10.00);
$provider->deleteExternalPaymentInvoice('INV2-Z56S-5LLA-Q52L-CPZ5', 'EXTR-86F38350LX4353815');
$provider->refundInvoice('INV2-Z56S-5LLA-Q52L-CPZ5', '2024-05-26', 'BANK_TRANSFER', 5.00);
$provider->deleteRefundInvoice('INV2-Z56S-5LLA-Q52L-CPZ5', 'EXTR-2LG703375E477444T');
```
---
## Invoice Search
```php
$invoices = $provider->searchInvoices();
$invoices = $provider->searchInvoices(1, 50, false);
```
Available filters (chainable, call `searchInvoices()` at the end):
```php
$invoices = $provider
->addInvoiceFilterByRecipientEmail('bill-me@example.com')
->addInvoiceFilterByRecipientFirstName('John')
->addInvoiceFilterByRecipientLastName('Doe')
->addInvoiceFilterByRecipientBusinessName('Acme Inc.')
->addInvoiceFilterByInvoiceNumber('#123')
->addInvoiceFilterByInvoiceStatus(['PAID', 'MARKED_AS_PAID'])
->addInvoiceFilterByReferenceorMemo('deal-ref')
->addInvoiceFilterByCurrencyCode('USD')
->addInvoiceFilterByAmountRange(30, 50) // uses configured currency
->addInvoiceFilterByAmountRange(30, 50, 'EUR') // explicit currency
->addInvoiceFilterByDateRange('2024-01-01', '2024-06-30', 'invoice_date') // invoice_date|due_date|payment_date|creation_date
->addInvoiceFilterByArchivedStatus(false)
->addInvoiceFilterByFields(['items', 'payments', 'refunds'])
->searchInvoices();
```
---
## Invoice Templates
```php
$provider->listInvoiceTemplates();
$provider->listInvoiceTemplates(1, 50);
$provider->createInvoiceTemplate($data);
$provider->deleteInvoiceTemplate('TEMP-19V05281TU309413B');
$provider->updateInvoiceTemplate('TEMP-19V05281TU309413B', $data);
$provider->showInvoiceTemplateDetails('TEMP-19V05281TU309413B');
```
---
## Subscriptions
Full CRUD for PayPal Subscriptions (distinct from the subscription helper methods above):
```php
$provider->createSubscription($data);
$provider->updateSubscription('I-BW452GLLEP1G', [
['op' => 'replace', 'path' => '/billing_info/outstanding_balance', 'value' => ['currency_code' => 'USD', 'value' => '50.00']],
]);
$provider->showSubscriptionDetails('I-BW452GLLEP1G');
$provider->activateSubscription('I-BW452GLLEP1G', 'Reactivating the subscription');
$provider->cancelSubscription('I-BW452GLLEP1G', 'Not satisfied with the service');
$provider->suspendSubscription('I-BW452GLLEP1G', 'Item out of stock');
$provider->captureSubscriptionPayment('I-BW452GLLEP1G', 'Balance reached limit', 100);
$provider->reviseSubscription('I-BW452GLLEP1G', $data);
$provider->listSubscriptionTransactions('I-BW452GLLEP1G', '2024-01-01T00:00:00Z', '2024-12-31T23:59:59Z');
// Lifecycle helpers
$provider->reactivateSubscription('I-BW452GLLEP1G'); // default reason
$provider->reactivateSubscription('I-BW452GLLEP1G', 'Customer requested'); // custom reason
$isActive = $provider->isSubscriptionActive('I-BW452GLLEP1G'); // bool
```
---
## Disputes
```php
$provider->listDisputes();
$provider->updateDispute('PP-D-27803', $patchData);
$provider->showDisputeDetails('PP-D-27803');
```
---
## Dispute Actions
```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->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',
]);
```
---
## Trackers
The `transaction-id` used here is the capture ID — get it via `getCaptureIdFromOrder()` after calling `capturePaymentOrder()` (see [Orders](#orders)).
```php
$provider->addBatchTracking($data);
$provider->addTracking($data);
$provider->listTrackingDetails($captureId);
$provider->listTrackingDetails($captureId, 'tracking-number');
$provider->updateTrackingDetails('tracking-id', $data);
$provider->showTrackingDetails('tracking-id');
```
---
## Webhooks
```php
// Create
$provider->createWebHook('https://example.com/paypal/webhook', ['PAYMENT.CAPTURE.COMPLETED']);
// List / Show / Update / Delete
$provider->listWebHooks();
$provider->showWebHookDetails('webhook-id');
$provider->updateWebHook('webhook-id', $patchData);
$provider->deleteWebHook('webhook-id');
// Events
$provider->listWebHookEvents('webhook-id');
$provider->listEventTypes();
$provider->listEvents();
$provider->showEventDetails('event-id');
$provider->resendEventNotification('event-id', ['webhook-id']);
// Verify incoming webhook signature (API roundtrip)
$provider->verifyWebHook([
'auth_algo' => $request->header('PAYPAL-AUTH-ALGO'),
'cert_url' => $request->header('PAYPAL-CERT-URL'),
'transmission_id' => $request->header('PAYPAL-TRANSMISSION-ID'),
'transmission_sig' => $request->header('PAYPAL-TRANSMISSION-SIG'),
'transmission_time' => $request->header('PAYPAL-TRANSMISSION-TIME'),
'webhook_id' => 'your-webhook-id',
'webhook_event' => $request->all(),
]);
// Verify locally (offline — no API roundtrip, faster for high-volume webhooks)
// Pass all request headers, your webhook ID, and the RAW (unmodified) request body.
$valid = $provider->verifyWebHookLocally(
$request->headers->all(),
'your-webhook-id',
$request->getContent(), // must be the raw body bytes, not re-encoded JSON
);
```
> **Local verification** skips the PayPal verify API entirely. The signing certificate is fetched
> over HTTPS from the `PAYPAL-CERT-URL` on the first call, then cached in memory for the lifetime
> of the process — subsequent calls are pure in-memory RSA-SHA256 with no network I/O. Short-lived
> processes (serverless, etc.) will still fetch the cert on each cold start. The cert URL is
> validated against PayPal's known API domains before any request is made (SSRF guard).
### Handling webhook events
After verification, parse the raw body into a typed `WebhookEvent` and route by event type:
```php
use Srmklive\PayPal\Events\WebhookEvent;
$rawBody = $request->getContent();
if (! $provider->verifyWebHookLocally($request->headers->all(), 'your-webhook-id', $rawBody)) {
return response()->json(['error' => 'Invalid signature'], 401);
}
$event = WebhookEvent::fromRawBody($rawBody);
if ($event->is('PAYMENT.CAPTURE.COMPLETED')) {
// $event->resource contains the capture object
$this->handleCapture($event->resource);
}
if ($event->is('BILLING.SUBSCRIPTION.CANCELLED')) {
$this->handleCancellation($event->resource);
}
// Available properties:
// $event->id — webhook notification ID
// $event->eventType — e.g. 'PAYMENT.CAPTURE.COMPLETED'
// $event->resourceType — e.g. 'capture'
// $event->summary — human-readable summary
// $event->createTime — ISO 8601 timestamp
// $event->resource — event-specific resource array
// $event->rawPayload — full decoded payload array
```
You can also build from an already-decoded array:
```php
$event = WebhookEvent::fromArray($request->json()->all());
```
---
## Payment Method Tokens
```php
// Payment tokens (permanent)
$provider->createPaymentSourceToken($data);
$provider->setCustomerId('customer_4029352050'); // required before listPaymentSourceTokens()
$provider->listPaymentSourceTokens(1, 10, true);
$provider->showPaymentSourceTokenDetails('token-id');
$provider->deletePaymentSourceToken('token-id');
// Setup tokens (single-use, used to create a payment token)
$provider->createPaymentSetupToken($data);
$provider->showPaymentSetupTokenDetails('token-id');
$provider->deletePaymentSetupToken('token-id');
```
Using the fluent helpers to create a token:
```php
$response = $provider->setTokenSource('5C991763VB2781612', 'SETUP_TOKEN')
->setCustomerId('customer_4029352050')
->sendPaymentMethodRequest();
// or ->sendPaymentMethodRequest(true) to create a setup token instead
```
---
## Reporting
```php
use Carbon\Carbon;
// Raw filter array (full control)
$provider->listTransactions([
'start_date' => Carbon::now()->subDays(30)->toIso8601String(),
'end_date' => Carbon::now()->toIso8601String(),
]);
// Convenience helpers
$provider->getTransactionDetails('5TY05013RG002845M'); // searches last 31 days
$provider->getTransactionDetails('5TY05013RG002845M', 7); // searches last 7 days
$provider->listTransactionsForDateRange('2024-07-01', '2024-07-31');
$provider->listTransactionsByType('T0006', '2024-07-01', '2024-07-31'); // e.g. express checkout sales
$provider->listTransactionsByStatus('S', '2024-07-01', '2024-07-31'); // 'S'=success, 'V'=reversed, 'P'=pending
$provider->listBalances('2024-01-01');
$provider->listBalances('2024-01-01', 'EUR');
```
---
## Identity
```php
$provider->showProfileInfo();
$provider->createMerchantApplication(
'AGGREGATOR',
['https://example.com/callback'],
['merchant@example.com'],
'WDJJHEBZ4X2LY',
'some-open-id'
);
$provider->setAccountProperties($data);
$provider->disableAccountProperties();
$provider->listUsers(1, 10);
$provider->showUserDetails('user-id');
$provider->deleteUser('user-id');
// Client token — used with PayPal Fastlane and Advanced Card Payments
$provider->generateClientToken(); // preferred alias
$provider->getClientToken(); // equivalent
```
---
## Partner Referrals
```php
$provider->createPartnerReferral($data);
$provider->showReferralData('ZjcyODU4ZWYtYTA1OC00ODIwLTk2M2EtOTZkZWQ4NmQwYzI3RU12cE5xa0xMRmk1NWxFSVJIT1JlTFdSbElCbFU1Q3lhdGhESzVQcU9iRT0=');
$provider->listSellerTrackingInfo('tracking-id');
$provider->listSellerStatus('partner-id', 'merchant-id');
$provider->listMerchantCredentials();
```
---
## Payment Experience
```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');
```
---
## Testing
Use `MockPayPalClient` to write unit tests against your PayPal integration without hitting the sandbox API:
```php
use Srmklive\PayPal\Testing\MockPayPalClient;
$mock = new MockPayPalClient();
$mock->addResponse(['id' => '5O190127TN364715T', 'status' => 'CREATED']);
// mockProvider() returns a ready PayPal instance — credentials and access token pre-set
$provider = $mock->mockProvider();
$order = $provider->createOrder($data);
expect($order['id'])->toBe('5O190127TN364715T');
```
Queue multiple responses in order — one is consumed per API call:
```php
$mock = new MockPayPalClient();
$mock->addResponse(['id' => 'ORDER-1', 'status' => 'CREATED']);
$mock->addResponse(['id' => 'ORDER-2', 'status' => 'CREATED']);
```
Pass `false` as the body for empty-response operations (e.g. `updateOrder`, which returns 204):
```php
$mock->addResponse(false, 204);
```
Inspect what was sent to assert on headers, method, or payload:
```php
$request = $mock->lastRequest(); // Psr\Http\Message\RequestInterface
$mock->requests(); // all captured requests, in order
$mock->requestCount(); // int
$request->getHeaderLine('Authorization'); // 'Bearer mock-access-token'
$request->getMethod(); // 'POST'
(string) $request->getUri(); // 'https://api-m.sandbox.paypal.com/v2/checkout/orders'
```
If you need to inject the mock into a provider you've already constructed, pass it to `setClient()` directly — `MockPayPalClient` implements `Psr\Http\Client\ClientInterface`:
```php
$provider->setAccessToken(['access_token' => 'mock-token', 'token_type' => 'Bearer']);
$provider->setClient($mock);
```
## Maintained by Blendbyte
Blendbyte builds cloud infrastructure, web apps, and developer tools.
We've been shipping software to production for 20+ years.
This package runs in our own stack, which is why we keep it maintained.
Issues and PRs get read. Good ones get merged.
blendbyte.com · hello@blendbyte.com
