The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Business-Stripe-WebCheckout-1.3
River stage zero No dependents
2 ++
/ Business::Stripe::WebCheckout

NAME

Business::Stripe::WebCheckout - Simple way to implement payments using Stripe hosted checkout

SYNOPSIS

  use Business::Stripe::WebCheckout;

  my $stripe = Business::Stripe::WebCheckout->new(
      'api-secret'  => 'sk_test_00000000000000000000000000',
  );

  # Note price is in lowest currency unit (i.e pence or cents not pounds or dollars)
  $stripe->add_product(
      'id'      => 1,
      'name'    => 'My product',
      'qty'     => 4,
      'price'   => 250,
  );

  foreach my $id($stripe->list_products) {
      print "$id is " . $stripe->get_product($id)->{'name'} . "\n";
  }

  $stripe->checkout(
      'api-public'  => 'pk_test_00000000000000000000000000',
  );

DESCRIPTION

A simple to use interface to the Stripe payment gateway utilising the Stripe hosted checkout. The only dependencies are the core modules HTTP::Tiny and JSON::PP.

Business::Stripe::WebCheckout has a Trolley into which products are loaded. Once the Trolley is full of the product(s) to be paid for, this is passed to the Stripe hosted checkout either using Javascript provided by Stripe (see https://stripe.com/docs/payments/accept-a-payment?integration=checkout), Javascript provided in this document or the checkout utility method that allows a server side script to send the user to Stripe invisibly.

At present Business::Stripe::WebCheckout only handles simple, one-off payments. Manipulation of customers, handling subscriptions and user hosted checkout is not supported. However, this implementation makes payment for a single item or group of items simple to implement.

In August 2022 Stripe released a new version of their API. Currently this module uses the previous version 2020-08-27. The module overrides the setting in the Stripe dashboard so this requires no user input. For the simple cases this module is intended for, this presents no problems and it is only pointed out to try and prevent confusion for anyone trying to cross reference the module calls with the Stripe API documentation. The latest version of the API introduces some additional functionality which may be incorporated into this module in the future.

Keys

Stripe provides four API Keys. A Secret and a Publishable (called Public within Business::Stripe::WebCheckout) for both testing and for live transactions. When calling the new method it is necessary to provide the Secret Key. Before calling the checkout method to redirect the user to the Stripe hosted checkout, the Public Key is also required so this is usually provided to the new method.

See https://stripe.com/docs/keys

Workflow

The basic workflow for Business::Stripe::WebCheckout is to initially create an instance of the module with at minimum the Secret Key. If using a currency other than GBP this should also be set at this time.

  my $stripe = Business::Stripe::WebCheckout->new(
      'api-public' => 'pk_test_00000000000000000000000000',
      'api-secret' => 'sk_test_00000000000000000000000000',
      'currency'   => 'USD',
  );

Next, products are assembled in the Trolley. There are methods to add, update, remove and list the products in the Trolley.

  $stripe->add_product(
      'id'      => 1,
      'name'    => 'My product',
      'qty'     => 4,
      'price'   => 250,
  );
  my @products = $stripe->list_products;

Once the Trolley contains all the products, the user is redirected to the Stripe hosted checkout where they pay for the Trolley. Once this happens, Stripe returns to your site using one of the URLs provided depending on whether the payment was successful or not. Where no return URLs are provided, the script URL is used although in practice this is not usually sufficient and return URLs will be needed.

  $stripe->checkout;

Examples of other ways of redirecting the user to the Stripe hosted checkout and listed in the Examples section.

METHODS

new

  Business::Stripe::WebCheckout->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-public - The Public Key. This would normally be provided to the new method but can be left until sending the user to the Stripe hosted checkout.

  • success-url

  • cancel-url - The callback URL that Stripe returns to once the payment transaction 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).

  • reference - The reference to use for the transaction

    Defaults to "Business::Stripe::WebCheckout" as this is required by Stripe.

  • email - If provided, this pre-fills the user's email address in the Stripe hosted checkout. If provided, this is then non editable during checkout.

  • getShipping - If provided, this forces Stripe to capture the customer's shipping address during checkout. This should be the country code for the customer's shipping location (see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).

Returns a Business::Stripe::WebCheckout even if creation has failed. The success method should always be checked to ensure success.

  my $stripe = Business::Stripe::WebCheckout->new(
      'api-secret' => 'sk_test_00000000000000000000000000',
      'api-public' => 'pk_test_00000000000000000000000000',
  );
  if ($stripe->success) {
      # ...carry on...
  } else {
      # ...deal with error...
      print $stripe->error;
  }

success

Returns true if the last method call was successful

error

Returns the last error message or an empty string if success returned true

Trolley Methods

add_product

Adds a product to the Trolley. Or update the product if an existing id is provided.

A product consists of the following hash entries

  • id - required A unique ID for the product. This is not passed to Stripe and is only used by Business::Stripe::WebCheckout to identify current products.

    If add_product is called with an existing ID, that product is updated.

  • name - required The name of the product as it will be passed to Stripe.

  • description - optional A one line decsription of the product as it will be passed to Stripe. This is typically used to specify options such as colour.

  • qty - required The number of the product to add to the Trolly.

  • price - required The price of the product in the lowest currency unit. For example - £2.50 would be 250 as it is 250 pence; $10 would be 1000 as it is 1000 cents.

    Note that special rules apply to Hungarian Forint (HUF) and Ugandan Shilling (UGX) - see https://stripe.com/docs/currencies

On success, returns the number of products in the Trolley

delete_product(id)

Delete the product with the specified id

On success, returns the number of products in the Trolley

list_products

Returns an array contining the IDs of the products in the Trolley

get_product(id)

On success, returns a hash with the product details. Each key of the hash corresponds to items listed for add_product

Checkout Methods

parameters

The get_intent, get_intent_id, get_ids and checkout methods all take the following optional parameters. See new for their descriptions.

  • reference

  • email

get_intent

This method will not normally need calling.

Returns the full session intent from Stripe if successful or the Stripe error otherwise.

get_intent_id

Returns the intend_id that needs passing to the Stripe hosted checkout if successful or the Stripe error otherwise.

get_ids

In addition to the parameters listed above, this method also accepts the following optional parameters

  • public-api - See new

  • format - The format of the returned information. Current options are JSON or text. The default is text.

Provides the Public Key and Intent Session ID as these are the two pieces of information required by the Javascript provided by Stripe and the Javacsript provided here. If text output is used (the default) the Public Key and Intent Session ID are provided as a colon separated string.

checkout

A simple implementation of redirecting the user to the Stripe hosted checkout.

Calling this method provides a fully formed HTML document including the Content-Type header that can be sent to the users browser. The HTML document contains all the Javascript required to sent the user to the Stripe hosted checkout transparently. Unless you are building a checkout with entirely AJAX calls, you will almost certainly want to use this method.

EXAMPLES

1 - Using the Stripe provided Javascript

See https://stripe.com/docs/payments/accept-a-payment?integration=checkout

Javascript

  <html>
    <head>
      <title>Buy cool new product</title>
      <script src="https://js.stripe.com/v3/"></script>
    </head>
    <body>
      <button id="checkout-button">Checkout</button>

      <script type="text/javascript">
        // Create an instance of the Stripe object with your publishable API key
        var stripe = Stripe('pk_test_00000000000000000000000000');
        var checkoutButton = document.getElementById('checkout-button');

        checkoutButton.addEventListener('click', function() {
          // Create a new Checkout Session using the server-side endpoint you
          // created in step 3.
          fetch('https://example.com/cgi-bin/trolley.pl', {
            method: 'POST',
          })
          .then(function(response) {
            return response.json();
          })
          .then(function(session) {
            return stripe.redirectToCheckout({ sessionId: session.id });
          })
          .then(function(result) {
            // If `redirectToCheckout` fails due to a browser or network
            // error, you should display the localized error message to your
            // customer using `error.message`.
            if (result.error) {
              alert(result.error.message);
            }
          })
          .catch(function(error) {
            console.error('Error:', error);
          });
        });
      </script>
    </body>
  </html>

Perl trolley.pl

  use Business::Stripe::WebCheckout;
  use strict;

  my $stripe = Business::Stripe::WebCheckout->new(
    'api-public'    => 'pk_test_00000000000000000000000000',
    'api-secret'    => 'sk_test_00000000000000000000000000',
    'success-url'   => 'https://www.example.com/yippee.html',
    'cancel-url'    => 'https://www.example.com/ohdear.html',
    'reference'     => 'My Payment',
  );

  $stripe->add_product(
    'id'          => 'test',
    'name'        => 'Expensive Thingy',
    'description' => 'Special edition version',
    'qty'         => 1,
    'price'       => 50000,
  );

  print "Content-Type: text/json\n\n";
  print $stripe->get_intent;

2 - Simpler Javascript using XHR without exposing Public Key

Javascript

  <html>
  <head>
  <script src="https://js.stripe.com/v3/"></script>
  <script>
  var xhr=new XMLHttpRequest();
  function buyNow() {
      xhr.open("POST", "https://www.example.com/cgi-bin/trolley.pl", true);
      xhr.onreadystatechange=function() {
      if (xhr.readyState == 4 && xhr.status == 200) {
                  var keys = xhr.response.split(':');
                  var stripe = Stripe(keys[0]);
                  var result = stripe.redirectToCheckout({ sessionId: keys[1] });
                  if (result.error) {
                          alert(result.error.message);
                  }
          }
      }
      xhr.send();
  }
  </script>
  </head>
  <body>
  <input type="button" value="Buy Now!" onClick="buyNow();">
  </body>
  </html>

Perl - trolley.pl

  use Business::Stripe::WebCheckout;
  use strict;

  my $stripe = Business::Stripe::WebCheckout->new(
    'api-public'    => 'pk_test_00000000000000000000000000',
    'api-secret'    => 'sk_test_00000000000000000000000000',
    'success-url'   => 'https://www.example.com/yippee.html',
    'cancel-url'    => 'https://www.example.com/ohdear.html',
    'reference'     => 'My Payment',
  );

  $stripe->add_product(
    'id'          => 'test',
    'name'        => 'Expensive Thingy',
    'description' => 'Special edition version',
    'qty'         => 1,
    'price'       => 50000,
  );

  print "Content-Type: text/text\n\n";
  print $stripe->get_ids;

3 - Simpest method (no Javascript required)

HTML

  <html>
  <head>
  <title>Simple Checkout</title>
  </head>
  <body>
  <form method="post" action="https://www.example.com/cgi-bin/trolley.pl">
  <input type="submit" value="Buy Now!">
  </form>
  </body>
  </html>

Perl - trolley.pl

  use Business::Stripe::WebCheckout;
  use strict;

  my $stripe = Business::Stripe::WebCheckout->new(
    'api-public'    => 'pk_test_00000000000000000000000000',
    'api-secret'    => 'sk_test_00000000000000000000000000',
    'success-url'   => 'https://www.example.com/yippee.html',
    'cancel-url'    => 'https://www.example.com/ohdear.html',
    'reference'     => 'My Payment',
  );

  $stripe->add_product(
    'id'          => 'test',
    'name'        => 'Expensive Thingy',
    'description' => 'Special edition version',
    'qty'         => 1,
    'price'       => 50000,
  );

  if ($stripe->success) {
     print $stripe->checkout;
  } else {
     # handle errors...
  }

This last example prints out a fully formed HTML document to the browser containing only the head section. The HTML contains the Javascript necessary to pass the use to the Stripe hosted checkout. The HTML is complete with Content-Type header. If other headers are required, such as Set-Cookie headers, they can be included immediately before calling checkout.

  print "Set-cookie: MyCookie=$order_number; path=/\n";
  $stripe->checkout;

SEE ALSO

Net::Stripe, Net::Stripe::Simple, Business::Stripe

AUTHOR

  • Ian Boddison <ian@boddison.com>

BUGS

Please report any bugs or feature requests to bug-business-stripe-webcheckout at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Business-Stripe-WebCheckout. 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::WebCheckout

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to the help and support provided by members of Perl Monks https://perlmonks.org/

LICENSE AND COPYRIGHT

This software is copyright (c) 2021 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.