omnitrade/stripe Référence de l’API

Omnitrade\Stripe

Accounts class

final class Accounts Accounts.php:10

Stripe's account and subscription objects as Omnitrade's models.

Accounts::account()

public static function account(array $account): Account

Accounts::subscription()

public static function subscription(array $subscription): Subscription

Api class

final class Api Api.php:24

Stripe, through omnipay/stripe: the Checkout gateway (hosted payment page) and the PaymentIntents gateway (what was paid, refunds), both on one secret key. Omnipay talks through the application's HTTP client when one is given (a PSR-18 bridge): the profiler sees the calls, the tests mock them.

The catalogue's plain reads (products, prices) go straight through that client, get(), with the secret key as a bearer token.

const SIGNATURE_HEADER = 'Stripe-Signature'

const BASE_URI = 'https://api.stripe.com'

Api::__construct()

public function __construct(readonly string $apiKey, readonly ?string $webhookSecret = null, readonly ?HttpClientInterface $http = null)

Api::checkout()

public function checkout(): CheckoutGateway

Api::intents()

public function intents(): PaymentIntentsGateway

Api::get()

public function get(string $path, array $query = []): array

A GET of Stripe's REST API: "/v1/products", with its query (arrays as Stripe reads them, expand[0]=...).

Throws

ProviderException with Stripe's error code ("resource_missing")

Api::post()

public function post(string $path, array $parameters = [], ?string $idempotencyKey = null): array

A POST of Stripe's REST API, form-encoded as Stripe reads it (nested arrays as a[b][c]=...; booleans as "true" / "false"): accounts, account links, portal sessions, subscriptions - what omnipay/stripe has no message for.

Throws

ProviderException with Stripe's error code

Api::delete()

public function delete(string $path, array $parameters = []): array

Api::sendOmnipay()

public function sendOmnipay(\Omnipay\Common\Message\RequestInterface $request): \Omnipay\Common\Message\ResponseInterface

Sends one of omnipay's requests (Checkout, payment intents): a network failure, or a request omnipay refuses before sending it (a parameter missing), is a ProviderException, like any other of Stripe's.

Throws

ProviderException

Api::canVerify()

public function canVerify(): bool

Api::verify()

public function verify(string $payload, ?string $header, int $tolerance = 300): void

Whether a webhook payload was signed by Stripe with the endpoint's secret (Stripe-Signature: t=timestamp,v1=hmac), within $tolerance seconds.

Throws

InvalidNotificationException

CheckoutGateway class

class CheckoutGateway extends OmnipayCheckoutGateway CheckoutGateway.php:8

omnipay/stripe's Checkout gateway, its purchase() our request (CheckoutPurchaseRequest).

CheckoutGateway::purchase()

public function purchase(array $parameters = []): CheckoutPurchaseRequest

CheckoutPurchaseRequest class

class CheckoutPurchaseRequest extends PurchaseRequest CheckoutPurchaseRequest.php:24

omnipay/stripe's Checkout session request, with what it does not send:

customer_email the buyer's address, filled in on Stripe's page adaptive_pricing off by default: the session is paid in the given currency, not converted to the buyer's locale the page's language client_reference_id the merchant's reference (the order's) - the parent's parameter, sent here metadata kept by Stripe, given back on every event notice a mention on the page and the receipt (why no VAT...) destination a connected account the payment is passed on to (Connect destination charge) applicationFee what the platform keeps of it, in minor units shippingOptions shipping_options: the shipping rate charged on top of the lines

The methods to insist on (paymentMethodTypes) and the Idempotency-Key header (setIdempotencyKeyHeader) are the parent's.

CheckoutPurchaseRequest::getCustomerEmail()

public function getCustomerEmail(): ?string

CheckoutPurchaseRequest::setCustomerEmail()

public function setCustomerEmail(?string $value): self

CheckoutPurchaseRequest::getAdaptivePricing()

public function getAdaptivePricing(): bool

CheckoutPurchaseRequest::setAdaptivePricing()

public function setAdaptivePricing(bool $value): self

CheckoutPurchaseRequest::getLocale()

public function getLocale(): ?string

CheckoutPurchaseRequest::setLocale()

public function setLocale(?string $value): self

CheckoutPurchaseRequest::getDestination()

public function getDestination(): ?string

CheckoutPurchaseRequest::setDestination()

public function setDestination(?string $value): self

CheckoutPurchaseRequest::getApplicationFee()

public function getApplicationFee(): ?int

CheckoutPurchaseRequest::setApplicationFee()

public function setApplicationFee(?int $value): self

CheckoutPurchaseRequest::getShippingOptions()

public function getShippingOptions(): ?array

CheckoutPurchaseRequest::setShippingOptions()

public function setShippingOptions(?array $value): self

CheckoutPurchaseRequest::getNotice()

public function getNotice(): ?string

CheckoutPurchaseRequest::setNotice()

public function setNotice(?string $value): self

CheckoutPurchaseRequest::getData()

public function getData(): array

Products class

final class Products Products.php:19

Stripe's Products and their Prices, read as Products: one variant per active price (the default price first), no stock - Stripe counts none.

Metadata are the attributes; by convention its "brand" is the brand, "category"/"categories" and "tags" (comma-separated) the categories and tags, "slug" (or "handle") the handle, a price's "sku" its variant's.

Products::fetch()

public static function fetch(Api $api, array $product): Product

A Stripe product with its active prices, fetched (GET /v1/prices?product=...).

Products::find()

public static function find(Api $api, string $id): ?Product

One product by its id, with its prices; null when Stripe has none.

Throws

ProviderException

Products::prices()

public static function prices(Api $api, string $product): array

Returns

the product's active prices, every page

Products::product()

public static function product(array $product, array $prices): Product

$product

a Stripe product (default_price expanded or not)

$prices

its active prices

Sessions class

final class Sessions Sessions.php:10

A Checkout session, as Stripe answers it, read as a Transaction.

Sessions::transaction()

public static function transaction(array $session): Transaction

StripeGatewayFactory class

final class StripeGatewayFactory extends GatewayFactory StripeGatewayFactory.php:44

Stripe: cards and wallets through Checkout (the hosted page), what was paid, refunds, the webhook's events, and the catalogue kept in Stripe's Products and Prices (no stock: fetchInventory() is not supported).

Connect: Express accounts opened for those the platform pays (createAccount(), accountLink(), fetchAccount()), and payments sent to them as destination charges (Payment::$destination, ::$applicationFee). Subscriptions: Checkout in subscription mode (subscribe()), the customer portal, cancellation; account.updated and customer.subscription.* events read by notify().

options: api_key: '%env(STRIPE_API_KEY)%' # sk_live_... / sk_test_... webhook_secret: '%env(STRIPE_WEBHOOK_SECRET)%' # whsec_..., for notify() adaptive_pricing: false # true: Stripe may offer the buyer's own currency payment_methods: [] # ['card', 'sepa_debit']: the methods to insist on active_only: false # true: fetchProducts() lists the active products only

No authorizations: Checkout takes the money when the buyer pays (a session in "setup"/"authorize" mode is not offered here).

Options

Omnitrade\Stripe\Action

AccountLinkAction class

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

The onboarding page of a connected account (POST /v1/account_links): single use, valid a few minutes.

AccountLinkAction::__construct()

public function __construct()

AccountLinkAction::supports()

public function supports(Request $request): bool

AccountLinkAction::execute()

public function execute(Request $request): void

CancelSubscriptionAction class

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

Stops a subscription: at the end of the paid period (POST, cancel_at_period_end) or at once (DELETE /v1/subscriptions/{id}).

CancelSubscriptionAction::__construct()

public function __construct()

CancelSubscriptionAction::supports()

public function supports(Request $request): bool

CancelSubscriptionAction::execute()

public function execute(Request $request): void

CreateAccountAction class

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

A connected account (POST /v1/accounts): Express by default, in the holder's country, with the capabilities asked for - "transfers" to be sent destination charges, "card_payments" with it where Stripe requires both.

CreateAccountAction::__construct()

public function __construct()

CreateAccountAction::supports()

public function supports(Request $request): bool

CreateAccountAction::execute()

public function execute(Request $request): void

FetchAccountAction class

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

A connected account as it stands (GET /v1/accounts/{id}).

FetchAccountAction::__construct()

public function __construct()

FetchAccountAction::supports()

public function supports(Request $request): bool

FetchAccountAction::execute()

public function execute(Request $request): void

FetchProductAction class

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

One Stripe product by its id (prod_...), with its active prices. Stripe hosts no product pages: an address answers null, as an unknown id does.

FetchProductAction::__construct()

public function __construct()

FetchProductAction::supports()

public function supports(Request $request): bool

FetchProductAction::execute()

public function execute(Request $request): void

FetchProductsAction class

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

A page of Stripe's Products, each with its active Prices (one call per product): GET /v1/products, the cursor the last product's id (starting_after); with a query, GET /v1/products/search on name~"...", the cursor Stripe's next_page. Stripe's search knows no update date, so updatedSince keeps the products whose "updated" is that late among each page - a page may come back short, or empty with a next one. Pass the same updatedSince and query with the cursor.

FetchProductsAction::__construct()

public function __construct(readonly bool $activeOnly = false)

FetchProductsAction::supports()

public function supports(Request $request): bool

FetchProductsAction::execute()

public function execute(Request $request): void

FetchProductsAction::search()

public static function search(string $text): string

Stripe's search: name~"..." (a substring, three characters at least), name:"..." below.

FetchSubscriptionAction class

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

A subscription as it stands (GET /v1/subscriptions/{id}).

FetchSubscriptionAction::__construct()

public function __construct()

FetchSubscriptionAction::supports()

public function supports(Request $request): bool

FetchSubscriptionAction::execute()

public function execute(Request $request): void

FetchTransactionAction class

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

The Checkout session as Stripe has it now: paid, still open, expired, or refunded - its payment intent and that intent's latest charge expanded, the charge's amount_refunded what says so (unexpanded, Stripe gives the intent's id only).

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:18

What Checkout offers: the methods insisted on in the options, else the card plus the wallets Stripe shows on its own (Apple Pay, Google Pay, Link) - Stripe decides the rest per account, country and currency on its page.

The amount's currency narrows them: the euro-only methods (SEPA Direct Debit, Bancontact, iDEAL, EPS) are left out of an amount in another currency (Stripe's payment method support table).

GetPaymentMethodsAction::__construct()

public function __construct(readonly array $paymentMethods = [])

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:36

A webhook event, its signature checked: the Checkout session events read as what they mean for the transaction - completed and async_payment_succeeded with a paid session is PAID, expired and async_payment_failed is EXPIRED / REFUSED. Any other event is handed back with no status, to ignore or to read from $raw.

account.updated carries the connected account ($account), the customer.subscription.* events the subscription ($subscription); a completed session of a subscription keeps the subscription's id in the transaction's raw data ("subscription"). $reference is the object's id.

The catalogue's events carry the product: product.created and product.updated the event's product with its active prices (one call), price.created, price.updated and price.deleted the price's product, read afresh (two calls); product.deleted the product's id alone. $reference is the product's id.

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:27

A Checkout session: Stripe's hosted page, the buyer sent to it (PENDING with the page's URL); notify() or fetch() then says whether they paid. The lines are listed on the page when they and the shipping add up to the amount, the shipping as the session's shipping rate; else (a discount among them, which Checkout takes only as a coupon made beforehand, or lines that do not add up) the amount is one line under the payment's description. Either way the session charges the payment's amount.

A payment with a destination is a Connect destination charge: taken by the platform, transferred to the connected account, the application fee kept.

PurchaseAction::__construct()

public function __construct(readonly bool $adaptivePricing = false, readonly array $paymentMethods = [])

PurchaseAction::supports()

public function supports(Request $request): bool

PurchaseAction::execute()

public function execute(Request $request): void

PurchaseAction::lines()

public static function lines(Payment $payment): array

Returns

the session's line items, which with shipping() charge the payment's amount

PurchaseAction::shipping()

public static function shipping(Payment $payment): ?array

The shipping as the session's one shipping rate, a fixed amount, when the lines are listed and there is shipping to pay; else null (it is inside the one line).

RefundAction class

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

Money back on what a Checkout session was paid with: its payment intent's charge. The reference is the session's id (cs_...), or a payment intent's (pi_...) or a charge's (ch_...) directly. The idempotency key makes the same refund asked twice happen once. Without an amount, the whole charge (what is left of it) is refunded.

RefundAction::__construct()

public function __construct()

RefundAction::supports()

public function supports(Request $request): bool

RefundAction::execute()

public function execute(Request $request): void

SubscribeAction class

final class SubscribeAction implements ActionInterface, ApiAwareInterface SubscribeAction.php:26

A Checkout session in subscription mode (POST /v1/checkout/sessions): the buyer is sent to Stripe's page (PENDING with its URL), pays the first period, and Stripe renews. The plan is the request's Stripe price when given, else a price made on the fly from the payment (its amount every interval, named by its description). The payment's metadata is put on the session and on the subscription, so every later event carries it.

Then: checkout.session.completed tells of the first payment (the session's "subscription" is the subscription's id), customer.subscription.updated and .deleted of its life, invoice.paid of each renewal.

SubscribeAction::__construct()

public function __construct()

SubscribeAction::supports()

public function supports(Request $request): bool

SubscribeAction::execute()

public function execute(Request $request): void

SubscriptionPortalAction class

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

The customer portal (POST /v1/billing_portal/sessions): card, invoices, cancellation.

SubscriptionPortalAction::__construct()

public function __construct()

SubscriptionPortalAction::supports()

public function supports(Request $request): bool

SubscriptionPortalAction::execute()

public function execute(Request $request): void