view release on metacpan or  search on metacpan

lib/Business/Payr/Webhook/Payment.pm  view on Meta::CPAN

package Business::Payr::Webhook::Payment;

=head1 NAME

Business::Payr::Webhook::Payment - class representing a Payr webhook
payment event, as received from the Payr webhook notification system.

=head1 SYNOPSIS

    my $Webhook = Business::Payr::Webhook->new(
        body      => $raw_request_body,
        signature => $x_payr_signature_header,
        secret    => $webhook_secret,
    );

    my $Payment = $Webhook->resource;

    if ( $Payment->completed ) {
        printf "Payment %s completed: %s %s\n",
            $Payment->payment_id,
            $Payment->currency,
            $Payment->amount;
    }

    if ( $Payment->failed ) {
        warn "Payment failed: " . $Payment->error_message;
    }

    if ( $Payment->pending ) {
        warn "Payment pending: " . $Payment->pending_reason;
    }

=head1 DESCRIPTION

A C<Business::Payr::Webhook::Payment> object is returned by
L<Business::Payr::Webhook/resource> after a webhook payload has been
verified and parsed. It provides typed access to all documented fields
across the three Payr payment event types (C<payment_success>,
C<payment_failed>, C<payment_pending>), as well as convenience status
and event-type predicate methods.

=cut

use strict;
use warnings;
use feature qw/ signatures /;

use Moose;
no warnings qw/ experimental::signatures /;

use namespace::autoclean;

=head1 ATTRIBUTES

The following attributes are common to all three payment event types.

=over

=item event (Str, required)

The event type string. One of C<payment_success>, C<payment_failed>,
or C<payment_pending>.

=item student_ref (Str, required)

Your external student / tenant reference, as supplied at onboarding.

=item payment_id (Str, required)

The Payr-assigned payment identifier.

=item amount (Int, required)

The payment amount in B<minor units> (pence). For example, C<85000>
represents £850.00.

=item currency (Str, required)

The ISO 4217 currency code (e.g. C<"GBP">).

=item timestamp (Str, required)

ISO 8601 timestamp of the event (e.g. C<"2024-09-01T12:00:00Z">).

=item payment_method (Str, required)

The payment method used (e.g. C<"card">).

=item transaction_id (Str, required)

The acquirer transaction ID. May be an empty string for failed or
pending events where no acquirer transaction was created.

=item status (Str, required)

The payment status. One of C<"completed">, C<"failed">, or C<"pending">.

=back

The following attributes are present only for C<payment_success> events.

=over

=item schedule_activated (Bool)

Whether a payment installment schedule was activated by this payment.

=item schedule_id (Str)

The schedule ID, present when C<schedule_activated> is C<true>.