Referencia de la API del SDK de PHP

Esta página lista las clases y métodos públicos del paquete orcarail/orcarail-php (namespace OrcaRail\). Para la instalación, la configuración y los ejemplos, consulta la guía del SDK de PHP.

Cliente

new OrcaRail\OrcaRailClient(array $config)

Crea un cliente. Todas las llamadas autenticadas usan HTTP Basic Auth con tu clave y tu secreto de API.

Claves de configuración:

Clave	Tipo	Por defecto	Descripción
api_key	string	—	Clave de API de OrcaRail (por ejemplo ak_live_xxx). Obligatoria salvo que se indique http_client.
api_secret	string	—	Secreto de API de OrcaRail (por ejemplo sk_live_xxx). Obligatorio salvo que se indique http_client.
base_url	string	https://api.orcarail.com/api/v1	URL base versionada de la API. Para usar otra versión, apunta a su URL base.
timeout	int	30000	Tiempo de espera total de la petición en milisegundos.
connect_timeout	int	10000	Tiempo de espera de la conexión en milisegundos.
http_client	OrcaRail\HttpClient\ClientInterface	OrcaRail\HttpClient\CurlClient	Transporte personalizado, sobre todo para tests. Sustituye al cliente cURL integrado.

Lanza InvalidArgumentException cuando http_client no implementa ClientInterface, cuando faltan credenciales para el transporte por defecto o cuando un tiempo de espera no es positivo.

Propiedades de servicio (se crean en el primer acceso y luego se reutilizan):

Propiedad	Clase
paymentIntents	OrcaRail\Service\PaymentIntentService
subscriptions	OrcaRail\Service\SubscriptionService
pay	OrcaRail\Service\PayService
rates	OrcaRail\Service\RateService
products	OrcaRail\Service\ProductService
prices	OrcaRail\Service\PriceService

Acceder a cualquier otra propiedad lanza InvalidArgumentException.

use OrcaRail\OrcaRailClient;

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

Servicios

Los parámetros de las peticiones son arrays asociativos con los mismos nombres de campo que la API REST. Las respuestas son instancias de OrcaRailObject salvo que se indique lo contrario.

$orcarail->paymentIntents

Consulta la visión general de Payment Intents y la referencia REST.

Método	Descripción
create(array $params)	Crea un payment intent. Requiere price_id o todos estos: amount, currency, tokenId, networkId. payment_method_types vale ['crypto'] por defecto.
retrieve(string $id)	Obtiene un payment intent por UUID.
confirm(string $id, array $params)	Confirma y obtiene la URL de pago alojada. Parámetros: client_secret, return_url. Envía la autenticación con clave de API además del client secret.
complete(string $id)	Marca el intent como en procesamiento cuando el cliente llega a la URL de retorno. Lanza payment_intent.processing.
update(string $id, array $params)	Actualiza amount, currency, tokenId, networkId, price_id, metadata, las URLs, expires_at o withdrawal_addresses.
cancel(string $id)	Cancela un payment intent.

Parámetros de creación: price_id, amount, currency, tokenId, networkId, payment_method_types, return_url, cancel_url, description, metadata, expires_at, withdrawal_addresses (indexado por familia de cadenas, por ejemplo ['evm' => '0x…']).

Combinar price_id con amount, currency, tokenId o networkId lanza InvalidArgumentException, igual que omitir las dos formas.

Redes y tokens: el SDK no tiene métodos para listarlos. Usa GET Pagos: listar redes y GET Pagos: listar tokens por red y pasa los UUID devueltos como networkId y tokenId.

$orcarail->subscriptions

Las rutas de colección deducen la organización de la clave de API autenticada; las rutas de elementos van en el nivel superior por ID de suscripción.

Método	Descripción
create(array $params)	Crea una suscripción. Requiere price_id o todos estos: amount, currency, token_id, network_id, interval.
retrieve(string $id)	Obtiene una suscripción por ID.
update(string $id, array $params)	Actualiza una suscripción (por ejemplo cancel_at_period_end, pause_collection, metadata).
cancel(string $id, array $params = [])	Cancela una suscripción. cancellation_details opcional (comment, feedback). No envía cuerpo si $params está vacío.
resume(string $id)	Reanuda una suscripción en pausa.
all(array $params = [])	Lista suscripciones. Devuelve un envoltorio con data y has_more. Se llama all() porque list es una palabra reservada de PHP.
listPaymentLinks(string $id, array $params = [])	Lista los enlaces de pago de una suscripción. Devuelve un envoltorio con data y has_more.

Parámetros de listado: status, collection_method, limit, starting_after, ending_before y los filtros de rango created, current_period_start, current_period_end. Los filtros de rango son arrays anidados y se codifican como parámetros de consulta con corchetes, así que ['current_period_end' => ['lte' => $iso]] se envía como current_period_end[lte]=…. Los booleanos se codifican como true/false.

Los endpoints de cobro automático de cara al pagador no están incluidos a propósito; consulta Cobro automático.

$orcarail->pay

Pago por el slug del enlace de pago. Consulta la API de pago.

Método	Descripción
retrieve(string $slug)	Obtiene el payment intent asociado al slug de un enlace de pago.
get(string $slug)	Alias de retrieve().
cancel(string $slug)	Cancela por slug.

$orcarail->rates

Cotizaciones fiat y monedas compatibles. Consulta la API de precios.

Método	Descripción
getFiatQuote(array $params)	Cotización de fiat a USD/USDC. Parámetros: amount, currency. Devuelve un objeto con amountUsd, amountUsdc, sourceAmount, sourceCurrency.
getCurrencies(array $options = [])	Lista las monedas fiat. Opción: active (bool). Devuelve list<OrcaRailObject>.

$orcarail->products

Productos del catálogo de la organización. Cada método recibe primero el UUID de la organización.

Método	Descripción
all(string $organizationId)	Lista los productos. Desenvuelve el envoltorio de lista; devuelve list<OrcaRailObject>.
create(string $organizationId, array $params)	Crea un producto (name, description, active, metadata).
update(string $organizationId, string $productId, array $params)	Actualiza un producto.
delete(string $organizationId, string $productId)	Elimina (desactiva) un producto.

$orcarail->prices

Precios del catálogo de la organización, más helpers para precios de pago único.

Método	Descripción
all(string $organizationId, array $params = [])	Lista los precios (por ejemplo ['active' => true, 'recurring' => true]). Devuelve list<OrcaRailObject>.
create(string $organizationId, array $params)	Crea un precio (product, nickname, unit_amount_decimal, currency, token_id, network_id, recurring, active, metadata).
update(string $organizationId, string $priceId, array $params)	Actualiza un precio.
deactivate(string $organizationId, string $priceId)	Desactiva un precio.
listActiveRecurring(string $organizationId)	Atajo para los precios recurrentes activos.
findOneTimeByAmount(string $organizationId, array $params)	Busca un precio de pago único activo que coincida con amount, currencyCode y productName. Devuelve null si no existe.
ensureOneTime(string $organizationId, array $params)	Busca o crea un precio de pago único, creando el producto si hace falta. Parámetros: amount, currencyCode, tokenId, networkId, productName y, opcionalmente, productDescription, productMetadata.

Los importes se normalizan a dos decimales; un importe no numérico o no positivo lanza InvalidArgumentException. Un envoltorio del catálogo mal formado lanza UnexpectedValueException.

Webhooks

Ambos helpers son estáticos y no necesitan cliente. Pasa siempre el cuerpo de la petición sin modificar.

OrcaRail\Webhook

Método	Descripción
Webhook::constructEvent(string $payload, string $signature, string $secret)	Verifica la firma y analiza el cuerpo como OrcaRailObject. Lanza SignatureVerificationException si la firma no es válida, si el JSON no es válido o si el cuerpo no es un objeto.

OrcaRail\WebhookSignature

Método	Descripción
WebhookSignature::verifyHeader(string $payload, string $signature, string $secret)	Devuelve true cuando la cabecera x-webhook-signature es igual al HMAC-SHA256 del cuerpo en bruto, comparándolos con hash_equals(). Los valores vacíos y las firmas no hexadecimales devuelven false.
WebhookSignature::assertValid(string $payload, string $signature, string $secret)	La misma comprobación, pero lanza SignatureVerificationException en lugar de devolver false.

Consulta Webhooks y Firmas.

OrcaRail\OrcaRailObject

Objeto de respuesta compatible con versiones futuras. Los objetos JSON anidados se convierten en OrcaRailObject; los arrays JSON siguen siendo listas de PHP. Los campos desconocidos se conservan, así que las respuestas no se rompen cuando la API añade campos.

Miembro	Descripción
__get(string $name)	Acceso por propiedad. Devuelve null para las claves que faltan.
ArrayAccess	Lectura, escritura, isset() y unset() con $object['field']. Las claves deben ser strings.
IteratorAggregate, Countable	foreach sobre los campos y count($object).
toArray()	Conversión recursiva a un array simple.
jsonSerialize()	Hace que json_encode($object) devuelva la misma estructura.
OrcaRailObject::convert(mixed $value)	Helper estático usado para hidratar el JSON decodificado.

Enums

Enums de string respaldados en OrcaRail\Enum\. Compáralos con $enum->value al leer strings de la API.

Enum	Casos
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

Gestiona con cuidado los tipos de evento desconocidos: se pueden añadir eventos nuevos.

Excepciones

Todas las excepciones del SDK extienden OrcaRail\Exception\OrcaRailException, que extiende RuntimeException.

Clase	Cuándo se lanza
OrcaRailException	Clase base de todas las excepciones del SDK.
ApiException	La API devolvió un estado distinto de 2xx. Propiedades: statusCode, type, details, request.
AuthenticationException	401: clave o secreto de API no válidos. Extiende ApiException con type authentication_error.
TransportException	Fallo de red, tiempo de espera agotado, petición que no se puede codificar o respuesta que no se puede decodificar. Propiedad: request.
SignatureVerificationException	Firma de webhook no válida o cuerpo que no es un objeto JSON. Propiedad: signature.

InvalidArgumentException y UnexpectedValueException (incorporadas en PHP) indican un uso local incorrecto: combinaciones de parámetros no válidas, configuración no válida, nombres de servicio desconocidos o una forma de respuesta inesperada.

Transporte HTTP

Clase / interfaz	Descripción
OrcaRail\HttpClient\ClientInterface	request(string $method, string $path, ?array $body = null, bool $requireAuth = true): mixed. Impleméntala para cambiar de transporte en los tests.
OrcaRail\HttpClient\CurlClient	Transporte cURL por defecto. Envía Accept/Content-Type: application/json, Basic auth cuando hace falta y User-Agent: orcarail-php/<version>. Los cuerpos que no son JSON se devuelven como strings; los vacíos, como null.

CurlClient::DEFAULT_BASE_URL es https://api.orcarail.com/api/v1. Los segmentos de ruta se codifican como URL y las cadenas de consulta con RFC 3986.

Otras clases

Clase	Descripción
OrcaRail\Version	Version::VERSION: versión del paquete usada en la cabecera User-Agent.
OrcaRail\CatalogPlanMetadata	parse() normaliza los metadatos de los planes del catálogo (array u objeto) en un OrcaRailObject.

Consulta también

• Guía del SDK de PHP: instalación, configuración y ejemplos
• Referencia de la API del SDK de Node: referencia equivalente para JavaScript y TypeScript
• API de Payment Intents: referencia REST