NAME
Business::Stripe::Subscription - Simple way to implement subscriptions using Stripe hosted checkout
Version 1.0
SYNOPSIS
use Business::Stripe::Subscription;
my $stripe = Business::Stripe::Subscription->new(
'api_secret' => 'sk_test_00000000000000000000000000',
'success_url' => 'https://www.example.com/yippee.html',
'cancel_url' => 'https://www.example.com/cancelled.html',
);
my $cus_vars = {
'name' => 'Andrew Test',
'email' => 'atest@example.com',
};
my $customer_id = $stripe->customer($cus_vars);
$checkout_url;
if ($stripe->success) {
$checkout = $stripe->subscription($customer_id, 'price_00000000000000000000000');
} else {
die $stripe->error;
}
print "Location: $checkout_url\n\n";
exit;
DESCRIPTION
A simple to use interface to Stripe subscriptions using the hosted checkout.
Keys
Stripe provides four API Keys. A Secret and Publishable Key for both testing and for live transactions. When calling the new method it is necessary to provide the Secret Key. The Publishable Key is not used by this module.
See https://stripe.com/docs/keys
Workflow
The basic workflow for Business::Stripe::Subscription is to initially create an instance of the module with the Secret Key. If using a currency other than GBP this should also be set at this time.
my $stripe = Business::Stripe::Subscription->new(
'api-secret' => 'sk_test_00000000000000000000000000',
'currency' => 'USD',
);Next, a Customer is created unless this has been done previously.
my $customer = $stripe->customer(
'name' => 'Andrew Test',
'email' => 'atest@example.com,
);To create the subscription, the customer and Price Plan (from Stripe) are used to get a URL for the Stripe hosted checkout.
my $url = $stripe->subscription($customer, 'price_00000000000000000000000');Sending the user to the URL will take them to the Stripe hosted checkout. From there, they will return to the success_url or cancel_url depending on the outcome of the transaction.
METHODS
new
Business::Stripe::Subscription->new('api-secret' => 'sk_test_00000000000000000000000000');The constructor method. The Secret Key is required.
The following parameters may be provided:
api_secret- required The Secret Key.success-urlcancel-url- The callback URL that Stripe returns to once the payment subscription has completed either successfully or otherwise. If these are not explicitly included, the current script URL is used. Normally these need setting but can be omitted for testing or if the Stripe payment dashboard is being relied on to confirm successful payments.currency- The currency to use for the transaction. The default is British Pounds Stirling (GBP).This should be a 3 letter currency code supported by Stripe (see https://stripe.com/docs/currencies).
trial_days- the number of days trial before payments are started. Stripe will still confirm card details at the start of the trial but will not charge the card until the trial period has finished.
Returns a Business::Stripe::Subscription even if creation has failed. The success method should always be checked to ensure success.
my $stripe = Business::Stripe::Subscription->new(
'api-secret' => 'sk_test_00000000000000000000000000',
);
if ($stripe->success) {
# ...carry on...
} else {
# ...deal with error...
print $stripe->error;
}success
success
if ($stripe->success) {
# Payment was successful
}This method is used to check if the last method call was successful. It returns a boolean value indicating whether the method call was successful or not.
error
die $stripe->error;This method is used to retrieve the error message if the last method call was not successful. It returns the error message as a string.
customer
my $customer_id = $stripe->customer(
'name' => 'Andrew Test',
'email' => 'atest@example.com',
);This method is used to create or retrieve a customer in Stripe. It takes a hash of customer information as input and returns the customer ID.
The following parameters are supported:
name- The customer's full name.email- The customer's email address.
If a customer with the same email address already exists in Stripe, the existing customer ID will be returned. Otherwise, a new customer will be created and the customer ID will be returned.
subscription
my $checkout_url = $stripe->subscription($customer_id, 'price_00000000000000000000000');This method is used to create a subscription for a customer in Stripe. It takes the customer ID and the price plan ID as input and returns the URL for the Stripe hosted checkout.
The following parameters are supported:
customer_id- The customer ID obtained from the customer method.price_plan_id- The ID of the price plan in Stripe.
The price plan ID can be obtained from the Stripe Dashboard or by using the Stripe API to retrieve the available price plans.
get_subscription
my $response = $stripe->get_subscription($subscription_id);Retrieves the subscription object from Stripe.
subscription_id- The subscription to retrieve
Returns an HTTP::Tiny response representing the Stripe subscription - see https://perldoc.perl.org/HTTP::Tiny#request
cancel
$stripe->cancel($subscription_id, $state);Restores the subscription or cancels it t the end of the current billing period.
subscription_id- the subscription to cancel or restorestate- (optional) if 0 the subscription is restored, otherwise it is cancelled
Cancels the subscription at the end of the current billing period. If state is supplied and set to 0, the subscription is restored provided it has not already reached the end of the billing period.
cancel_now
$stripe->cancel_now($subscription_id);Cancels a subscription immediately
subscription_id- the subscription to cancel
update
$stripe->update($subscription_id, 'price_00000000000000000000000');Updates a subscription to a new price plan.
The following parameters are supported:
subscription_id- The Stripe Subscription ID..price_plan_id- The ID of the price plan to change to.
Note that if the subscription has been set to cancel, it will be restored if the subscription plan is succesfully updated.
new_card
my $url = $stripe->new_card($customer_id, $sunscription_id);Get the URL to send a customer to a Stripe hosted checkout to add a new card to their account.
The following parameters are supported:
customer_id- The customer ID obtained from the customer method.subscription_id- The subscription to add the new card to.
Returns a URL string to send the customer to so they can add a new card to their account. Note that this does not set the new card as the one to be charged for future subscription payments. See set_card.
set_card
$stripe->set_card($customer_id, $subscription_id, $session_id);Set default card for future subscription payments.
customer_id- the customer to set the card forsubscription_id- the subscription to updatesession_id- the session ID obtained from new_card
SEE ALSO
AUTHOR
Ian Boddison <ian at boddison.com>
BUGS
Please report any bugs or feature requests to bug-business-stripe-subscription at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=bug-business-stripe-subscription. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Business::Stripe::SubscriptionYou can also look for information at:
RT: CPAN's request tracker (report bugs here)
https://rt.cpan.org/NoAuth/Bugs.html?Dist=Business-Stripe-Subscription
Search CPAN
ACKNOWLEDGEMENTS
Thanks to the help and support provided by members of Perl Monks https://perlmonks.org/.
COPYRIGHT AND LICENSE
This software is copyright (c) 2023 by Ian Boddison.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.