NAME
Business::Payr - Perl library for interacting with the Payr API (https://docs.payr.com/)
VERSION
v0.02
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 );
# Create a payment session for an already-onboarded user
my $Session = $Payr->create_payment_session( '[email protected]' );
# Embed the payment iframe in your page
print $Session->iframe_html;
# 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,
signature => $x_payr_signature_header,
secret => $webhook_secret,
);
my $Payment = $Webhook->resource;
if ( $Payment->completed ) {
# Payment was successful
}DESCRIPTION
Business::Payr is a client library for interacting with the Payr third-party integration API (https://docs.payr.com/). 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:
Onboard users with their tenancy details and KYC documents
Create payment sessions for seamless rent payments
Rotate your server API token for improved security
Verify and parse webhooks for real-time payment notifications (see Business::Payr::Webhook)
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).
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), and either kyc (object) or agent_id (integer).
The kyc field is optional. When it is not provided, agent_id must be supplied instead - this is an integer reference to the agency associated with the tenancy, similar in type to user_id. Supplying neither will result in an exception being thrown before any API call is made.
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( '[email protected]' );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" in Business::Payr::PaymentSession to generate the HTML snippet required to embed the Payr payment interface:
print $Session->iframe_html;
# Or with custom dimensions:
print $Session->iframe_html( width => '80%', height => 800 );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 the following keys:
- token
-
The new server API token string. Update your configuration to use this value before the old token's grace period expires.
- old_token_expiry
-
An ISO 8601 datetime string indicating when the previous token will stop working (e.g.
"2024-01-22T14:30:00Z").
Any issues here will result in an exception being thrown.
SEE ALSO
Business::Payr::PaymentSession
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