1Stripe(3)             User Contributed Perl Documentation            Stripe(3)
2
3
4

NAME

6       Business::Stripe - Interface for Stripe payment system.
7

SYNOPSIS

9        my $stripe = Business::Stripe->new(
10           -api_key => 'your-api-key-here',
11        );
12
13        ## get the payment token from Stripe.js, then:
14        $stripe->charges_create(
15            amount         => 400,
16            source         => 'tok_5EuIyKyCTc0f2V',
17            description    => 'Ice cream'
18        ) and return $stripe->success;
19
20        say $stripe->error->{message};
21

DESCRIPTION

23       This module provides common bindings for the Stripe payment system.
24       Any API calls that do not have bindings can be accessed through the
25       generic "api" method.
26
27   General Methods
28       new (%options)
29
30       Creates a new Business::Stripe object for you to use. The only required
31       argument is "-api_key", which was given to you as part of your Stripe
32       account to access the API.
33
34       Other (optional) arguments are:
35
36       "-version" Sets a Stripe API version to use, overriding your account's
37       default. You can use this to test if new versions of the API work with
38       your code. To support marketplaces, for instance, you should use at
39       least '2014-11-05'.
40       "-ua_args" Hashref of options that will be passed directly as arguments
41       to LWP::UserAgent. Example:
42               my $stripe = Business::Stripe->new(
43                   -api_key => 'xxxxxxxxx',
44                   -ua_args => {
45                       timeout   => 10,
46                       env_proxy => 1,
47                       agent     => 'myApp',
48                       ssl_opts  => { verify_hostname => 0 },
49                   },
50               );
51
52       "-ua" Completely overrides the default user agent object
53       (LWP::UserAgent). Note that your object must accept HTTPS, and provide
54       a "request()" method accepting HTTP::Request objects and returning
55       HTTP::Response-compatible objects. You can use this to have a common
56       user agent make all requests in your code. The example above works
57       exactly like:
58               my $ua = LWP::UserAgent->new(
59                   timeout   => 10,
60                   env_proxy => 1,
61                   agent     => 'myApp',
62                   ssl_opts  => { verify_hostname => 0 },
63               );
64
65               my $stripe = Business::Stripe->new(
66                   -api_key => 'xxxxxxxx',
67                   -ua      => $ua,
68               );
69
70       "-url" Overrides the default API endpoint
71       ("https://api.stripe.com/v1/")
72       "-stripe_account" If you use the OAauth authentication flow for managed
73       accounts <https://stripe.com/docs/connect/authentication> You can use
74       this argument to make operations on behalf of a managed account.
75
76       api ($method, $path, %params)
77
78       Generic function that sends requests to Stripe.  Check the Stripe API
79       Reference <https://stripe.com/docs/api> for specific calls.
80
81       The first argument is the HTTP method: "post", "get" or "delete".
82
83       The second is the target path, like "tokens", "plans", "customers" or
84       even complex paths like "customers/$id/subscriptions". Check the Stripe
85       API Reference for a list of all available paths.
86
87       Use the optional third argument to send a hash of data with your API
88       call.  This is usually required on all "post" calls to the API.
89
90       On success, it returns a true value. If the returned data structure
91       contains an "id" field, this is the value returned. Otherwise, "1" is
92       returned and you should check $stripe->success()  for the actual data
93       structure.
94
95       In case of failures, it returns false (0) and you should then check
96       $stripe->error()  for the appropriate data structure.
97
98       Examples:
99
100       get a credit card source token on the server side (without using
101       Stripe.js)
102               my $token_id = $stripe->api('post', 'tokens',
103                   'card[number]'    => '4242424242424242',
104                   'card[exp_month]' => 12,
105                   'card[exp_year]'  => 2022,
106                   'card[cvc]'       => 123
107               ) or die $stripe->error->{message};
108
109       create a new customer (with the $token_id from above)
110               my $customer = $stripe->api('post', 'customers',
111                   email       => 'myuser@example.com',
112                   name        => 'Jane S. Customer',
113                   description => 'Displayed alongside the customer on your dashboard',
114                   source      => $token_id,
115               ) and $stripe->success;
116               die $stripe->error unless $customer;
117
118       create a new plan to subscribe your customers
119               my $plan_id = $stripe->api('post', 'plans',
120                   'amount'        => 999,       # *IN CENTS* (999 = 9.99). Use 0 for a free plan!
121                   'id'            => 'my-plan', # Optional. Must be unique in your account
122                   'currency'      => 'usd',     # See https://stripe.com/docs/currencies
123                   'interval'      => 'month',   # Also: 'day', 'week', 'year'
124                   'product[name]' => 'My Plan',
125               ) or die $stripe->error->{message};
126
127       subscribe the customer to a plan (using examples above)
128               my $subscription = $stripe->api('post', 'subscriptions',
129                   'customer'       => $customer->{id},
130                   'items[0][plan]' => $plan_id,
131               ) ? $stripe->success : $stripe_error;
132
133       cancel a subscription immediately
134            $stripe->api('delete', "subscriptions/" . $subscription->{id})
135               or die "error canceling subscription: " . $stripe->error->{message};
136
137       As you can see, all actions can be performed by using only this method.
138       The other methods provided by this class are just helper wrappers
139       around this, for frequently made calls.
140
141       error
142
143       All API and helper methods return 0 when they encounter error
144       conditions.  The JSON object returned by Stripe can be retrieved via
145       this method.
146
147        say $stripe->error->{message};
148
149       Most error messages include "message", "code", "type" and "doc_url".
150
151       success
152
153       All API and helper methods return either 1 or the object's ID on
154       success.  Use this method to get access to the complete JSON object
155       returned on the last call made by your object. See Stripe's API
156       Documentation for details on what is returned on each call.
157
158        say $stripe->success->{data}->[0]->{description};
159
160   Charges
161       Set of methods that handle credit/debit card such as charging a card,
162       refund, retrieve specific charge and list charges.
163
164       charges_create (%params)
165
166           my $success = $stripe->charges_create(
167               amount      => 100,  # <-- amount in cents
168               source      => 'tok_Wzm6ewTBrkVvC3',
169               description => 'customer@example.com'
170           );
171
172       Charges a credit card or other payment sources. This is exactly the
173       same as "$stripe->api('post', 'charges', %params)", except that it
174       defaults to 'usd' if you don't provide a currency.
175
176       It returns the "id" of the charge on success, or 0 on error.  You may
177       also check $stripe->success  or $stripe->error  for the complete JSON.
178
179       Please see Stripe's API Documentation for which parameters are accepted
180       by your current API version.
181
182       Note: The "amount" field is in the currency's smallest unit.  For
183       currencies that allow cents (like USD), an amount of 100 means $1.00,
184       1000 mean $10.00 and so on. For zero-decimal currencies (like JPY) you
185       don't have to multiply, as an amount of 100 mean ¥100.
186
187       Note: Older (2015-ish) versions of Stripe's API support the "card"
188       parameter containing the source token from Stripe.js. This has since
189       been deprecated in favour of the "source" parameter, shown in the
190       example above.
191
192       charges_retrieve ($id)
193
194           my $charge_data = $stripe->charges_retrieve('ch_uxLBSIZB8azrSr')
195               and $stripe->success;
196
197       Takes the charge "id" value and yields data about the charge, available
198       on $stripe->success .
199
200       This is exactly the same as "$stripe->api('get',
201       "charges/$charge_id")".
202
203       charges_refund ($id, [$amount])
204
205       Refunds a specific "amount" (or if omitted, issues a full refund) to
206       the charge "id". Remember: the "amount" parameter is in cents whenever
207       the currency supports cents.
208
209        ### refunds full amount
210        $stripe->charges_refund('ch_uxLBSIZB8azrSr')
211           or die $stripe->error->{message};
212
213        ### refunds $5 over a bigger charge
214        $stripe->charges_refund('ch_uxLBSIZB8azrSr', 500)
215           or die $stripe->error->{message};
216
217       charges_list (%params)
218
219       List all the charges, with pagination.
220
221           ### lists next 5 charges
222           my $charges = $stripe->charges_list(limit => 5)
223               ? $stripe->success : die $stripe->error->{message};
224
225           foreach my $charge (@{$charges->{data}}) {
226               say $charge->{amount} . $charge->{currency};
227           }
228
229           if ($charges->{has_more}) {
230               say "there are more charges to show if you raise the limit"
231                 . " or change the 'starting_after' argument.";
232           }
233
234       Pass on the customer's ID to only get charges made to that customer:
235
236           $stripe->charges_list(customer => 'cus_gpj0mzwbQKBI7c')
237               or die "error fetching customer charges: " . $stripe->error;
238
239           my $charges = $stripe->success;
240
241   Customers
242       Some operations require you create a customer. Also, by creating a
243       customer, you don't have to ask for credit card information on every
244       charge.
245
246       customers_create (%params)
247
248       Creates a new customer according to the credit card information or
249       token given.  Use this method to create a customer-ID for the given
250       "card" (token when used in conjunction with Stripe.js).  The customer-
251       ID can be passed to "charges_create"'s "customer" parameter instead of
252       "source" so that you don't have to ask for credit card info again.
253
254           my $customer_id = $stripe->customers_create(
255               source      => 'tok_Wzm6ewTBrkVvC3',
256               email       => 'customer@example.com',
257               description => 'userid-123456'
258           ) or die $stripe->error;
259
260           ### charges the customer $5
261           $stripe->charges_create(
262               customer    => $customer_id,
263               amount      => 500,
264               description => 'userid-123456 paid $5'
265           );
266
267       Returns the customer's ID if successful. As usual, you may check the
268       full JSON object returned on $stripe->success .
269
270       customers_retrieve ($id)
271
272       Gets the customer's object. Returns the id (which you already have) so
273       make sure to fetch the actual object using $stripe->success .
274
275           my $customer = $stripe->customers_retrieve('cus_gpj0mzwbQKBI7c')
276               and $stripe->success;
277           die $stripe->error unless $customer;
278
279       customers_update ($id, [%params])
280
281       Updates customer's information.
282
283           $stripe->customers_update('cus_gpj0mzwbQKBI7c',
284               email => 'newemail@example.com',
285           );
286
287       Note: If you update the "source" of a customer, Stripe will create a
288       source object with the new value, make it the default source, and
289       delete the old customer default if it exists. If you just want to add
290       extra sources for that customer, refer to Stripe's card creation API .
291
292       customers_delete ($id)
293
294       Deletes the customer.
295
296        $stripe->customers_delete('cus_gpj0mzwbQKBI7c')
297           or die $stripe->error;
298
299       customers_list (%params)
300
301       List all customers.
302
303        $stripe->customers_list(limit => 20);
304
305       customers_subscribe ($id, %params)
306
307       Subscribes a customer to a specified plan:
308
309           $stripe->customers_subscribe('cus_YrUZejr9oojQjs',
310               'items[0][plan]' => $some_plan_id,
311               'prorate'        => 'false'
312           );
313
314       Assuming $some_plan_id is the id of a plan already created in your
315       Stripe account.
316
317       Note: pass 'items[0][quantity]' with a value of 2 or more to subscribe
318       the same user to 2 or more of the same plan. It defaults to 1.
319
320       Note: This method will replace all your user's subscriptions with the
321       new data provided. To subscribe the user to more than one plan, write:
322
323           $stripe->api('post', 'subscriptions',
324               'customer'       => $customer_id,
325               'items[0][plan]' => $plan_id_to_add,
326           );
327
328       Note that this will keep all previous billing cycles (and associated
329       fees) for any other subscription already present and add a new billing
330       cycle (and fee) for this new one. If you want to subscribe the customer
331       to more than one plan with a single billing cycle, pass each plan as a
332       separate item:
333
334           $stripe->customers_subscribe('cus_YrUZejr9oojQjs',
335               'items[0][plan]' => $some_plan_id,
336               'items[1][plan]' => $other_plan_id,
337           ) or die "error subscribing customer: " . $stripe->error->{message};
338
339       customers_unsubscribe ($id)
340
341       Immediately unsubscribe the customer from all currently subscribed
342       plans.  Useful for terminating accounts (or paid subscriptions).
343
344       NOTE: As per Stripe's documentation, any pending invoice items that
345       you’ve created will still be charged for at the end of the period,
346       unless manually deleted. If you’ve set the subscription to cancel at
347       the end of the period, any pending prorations will also be left in
348       place and collected at the end of the period. But if the subscription
349       is set to cancel immediately, pending prorations will be removed.
350
351        $stripe->customers_unsubscribe('cus_YrUZejr9oojQjs')
352           or die "error unsubscribing customer: " . $stripe->error->{message};
353

REPOSITORY

355       <https://github.com/aquaron/Business-Stripe>
356

SEE ALSO

358       Stripe.js Documentation <https://stripe.com/docs/stripe.js>.
359
360       Stripe Full API Reference <https://stripe.com/docs/api>.
361
362       Full featured implementation by Luke Closs Net::Stripe.
363

SINGLE FILE INSTALLATION

365       This module is implemented as a single-file package.  If you don't want
366       to use the CPAN distribution, you can download "Stripe.pm" from the
367       root directory and renamed it to "BusinessStripe.pm":
368
369        mv Stripe.pm BusinessStripe.pm
370
371       Edit "BusinessStripe.pm" and remove the "::" between the package name
372       on the first line to:
373
374        package BusinessStripe;
375
376       Include the file in your program:
377
378        use BusinessStripe;
379        my $stripe = BusinessStripe->new(
380            -api_key => 'c6EiNIusHip8x5hkdIjtur7KNUA3TTpE',
381            -env_proxy => 1,
382        );
383        $stripe->charges_list;
384

AUTHOR

386       Paul Pham (@phamnp)
387
389       Copyright (C) 2012-2019 Aquaron. All Rights Reserved.
390
391       This program and library is free software; you can redistribute it
392       and/or modify it under the same terms as Perl itself.
393
394
395
396perl v5.32.0                      2020-07-28                         Stripe(3)
Impressum