byrcsc/laravel-payrex · 1.x

Payments and refunds.

Read completed payments and create full or partial refunds.

A payment is the charge produced by a payment intent. It cannot be created directly through the payments resource.

Retrieve a payment

use ByRcsc\LaravelPayrex\Facades\Payrex;

$payment = Payrex::payments()->retrieve('pay_...');

$payment->amount;
$payment->amountRefunded;
$payment->fee;
$payment->netAmount;
$payment->status;
$payment->paymentIntentId;
$payment->paymentMethod;
$payment->customer;

The Payment object also exposes consolidatedNetAmount, consolidatedStatus, origin, refunded, billing, pageSession, metadata, timestamps, and raw.

$payment->paymentMethod is a PaymentMethodSummary, not a full PaymentMethod: it carries type, details, and raw, but no id. Read the saved-method identifier from the payment intent's paymentMethodId or from listPaymentMethods().

Update a payment

Only the description and metadata are modeled for updates:

$payment = Payrex::payments()->update(
    id: $payment->id,
    description: 'Order #1042',
    metadata: [
        'order_id' => '1042',
        'tenant_id' => 'acme',
    ],
);

Create a refund

use ByRcsc\LaravelPayrex\Enums\Currency;
use ByRcsc\LaravelPayrex\Enums\RefundReason;

$refund = Payrex::refunds()->create(
    amount: 5_000,
    paymentId: $payment->id,
    reason: RefundReason::RequestedByCustomer,
    currency: Currency::PHP,
    description: 'Partial refund for order #1042',
    remarks: 'One item returned unopened',
    metadata: ['order_id' => '1042'],
);

Pass the full payment amount for a total refund or a smaller amount for a partial refund. Amounts are integers in centavos. PayRex validates refund eligibility and the refundable ceiling.

The complete create signature is:

create(
    int $amount,
    string $paymentId,
    RefundReason $reason,
    Currency $currency = Currency::PHP,
    ?string $description = null,
    ?string $remarks = null,
    ?array $metadata = null,
    array $options = [],
): Refund

Refund reasons

RefundReason provides the documented values:

Fraudulent
RequestedByCustomer
ProductOutOfStock
ServiceNotProvided
ProductWasDamaged
ServiceMisaligned
WrongProductReceived
Others

Update a refund

The modeled update operation changes metadata:

$refund = Payrex::refunds()->update(
    id: $refund->id,
    metadata: ['case_id' => 'RMA-1042'],
);

Read status, reason, paymentId, description, remarks, metadata, and raw from the returned Refund.

Track the final outcome

Refund processing can be asynchronous. Listen for RefundCreated and RefundUpdated, then inspect the refund resource delivered with the event:

use ByRcsc\LaravelPayrex\Data\Refund;
use ByRcsc\LaravelPayrex\Events\RefundUpdated;

public function handle(RefundUpdated $event): void
{
    $resource = $event->event->resource();

    if (! $resource instanceof Refund) {
        return;
    }

    // Reconcile the local refund using $resource->id and $resource->status.
}

Make reconciliation idempotent using the PayRex event ID.

What to read next

Payment intents to understand the intent that produced a payment.
Events and listeners to reconcile payment and refund updates.
Errors and retries before retrying a failed refund.