byrcsc/laravel-payrex · 1.x

Payment intents.

Create, update, attach, cancel, and manually capture PayRex payment intents from Laravel.

A payment intent tracks the lifecycle of collecting one amount. Use it when your application controls the payment form with PayRex Elements or needs manual capture.

Create an intent

use ByRcsc\LaravelPayrex\Enums\Currency;
use ByRcsc\LaravelPayrex\Enums\PaymentMethodType;
use ByRcsc\LaravelPayrex\Facades\Payrex;

$intent = Payrex::paymentIntents()->create(
    amount: 10_000,
    paymentMethods: [
        PaymentMethodType::Card,
        PaymentMethodType::Gcash,
    ],
    currency: Currency::PHP,
    description: 'Order #1042',
    customerId: 'cus_...',
    statementDescriptor: 'RCSC ORDER',
    metadata: ['order_id' => '1042'],
);

The complete signature is:

create(
    int $amount,
    array $paymentMethods = [],
    Currency $currency = Currency::PHP,
    ?string $description = null,
    ?string $customerId = null,
    ?array $paymentMethodOptions = null,
    ?string $statementDescriptor = null,
    ?array $metadata = null,
    array $options = [],
): PaymentIntent

Amounts use the smallest currency unit. For Philippine pesos, 10_000 is ₱100.00. The package locally enforces PayRex's documented payment-intent range of 2_000 through 5_999_999_999 centavos: ₱20.00 through ₱59,999,999.99.

Attach a payment method

After PayRex Elements returns a pm_... token, attach it to start the charge:

$intent = Payrex::paymentIntents()->attach(
    id: $intentId,
    paymentMethodId: $paymentMethodId,
);

if ($intent->requiresAction()) {
    return redirect()->away($intent->redirectUrl());
}

The clientSecret and publishable key may be sent to the frontend. The PayRex secret key may not.

Retrieve and update

$intent = Payrex::paymentIntents()->retrieve('pi_...');

$intent = Payrex::paymentIntents()->update(
    id: $intent->id,
    amount: 12_500,
    description: 'Order #1042, updated',
    customerId: 'cus_...',
);

update() accepts id, optional amount, optional description, optional customerId, and options. Null fields are omitted.

Cancel an intent

$intent = Payrex::paymentIntents()->cancel('pi_...');

The returned object contains the status PayRex assigned after cancellation.

Manual capture

Request manual card capture in paymentMethodOptions:

use ByRcsc\LaravelPayrex\Enums\CaptureType;

$intent = Payrex::paymentIntents()->create(
    amount: 10_000,
    paymentMethods: ['card'],
    paymentMethodOptions: [
        'card' => [
            'capture_type' => CaptureType::Manual,
        ],
    ],
);

After the payer authorizes the payment, the intent can reach awaiting_capture. Capture all or part of the authorized amount:

$intent = Payrex::paymentIntents()->capture(
    id: $intent->id,
    amount: 10_000,
);

Use captureBeforeAt to observe the capture deadline when PayRex includes it. Listen for PaymentIntentAwaitingCapture and PaymentIntentSucceeded instead of relying on a browser redirect.

Installments

Installment types are a list under the relevant payment method:

use ByRcsc\LaravelPayrex\Enums\InstallmentType;

$intent = Payrex::paymentIntents()->create(
    amount: 100_000,
    paymentMethods: ['bdo_installment'],
    paymentMethodOptions: [
        'bdo_installment' => [
            'installment_types' => [
                InstallmentType::Zero,
                InstallmentType::Regular,
            ],
        ],
    ],
);

Account eligibility and installment rules are enforced by PayRex.

Read the result

Useful PaymentIntent properties include:

$intent->id;
$intent->status;
$intent->amount;
$intent->amountReceived;
$intent->amountCapturable;
$intent->clientSecret;
$intent->nextAction;
$intent->latestPayment;
$intent->paymentMethodId;
$intent->customer;
$intent->metadata;
$intent->raw;

Convenience methods include hasSucceeded(), requiresAction(), and redirectUrl().