PHP SDK API Reference

This page lists the public classes and methods of the orcarail/orcarail-php package (namespace OrcaRail\). For installation, configuration, and examples, see the PHP SDK guide.

Client

new OrcaRail\OrcaRailClient(array $config)

Creates a client. All authenticated calls use HTTP Basic Auth with your API key and secret.

Config keys:

Key	Type	Default	Description
api_key	string	—	OrcaRail API key (e.g. ak_live_xxx). Required unless http_client is supplied.
api_secret	string	—	OrcaRail API secret (e.g. sk_live_xxx). Required unless http_client is supplied.
base_url	string	https://api.orcarail.com/api/v1	Versioned API base URL. Use another version by pointing at its base URL.
timeout	int	30000	Total request timeout in milliseconds.
connect_timeout	int	10000	Connection timeout in milliseconds.
http_client	OrcaRail\HttpClient\ClientInterface	OrcaRail\HttpClient\CurlClient	Custom transport, mainly for tests. Replaces the built-in cURL client.

Throws InvalidArgumentException when http_client does not implement ClientInterface, when credentials are missing for the default transport, or when a timeout is not positive.

Service properties (created on first access, then reused):

Property	Class
paymentIntents	OrcaRail\Service\PaymentIntentService
subscriptions	OrcaRail\Service\SubscriptionService
pay	OrcaRail\Service\PayService
rates	OrcaRail\Service\RateService
products	OrcaRail\Service\ProductService
prices	OrcaRail\Service\PriceService

Accessing any other property throws InvalidArgumentException.

use OrcaRail\OrcaRailClient;

$orcarail = new OrcaRailClient([
    'api_key' => getenv('ORCARAIL_API_KEY'),
    'api_secret' => getenv('ORCARAIL_API_SECRET'),
]);

Services

Request parameters are associative arrays with the same field names as the REST API. Responses are OrcaRailObject instances unless noted otherwise.

$orcarail->paymentIntents

See Payment Intents overview and the REST reference.

Method	Description
create(array $params)	Create a payment intent. Requires either price_id or all of amount, currency, tokenId, networkId. Defaults payment_method_types to ['crypto'].
retrieve(string $id)	Get a payment intent by UUID.
confirm(string $id, array $params)	Confirm and get the hosted pay URL. Params: client_secret, return_url. Sends API key authentication in addition to the client secret.
complete(string $id)	Mark the intent as processing when the customer lands on the return URL. Triggers payment_intent.processing.
update(string $id, array $params)	Update amount, currency, tokenId, networkId, price_id, metadata, URLs, expires_at, or withdrawal_addresses.
cancel(string $id)	Cancel a payment intent.

Create params: price_id, amount, currency, tokenId, networkId, payment_method_types, return_url, cancel_url, description, metadata, expires_at, withdrawal_addresses (keyed by chain family, e.g. ['evm' => '0x…']).

Combining price_id with any of amount, currency, tokenId, or networkId throws InvalidArgumentException, as does omitting both forms.

Networks and tokens: the SDK has no list methods for them. Use GET Payments: List Networks and GET Payments: List Tokens by Network, then pass the returned UUIDs as networkId and tokenId.

$orcarail->subscriptions

Collection routes infer the organization from the authenticated API key; item routes are top-level by subscription id.

Method	Description
create(array $params)	Create a subscription. Requires either price_id or all of amount, currency, token_id, network_id, interval.
retrieve(string $id)	Get a subscription by id.
update(string $id, array $params)	Update a subscription (e.g. cancel_at_period_end, pause_collection, metadata).
cancel(string $id, array $params = [])	Cancel a subscription. Optional cancellation_details (comment, feedback). Sends no body when $params is empty.
resume(string $id)	Resume a paused subscription.
all(array $params = [])	List subscriptions. Returns an envelope with data and has_more. Named all() because list is a PHP reserved word.
listPaymentLinks(string $id, array $params = [])	List payment links for a subscription. Returns an envelope with data and has_more.

List params: status, collection_method, limit, starting_after, ending_before, and the range filters created, current_period_start, current_period_end. Range filters are nested arrays and are encoded as bracketed query parameters, so ['current_period_end' => ['lte' => $iso]] is sent as current_period_end[lte]=…. Booleans are encoded as true/false.

Payer-facing auto-charge endpoints are intentionally absent; see Auto-charge.

$orcarail->pay

Pay by payment-link slug. See Pay API.

Method	Description
retrieve(string $slug)	Get the payment intent behind a payment-link slug.
get(string $slug)	Alias of retrieve().
cancel(string $slug)	Cancel by slug.

$orcarail->rates

Fiat quotes and supported currencies. See Price API.

Method	Description
getFiatQuote(array $params)	Fiat-to-USD/USDC quote. Params: amount, currency. Returns an object with amountUsd, amountUsdc, sourceAmount, sourceCurrency.
getCurrencies(array $options = [])	List fiat currencies. Option: active (bool). Returns list<OrcaRailObject>.

$orcarail->products

Organization-scoped catalog products. Each method takes the organization UUID first.

Method	Description
all(string $organizationId)	List products. Unwraps the list envelope; returns list<OrcaRailObject>.
create(string $organizationId, array $params)	Create a product (name, description, active, metadata).
update(string $organizationId, string $productId, array $params)	Update a product.
delete(string $organizationId, string $productId)	Delete (deactivate) a product.

$orcarail->prices

Organization-scoped catalog prices, plus helpers for one-time prices.

Method	Description
all(string $organizationId, array $params = [])	List prices (e.g. ['active' => true, 'recurring' => true]). Returns list<OrcaRailObject>.
create(string $organizationId, array $params)	Create a price (product, nickname, unit_amount_decimal, currency, token_id, network_id, recurring, active, metadata).
update(string $organizationId, string $priceId, array $params)	Update a price.
deactivate(string $organizationId, string $priceId)	Deactivate a price.
listActiveRecurring(string $organizationId)	Shorthand for active recurring prices.
findOneTimeByAmount(string $organizationId, array $params)	Find an active one-time price matching amount, currencyCode, and productName. Returns null when absent.
ensureOneTime(string $organizationId, array $params)	Find or create a one-time price, creating the product when needed. Params: amount, currencyCode, tokenId, networkId, productName, optional productDescription, productMetadata.

Amounts are normalized to two decimals; a non-numeric or non-positive amount throws InvalidArgumentException. A malformed catalog envelope throws UnexpectedValueException.

Webhooks

Both helpers are static and need no client. Always pass the unmodified request body.

OrcaRail\Webhook

Method	Description
Webhook::constructEvent(string $payload, string $signature, string $secret)	Verifies the signature and parses the body into an OrcaRailObject. Throws SignatureVerificationException on an invalid signature, invalid JSON, or a non-object body.

OrcaRail\WebhookSignature

Method	Description
WebhookSignature::verifyHeader(string $payload, string $signature, string $secret)	Returns true when the x-webhook-signature header equals the HMAC-SHA256 of the raw body, compared with hash_equals(). Empty values and non-hex signatures return false.
WebhookSignature::assertValid(string $payload, string $signature, string $secret)	Same check, but throws SignatureVerificationException instead of returning false.

See Webhooks and Signatures.

OrcaRail\OrcaRailObject

Forward-compatible response object. Nested JSON objects become OrcaRailObject; JSON arrays stay PHP lists. Unknown fields are preserved, so responses do not break when the API adds fields.

Member	Description
__get(string $name)	Property access. Returns null for missing keys.
ArrayAccess	$object['field'] reads, writes, isset(), and unset(). Keys must be strings.
IteratorAggregate, Countable	foreach over fields and count($object).
toArray()	Recursive plain-array conversion.
jsonSerialize()	Makes json_encode($object) return the same structure.
OrcaRailObject::convert(mixed $value)	Static helper used to hydrate decoded JSON.

Enums

Backed string enums under OrcaRail\Enum\. Compare against $enum->value when reading API strings.

Enum	Cases
PaymentIntentStatus	requires_payment_method, requires_confirmation, processing, completed, canceled
PaymentStatus	pending, partial_confirmed, confirmed, canceled, expired, completed, withdrawn
SubscriptionStatus	trialing, active, past_due, canceled, paused, completed
WebhookEventType	payment_intent.completed, payment_intent.processing, payment_intent.canceled, payment_intent.requires_payment_method, payment_intent.requires_confirmation, subscription.created, subscription.updated, subscription.canceled, subscription.paused, subscription.resumed, subscription.trial_will_end, subscription.payment_link.created, subscription.payment_link.paid, subscription.payment_link.payment_failed, subscription.past_due, subscription.completed

Handle unrecognized event types gracefully — new events can be added.

Exceptions

All SDK exceptions extend OrcaRail\Exception\OrcaRailException, which extends RuntimeException.

Class	When thrown
OrcaRailException	Base class for all SDK exceptions.
ApiException	API returned a non-2xx status. Properties: statusCode, type, details, request.
AuthenticationException	401 — invalid API key or secret. Extends ApiException with type authentication_error.
TransportException	Network failure, timeout, unencodable request, or undecodable response. Property: request.
SignatureVerificationException	Webhook signature invalid or body not a JSON object. Property: signature.

InvalidArgumentException and UnexpectedValueException (PHP built-ins) signal local misuse: bad parameter combinations, invalid config, unknown service names, or an unexpected response shape.

HTTP transport

Class / interface	Description
OrcaRail\HttpClient\ClientInterface	request(string $method, string $path, ?array $body = null, bool $requireAuth = true): mixed. Implement it to swap transports in tests.
OrcaRail\HttpClient\CurlClient	Default cURL transport. Sends Accept/Content-Type: application/json, Basic auth when required, and User-Agent: orcarail-php/<version>. Non-JSON bodies are returned as strings; empty bodies as null.

CurlClient::DEFAULT_BASE_URL is https://api.orcarail.com/api/v1. Path segments are URL-encoded and query strings are RFC 3986 encoded.

Other classes

Class	Description
OrcaRail\Version	Version::VERSION — package version used in the User-Agent header.
OrcaRail\CatalogPlanMetadata	parse() normalizes catalog plan metadata (array or object) into an OrcaRailObject.

See Also

• PHP SDK guide - Installation, configuration, and examples
• Node SDK API Reference - Equivalent reference for JavaScript and TypeScript
• Payment Intents API - REST reference