omnitrade/paypal API reference

Omnitrade\PayPal

Api class

final class Api Api.php:16

PayPal's REST API (v2 Orders, v2 Payments, v1 webhook verification), on an OAuth2 client-credentials token fetched once and kept until it expires.

The sandbox and the live site are the same API at two addresses.

const LIVE = 'https://api-m.paypal.com'

const SANDBOX = 'https://api-m.sandbox.paypal.com'

public readonly bool $sandbox

Api::__construct()

public function __construct(readonly HttpClientInterface $http, readonly string $clientId, readonly string $secret, public readonly bool $sandbox = false, readonly ?string $webhookId = null, readonly int $timeout = 15)

Api::base()

public function base(): string

Api::authorized()

public function authorized(array $order): array

An order as it stands once authorized: an intent AUTHORIZE order the buyer approved holds no authorization until the merchant asks for it (POST /v2/checkout/orders/{id}/authorize, once per order: its PayPal-Request-Id is "<order>-authorize"); then the order read again.

Any other order is given back as it is.

Throws

ProviderException

Api::call()

public function call(string $method, string $path, ?array $body = null, array $headers = []): array

Returns

the JSON answer (empty for 204)

Throws

ProviderException

Api::verifyWebhook()

public function verifyWebhook(string $body, array $transmission): void

Whether a webhook was sent by PayPal to this webhook id: PayPal itself checks the transmission's signature (POST /v1/notifications/verify-webhook-signature).

$transmission

the PAYPAL-* headers

Throws

InvalidNotificationException

Orders class

final class Orders Orders.php:11

A v2 order, as PayPal answers it, read as a Transaction; and a Payment written as one.

Orders::transaction()

public static function transaction(array $order): Transaction

Orders::create()

public static function create(Payment $payment, string $intent): array

Returns

a v2 order to create

PayPalGatewayFactory class

final class PayPalGatewayFactory extends GatewayFactory PayPalGatewayFactory.php:28

PayPal: orders approved on PayPal's page, captured when the buyer comes back, authorizations, refunds, and the webhook's events - the v2 REST API.

options: client_id: '%env(PAYPAL_CLIENT_ID)%' secret: '%env(PAYPAL_SECRET)%' sandbox: true # the sandbox API, with sandbox credentials webhook_id: '%env(PAYPAL_WEBHOOK_ID)%' # the webhook's id in the developer dashboard, for notify() timeout: 15

Options

Omnitrade\PayPal\Action

AuthorizeAction class

final class AuthorizeAction implements ActionInterface, ApiAwareInterface AuthorizeAction.php:18

An order with intent AUTHORIZE: approved on PayPal's page (PENDING with the page's URL); capture() then reserves and takes the money (or void() lets it go).

AuthorizeAction::__construct()

public function __construct()

AuthorizeAction::supports()

public function supports(Request $request): bool

AuthorizeAction::execute()

public function execute(Request $request): void

CaptureAction class

final class CaptureAction implements ActionInterface, ApiAwareInterface CaptureAction.php:22

Take the money of an approved order (the buyer is back): an order made with intent CAPTURE is captured; one made with intent AUTHORIZE is authorized then its authorization captured, for $amount or all of it. An order already captured is answered as it is - capture() may be called twice (the return page and the webhook).

CaptureAction::__construct()

public function __construct()

CaptureAction::supports()

public function supports(Request $request): bool

CaptureAction::execute()

public function execute(Request $request): void

FetchTransactionAction class

final class FetchTransactionAction implements ActionInterface, ApiAwareInterface FetchTransactionAction.php:14

The order as PayPal has it now; an approved AUTHORIZE order authorized first (Api::authorized()).

FetchTransactionAction::__construct()

public function __construct()

FetchTransactionAction::supports()

public function supports(Request $request): bool

FetchTransactionAction::execute()

public function execute(Request $request): void

GetPaymentMethodsAction class

final class GetPaymentMethodsAction implements ActionInterface GetPaymentMethodsAction.php:17

What PayPal's page offers: the PayPal account, the cards it takes as a guest, and Pay Later where PayPal offers it - Australia, France, Germany, Italy, Spain, the United Kingdom and the United States, each in its own currency (PayPal's Pay Later documentation). A country or an amount's currency outside those leaves Pay Later out.

GetPaymentMethodsAction::supports()

public function supports(Request $request): bool

GetPaymentMethodsAction::execute()

public function execute(Request $request): void

NotifyAction class

final class NotifyAction implements ActionInterface, ApiAwareInterface NotifyAction.php:23

A PayPal webhook, verified by PayPal itself: the order and capture events read as what they mean for the order. CHECKOUT.ORDER.APPROVED is still PENDING (the money comes with capture()); PAYMENT.CAPTURE.COMPLETED is PAID; DENIED is REFUSED; REFUNDED is REFUNDED. The reference is the order's id, taken from the capture's related ids when the event is a capture's.

NotifyAction::__construct()

public function __construct()

NotifyAction::supports()

public function supports(Request $request): bool

NotifyAction::execute()

public function execute(Request $request): void

PurchaseAction class

final class PurchaseAction implements ActionInterface, ApiAwareInterface PurchaseAction.php:19

An order with intent CAPTURE: the buyer approves it on PayPal's page (PENDING with the page's URL), comes back to returnUrl with ?token=<order id>, and capture() takes the money. PayPal-Request-Id carries the idempotency key.

PurchaseAction::__construct()

public function __construct()

PurchaseAction::supports()

public function supports(Request $request): bool

PurchaseAction::execute()

public function execute(Request $request): void

RefundAction class

final class RefundAction implements ActionInterface, ApiAwareInterface RefundAction.php:17

Money back on a capture: the reference is the order's (its first capture) or the capture's own.

RefundAction::__construct()

public function __construct()

RefundAction::supports()

public function supports(Request $request): bool

RefundAction::execute()

public function execute(Request $request): void

VoidAction class

final class VoidAction implements ActionInterface, ApiAwareInterface VoidAction.php:15

Let an order's authorization go: the reference is the order's, or the authorization's own.

VoidAction::__construct()

public function __construct()

VoidAction::supports()

public function supports(Request $request): bool

VoidAction::execute()

public function execute(Request $request): void