byrcsc/laravel-payrex · 1.x

Payments and refunds.

Retrieve completed PayRex payments, add metadata, issue full or partial refunds, and track refund outcomes.

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.

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.