/ 
Business-Payr-0.02
/ README.md

NAME

Business::Payr - Perl library for interacting with the Payr API ( https://docs.payr.com/ )

VERSION

v0.01

SYNOPSIS

my $Payr = Business::Payr->new(

    # required constructor argument
    api_token => $payr_server_api_token,

    # optional constructor arguments (with defaults shown)
    api_host    => 'api.mypayr.co.uk',
    iframe_host => 'mypayr.co.uk',
);

# For sandbox / testing use the sandbox hosts:
my $Payr = Business::Payr->new(
    api_token   => $payr_sandbox_api_token,
    api_host    => 'sandbox-api.mypayr.co.uk',
    iframe_host => 'sandbox.mypayr.co.uk',
);

# Onboard a user with their tenancy details and KYC documents
$Payr->onboard_user( \%user_args );

# Onboard multiple users in a single call
$Payr->onboard_user( [ \%user_one, \%user_two ] );

# Create a payment session for an already-onboarded user
my $Session = $Payr->create_payment_session( 'john.smith@example.com' );

# Embed the Payr payment iframe in your page
print $Session->iframe_html;

# Or with custom dimensions
print $Session->iframe_html( width => '80%', height => 800 );

# Access the raw session URL directly
my $url = $Session->url;

# Rotate the server API token (do this periodically for security)
my $rotation   = $Payr->rotate_token;
my $new_token  = $rotation->{token};
my $old_expiry = $rotation->{old_token_expiry};

# Handle incoming webhooks
use Business::Payr::Webhook;

my $Webhook = Business::Payr::Webhook->new(
    body      => $raw_request_body,        # raw POST body string
    signature => $x_payr_signature_header, # X-Payr-Signature header value
    secret    => $webhook_secret,          # your Payr webhook secret
);

# Signature is verified during construction - wrap in eval / try
my $Payment = eval { $Webhook->resource };
if ( $@ ) {
    warn "Webhook verification failed: $@";
    return http_response( 400 );
}

if ( $Payment->completed ) {
    printf "Payment %s completed: %.2f %s for student %s\n",
        $Payment->payment_id,
        $Payment->amount / 100,
        $Payment->currency,
        $Payment->student_ref;

    if ( $Payment->schedule_activated ) {
        printf "Schedule %s activated; next instalment: %s\n",
            $Payment->schedule_id,
            $Payment->next_installment_date // 'N/A';
    }
}
elsif ( $Payment->failed ) {
    warn sprintf "Payment %s failed (%s): %s\n",
        $Payment->payment_id,
        $Payment->error_code    // 'unknown',
        $Payment->error_message // 'no detail';
}
elsif ( $Payment->pending ) {
    warn "Payment " . $Payment->payment_id
        . " is pending: " . ( $Payment->pending_reason // 'unknown reason' );
}

DESCRIPTION

Business::Payr is a client library for interacting with the Payr third-party integration API. It handles the necessary authentication and transport logic, allowing you to focus on just the endpoints you want to call.

Payr enables your users to pay their rent by card through an embedded payment interface. With this library you can:

The initial version of this distribution supports those steps described at https://docs.payr.com/ and others will be added as necessary (pull requests also welcome).

ENVIRONMENTS

| Environment | API Base URL | Iframe URL | |-------------|---------------------------------------------------|-------------------------------| | Sandbox | https://sandbox-api.mypayr.co.uk/thirdparty | https://sandbox.mypayr.co.uk | | Production | https://api.mypayr.co.uk/thirdparty | https://mypayr.co.uk |

Always test thoroughly in the sandbox environment before moving to production.

DEBUGGING

Set MOJO_CLIENT_DEBUG=1 for user agent and transport debug output.

METHODS

onboard_user

Onboard one or more users to the Payr platform with their tenancy details and KYC documents. Calls the /thirdparty/onboarding/ endpoint.

# Single user
$Payr->onboard_user( \%user_args );

# Batch onboarding
$Payr->onboard_user( [ \%user_one, \%user_two ] );

$user_args should be a hash reference (single user) or array reference of hash references (multiple users) containing the fields described at https://docs.payr.com/onboarding.

Required user fields: user_id, email, first_name, last_name, phone_number, date_of_birth, tenant (array), kyc (object).

If a user already exists (matched by user_id), their information is updated. If a tenancy already exists (matched by user_id, start_rent_date, payment_reference, and address_1), only end_rent_date, amount, and frequency can be updated.

Returns 1 on success. Throws an exception on failure with a descriptive error message including any field-level validation errors returned by the API.

create_payment_session

Creates a temporary payment session token for an already-onboarded user. Calls the /thirdparty/user-login/ endpoint.

my $Session = $Payr->create_payment_session( 'john.smith@example.com' );

The user identified by $email must have been previously onboarded via onboard_user, otherwise a 400 error is thrown.

Returns a Business::Payr::PaymentSession object. The session URL embedded in that object is valid for 15 minutes. Pass it to ->iframe_html to generate the HTML snippet required to embed the Payr payment interface.

Any issues here will result in an exception being thrown.

rotate_token

Generates a new server API token, replacing the current one. Calls the /thirdparty/rotate-token/ endpoint. The old token remains valid for a grace period of 7–15 days, allowing you to update your systems without downtime.

my $rotation = $Payr->rotate_token;

my $new_token  = $rotation->{token};
my $old_expiry = $rotation->{old_token_expiry};

Returns a hash reference with keys token (the new token string) and old_token_expiry (ISO 8601 datetime string). Any issues will result in an exception being thrown.

SEE ALSO

Business::Payr::Request

Business::Payr::PaymentSession

Business::Payr::Webhook

Business::Payr::Webhook::Payment

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