1Stripe(3) User Contributed Perl Documentation Stripe(3)
2
6 Business::Stripe - Interface for Stripe payment system.
7
9 my $stripe = Business::Stripe->new(
10 -api_key => 'your-api-key-here',
11 );
12 ## 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 say $stripe->error->{message};
21
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 General Methods
28 new (%options)
29 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 Other (optional) arguments are:
35 "-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 "-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 my $stripe = Business::Stripe->new(
66 -api_key => 'xxxxxxxx',
67 -ua => $ua,
68 );
69 "-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 api ($method, $path, %params)
77 Generic function that sends requests to Stripe. Check the Stripe API
79 Reference <https://stripe.com/docs/api> for specific calls.
80 The first argument is the HTTP method: "post", "get" or "delete".
82 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 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 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 In case of failures, it returns false (0) and you should then check
96 $stripe->error() for the appropriate data structure.
97 Examples:
99 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 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 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 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 cancel a subscription immediately
134 $stripe->api('delete', "subscriptions/" . $subscription->{id})
135 or die "error canceling subscription: " . $stripe->error->{message};
136 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 error
142 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 say $stripe->error->{message};
148 Most error messages include "message", "code", "type" and "doc_url".
150 success
152 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 say $stripe->success->{data}->[0]->{description};
159 Charges
161 Set of methods that handle credit/debit card such as charging a card,
162 refund, retrieve specific charge and list charges.
163 charges_create (%params)
165 my $success = $stripe->charges_create(
167 amount => 100, # <-- amount in cents
168 source => 'tok_Wzm6ewTBrkVvC3',
169 description => 'customer@example.com'
170 );
171 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 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 Please see Stripe's API Documentation for which parameters are accepted
180 by your current API version.
181 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 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 charges_retrieve ($id)
193 my $charge_data = $stripe->charges_retrieve('ch_uxLBSIZB8azrSr')
195 and $stripe->success;
196 Takes the charge "id" value and yields data about the charge, available
198 on $stripe->success .
199 This is exactly the same as "$stripe->api('get',
201 "charges/$charge_id")".
202 charges_refund ($id, [$amount])
204 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 ### refunds full amount
210 $stripe->charges_refund('ch_uxLBSIZB8azrSr')
211 or die $stripe->error->{message};
212 ### refunds $5 over a bigger charge
214 $stripe->charges_refund('ch_uxLBSIZB8azrSr', 500)
215 or die $stripe->error->{message};
216 charges_list (%params)
218 List all the charges, with pagination.
220 ### lists next 5 charges
222 my $charges = $stripe->charges_list(limit => 5)
223 ? $stripe->success : die $stripe->error->{message};
224 foreach my $charge (@{$charges->{data}}) {
226 say $charge->{amount} . $charge->{currency};
227 }
228 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 Pass on the customer's ID to only get charges made to that customer:
235 $stripe->charges_list(customer => 'cus_gpj0mzwbQKBI7c')
237 or die "error fetching customer charges: " . $stripe->error;
238 my $charges = $stripe->success;
240 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 customers_create (%params)
247 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 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 ### charges the customer $5
261 $stripe->charges_create(
262 customer => $customer_id,
263 amount => 500,
264 description => 'userid-123456 paid $5'
265 );
266 Returns the customer's ID if successful. As usual, you may check the
268 full JSON object returned on $stripe->success .
269 customers_retrieve ($id)
271 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 my $customer = $stripe->customers_retrieve('cus_gpj0mzwbQKBI7c')
276 and $stripe->success;
277 die $stripe->error unless $customer;
278 customers_update ($id, [%params])
280 Updates customer's information.
282 $stripe->customers_update('cus_gpj0mzwbQKBI7c',
284 email => 'newemail@example.com',
285 );
286 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 customers_delete ($id)
293 Deletes the customer.
295 $stripe->customers_delete('cus_gpj0mzwbQKBI7c')
297 or die $stripe->error;
298 customers_list (%params)
300 List all customers.
302 $stripe->customers_list(limit => 20);
304 customers_subscribe ($id, %params)
306 Subscribes a customer to a specified plan:
308 $stripe->customers_subscribe('cus_YrUZejr9oojQjs',
310 'items[0][plan]' => $some_plan_id,
311 'prorate' => 'false'
312 );
313 Assuming $some_plan_id is the id of a plan already created in your
315 Stripe account.
316 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 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 $stripe->api('post', 'subscriptions',
324 'customer' => $customer_id,
325 'items[0][plan]' => $plan_id_to_add,
326 );
327 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 $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 customers_unsubscribe ($id)
340 Immediately unsubscribe the customer from all currently subscribed
342 plans. Useful for terminating accounts (or paid subscriptions).
343 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 $stripe->customers_unsubscribe('cus_YrUZejr9oojQjs')
352 or die "error unsubscribing customer: " . $stripe->error->{message};
353
355 <https://github.com/aquaron/Business-Stripe>
356
358 Stripe.js Documentation <https://stripe.com/docs/stripe.js>.
359 Stripe Full API Reference <https://stripe.com/docs/api>.
361 Full featured implementation by Luke Closs Net::Stripe.
363
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 mv Stripe.pm BusinessStripe.pm
370 Edit "BusinessStripe.pm" and remove the "::" between the package name
372 on the first line to:
373 package BusinessStripe;
375 Include the file in your program:
377 use BusinessStripe;
379 my $stripe = BusinessStripe->new(
380 -api_key => 'c6EiNIusHip8x5hkdIjtur7KNUA3TTpE',
381 -env_proxy => 1,
382 );
383 $stripe->charges_list;
384
386 Paul Pham (@phamnp)
387
389 Copyright (C) 2012-2019 Aquaron. All Rights Reserved.
390 This program and library is free software; you can redistribute it
392 and/or modify it under the same terms as Perl itself.
393perl v5.36.0 2023-01-20 Stripe(3)