/ 
Business-Payr-0.02
/ Business::Payr::Webhook::Payment

NAME

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

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;
}

DESCRIPTION

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

ATTRIBUTES

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

event (Str, required)

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

student_ref (Str, required)

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

payment_id (Str, required)

The Payr-assigned payment identifier.

amount (Int, required)

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

currency (Str, required)

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

timestamp (Str, required)

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

payment_method (Str, required)

The payment method used (e.g. "card").

transaction_id (Str, required)

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

status (Str, required)

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

The following attributes are present only for payment_success events.

schedule_activated (Bool)

Whether a payment installment schedule was activated by this payment.

schedule_id (Str)

The schedule ID, present when schedule_activated is true.

next_installment_date (Str)

The next installment due date (YYYY-MM-DD), or undef if none.

The following attributes are present only for payment_failed events.

error_code (Str)

A machine-readable error code (e.g. "card_declined").

error_message (Str)

A human-readable description of the failure.

The following attribute is present only for payment_pending events.

pending_reason (Str)

A string describing why the payment is pending (e.g. "3ds_authentication_pending").

METHODS

Status Methods

completed

failed

pending

Check whether the payment is in a given status:

if ( $Payment->completed ) { ... }
if ( $Payment->failed )    { ... }
if ( $Payment->pending )   { ... }

Each returns 1 if the status attribute matches, 0 otherwise.

Event Type Methods

is_payment_success

is_payment_failed

is_payment_pending

Check which type of payment event this object represents:

if ( $Payment->is_payment_success ) { ... }
if ( $Payment->is_payment_failed  ) { ... }
if ( $Payment->is_payment_pending ) { ... }

Each returns 1 if the event attribute matches, 0 otherwise.

SEE ALSO

Business::Payr::Webhook

Business::Payr

AUTHORS

Lee Johnson - leejo@cpan.org

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. If you would like to contribute documentation, features, bug fixes, or anything else then please raise an issue / pull request:

https://github.com/payprop/business-payr

1 POD Error

The following errors were encountered while parsing the POD:

Around line 75:

Non-ASCII character seen before =encoding in '£850.00.'. Assuming UTF-8