Business::Stripe::Subscription - Simple way to implement subscriptions using Stripe hosted checkout
Version 1.0
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;
A simple to use interface to Stripe subscriptions using the hosted checkout.
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
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.
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.
api_secret
success-url
cancel-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.
cancel-url
currency - The currency to use for the transaction. The default is British Pounds Stirling (GBP).
currency
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.
trial_days
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; }
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.
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.
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.
name
email - The customer's email address.
email
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.
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.
customer_id - The customer ID obtained from the customer method.
customer_id
price_plan_id - The ID of the price plan in Stripe.
price_plan_id
The price plan ID can be obtained from the Stripe Dashboard or by using the Stripe API to retrieve the available price plans.
my $response = $stripe->get_subscription($subscription_id);
Retrieves the subscription object from Stripe.
subscription_id - The subscription to retrieve
subscription_id
Returns an HTTP::Tiny response representing the Stripe subscription - see https://perldoc.perl.org/HTTP::Tiny#request
$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 restore
state - (optional) if 0 the subscription is restored, otherwise it is cancelled
state
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.
$stripe->cancel_now($subscription_id);
Cancels a subscription immediately
subscription_id - the subscription to cancel
$stripe->update($subscription_id, 'price_00000000000000000000000');
Updates a subscription to a new price plan.
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.
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.
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.
$stripe->set_card($customer_id, $subscription_id, $session_id);
Set default card for future subscription payments.
customer_id - the customer to set the card for
subscription_id - the subscription to update
session_id - the session ID obtained from new_card
session_id
Stripe Subscriptions API
Business::Stripe::Webhook
Business::Stripe::WebCheckout
Ian Boddison <ian at boddison.com>
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.
bug-business-stripe-subscription at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Business::Stripe::Subscription
You 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
https://metacpan.org/release/Business::Stripe::Subscription
Thanks to the help and support provided by members of Perl Monks https://perlmonks.org/.
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.
To install Business::Stripe::Subscription, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Business::Stripe::Subscription
CPAN shell
perl -MCPAN -e shell install Business::Stripe::Subscription
For more information on module installation, please visit the detailed CPAN module installation guide.