File Coverage

blib/lib/Net/API/Stripe/Payment/Intent.pm
Criterion Covered Total %
statement 7 47 14.8
branch n/a
condition n/a
subroutine 3 43 6.9
pod 35 40 87.5
total 45 130 34.6


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## Stripe API - ~/lib/Net/API/Stripe/Payment/Intent.pm
3             ## Version v0.100.0
4             ## Copyright(c) 2019 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <@sitael.tokyo.deguest.jp>
6             ## Created 2019/11/02
7             ## Modified 2020/05/15
8             ##
9             ##----------------------------------------------------------------------------
10             ## https://stripe.com/docs/api/payment_intents
11             package Net::API::Stripe::Payment::Intent;
12             BEGIN
13             {
14 1     1   889 use strict;
  1         2  
  1         27  
15 1     1   5 use parent qw( Net::API::Stripe::Generic );
  1         1  
  1         4  
16 1     1   807 our( $VERSION ) = 'v0.100.0';
17             };
18              
19 0     0 1   sub id { shift->_set_get_scalar( 'id', @_ ); }
20              
21 0     0 1   sub object { shift->_set_get_scalar( 'object', @_ ); }
22              
23             ## 2019-02-11
24             ## Stripe: allowed_source_types has been renamed to payment_method_types.
25             ## sub allowed_source_types { shift->_set_get_scalar( 'allowed_source_types', @_ ); }
26 0     0 0   sub allowed_source_types { return( shift->payment_method_types( @_ ) ); }
27              
28             ## 2019-02-11
29             ## Stripe: authorize_with_url within has been renamed to redirect_to_url.
30 0     0 0   sub authorize_with_url { return( shift->redirect_to_url( @_ ) ); }
31              
32 0     0 1   sub amount { shift->_set_get_number( 'amount', @_ ); }
33              
34 0     0 1   sub amount_capturable { shift->_set_get_number( 'amount_capturable', @_ ); }
35              
36 0     0 1   sub amount_received { shift->_set_get_number( 'amount_received', @_ ); }
37              
38 0     0 1   sub application { shift->_set_get_scalar_or_object( 'application', 'Net::API::Stripe::Connect::Account', @_ ); }
39              
40 0     0 1   sub application_fee_amount { shift->_set_get_number( 'application_fee_amount', @_ ); }
41              
42 0     0 1   sub canceled_at { shift->_set_get_datetime( 'canceled_at', @_ ); }
43              
44 0     0 1   sub cancellation_reason { shift->_set_get_scalar( 'cancellation_reason', @_ ); }
45              
46 0     0 1   sub capture_method { shift->_set_get_scalar( 'capture_method', @_ ); }
47              
48 0     0 1   sub charges { shift->_set_get_object( 'charges', 'Net::API::Stripe::Payment::Intent::Charges', @_ ); }
49              
50 0     0 1   sub client_secret { shift->_set_get_scalar( 'client_secret', @_ ); }
51              
52 0     0 0   sub confirmation_method { shift->_set_get_scalar( 'confirmation_method', @_ ); }
53              
54 0     0 1   sub created { shift->_set_get_datetime( 'created', @_ ); }
55              
56 0     0 0   sub currency { shift->_set_get_scalar( 'currency', @_ ); }
57              
58 0     0 1   sub customer { shift->_set_get_scalar_or_object( 'customer', 'Net::API::Stripe::Customer', @_ ); }
59              
60 0     0 1   sub description { shift->_set_get_scalar( 'description', @_ ); }
61              
62 0     0 1   sub invoice { return( shift->_set_get_scalar_or_object( 'invoice', '::API::Stripe::Billing::Invoice', @_ ) ); }
63              
64 0     0 1   sub last_payment_error { shift->_set_get_object( 'last_payment_error', 'Net::API::Stripe::Error', @_ ); }
65              
66 0     0 1   sub livemode { shift->_set_get_boolean( 'livemode', @_ ); }
67              
68 0     0 1   sub metadata { shift->_set_get_hash( 'metadata', @_ ); }
69              
70 0     0 1   sub next_action { return( shift->_set_get_object( 'next_action', 'Net::API::Stripe::Payment::Intent::NextAction', @_ ) ); }
71              
72             # 2019-02-11
73             # Stripe: The next_source_action property on PaymentIntent has been renamed to next_action
74             # sub next_source_action { shift->_set_get_scalar( 'next_source_action', @_ ); }
75 0     0 0   sub next_source_action { return( shift->next_action( @_ ) ); }
76              
77 0     0 1   sub on_behalf_of { return( shift->_set_get_scalar_or_object( 'on_behalf_of', 'Net::API::Stripe::Connect::Account', @_ ) ); }
78              
79 0     0 1   sub payment_method { return( shift->_set_get_scalar( 'payment_method', @_ ) ); }
80              
81 0     0 1   sub payment_method_options { return( shift->_set_get_hash_as_object( 'payment_method_options', 'Net::API::Stripe::Payment::Method::Options', @_ ) ); }
82              
83 0     0 1   sub payment_method_types { return( shift->_set_get_array( 'payment_method_types', @_ ) ); }
84              
85 0     0 1   sub receipt_email { shift->_set_get_scalar( 'receipt_email', @_ ); }
86              
87 0     0 1   sub return_url { shift->_set_get_uri( 'return_url', @_ ); }
88              
89 0     0 1   sub review { shift->_set_get_scalar_or_object( 'review', 'Net::API::Stripe::Fraud::Review', @_ ); }
90              
91 0     0 1   sub setup_future_usage { return( shift->_set_get_scalar( 'setup_future_usage', @_ ) ); }
92              
93 0     0 1   sub shipping { shift->_set_get_object( 'shipping', 'Net::API::Stripe::Shipping', @_ ); }
94              
95 0     0 1   sub source { shift->_set_get_scalar_or_object( 'source', 'Net::API::Stripe::Payment::Source', @_ ); }
96              
97 0     0 1   sub statement_descriptor { shift->_set_get_scalar( 'statement_descriptor', @_ ); }
98              
99 0     0 1   sub statement_descriptor_suffix { return( shift->_set_get_scalar( 'statement_descriptor_suffix', @_ ) ); }
100              
101             ## requires_payment_method, requires_confirmation, requires_action, processing, requires_capture, canceled, or succeeded
102 0     0 1   sub status { return( shift->_set_get_scalar( 'status', @_ ) ); }
103              
104 0     0 1   sub transfer_data { shift->_set_get_object( 'transfer_data', 'Net::API::Stripe::Payment::Intent::TransferData', @_ ); }
105              
106 0     0 1   sub transfer_group { shift->_set_get_scalar( 'transfer_group', @_ ); }
107              
108             1;
109              
110             __END__
111              
112             =encoding utf8
113              
114             =head1 NAME
115              
116             Net::API::Stripe::Payment::Intent - A Stripe Payment Intent Object
117              
118             =head1 SYNOPSIS
119              
120             my $intent = $stripe->payment_intent({
121             amount => 2000,
122             amount_capturable => 2000,
123             application => $connect_account_object,
124             application_fee_amount => 20,
125             capture_method => 'automatic',
126             customer => $customer_object,
127             description => 'Preparation for payment',
128             invoice => $invoice_object,
129             metadata => { transaction_id => 123, customer_id => 456 },
130             receipt_email => 'john.doe@example.com',
131             });
132              
133             See documentation in L<Net::API::Stripe> for example to make api calls to Stripe to create those objects.
134              
135             =head1 VERSION
136              
137             v0.100.0
138              
139             =head1 DESCRIPTION
140              
141             A PaymentIntent guides you through the process of collecting a payment from your customer. Stripe recommends that you create exactly one PaymentIntent for each order or customer session in your system. You can reference the PaymentIntent later to see the history of payment attempts for a particular session.
142              
143             A PaymentIntent transitions through multiple statuses throughout its lifetime as it interfaces with Stripe.js to perform authentication flows and ultimately creates at most one successful charge.
144              
145             Creating payments takes five steps:
146              
147             =over 4
148              
149             =item 1. Create a PaymentIntent on the server
150              
151             =item 2. Pass the PaymentIntent’s client secret to the client
152              
153             =item 3. Collect payment method details on the client
154              
155             =item 4. Submit the payment to Stripe from the client
156              
157             =item 5. Asynchronously fulfill the customer’s order
158              
159             =back
160              
161             More info here: L<https://stripe.com/docs/payments/payment-intents/web>
162              
163             =head1 CONSTRUCTOR
164              
165             =over 4
166              
167             =item B<new>( %ARG )
168              
169             Creates a new L<Net::API::Stripe::Payment::Intent> object.
170             It may also take an hash like arguments, that also are method of the same name.
171              
172             =back
173              
174             =head1 METHODS
175              
176             =over 4
177              
178             =item B<id> retrievable with publishable key string
179              
180             Unique identifier for the object.
181              
182             =item B<object> retrievable with publishable key string, value is "payment_intent"
183              
184             String representing the object’s type. Objects of the same type share the same value.
185              
186             =item B<amount> retrievable with publishable key integer
187              
188             Amount intended to be collected by this PaymentIntent.
189              
190             =item B<amount_capturable> integer
191              
192             Amount that can be captured from this PaymentIntent.
193              
194             =item B<amount_received> integer
195              
196             Amount that was collected by this PaymentIntent.
197              
198             =item B<application> string expandable "application"
199              
200             ID of the Connect application that created the PaymentIntent.
201              
202             This is a L<Net::API::Stripe::Connect::Account> object.
203              
204             =item B<application_fee_amount> integer
205              
206             The amount of the application fee (if any) for the resulting payment. See the PaymentIntents use case for connected accounts for details.
207              
208             =item B<canceled_at> retrievable with publishable key timestamp
209              
210             Populated when status is canceled, this is the time at which the PaymentIntent was canceled. Measured in seconds since the Unix epoch.
211              
212             =item B<cancellation_reason> retrievable with publishable key string
213              
214             Reason for cancellation of this PaymentIntent, either user-provided (duplicate, fraudulent, requested_by_customer, or abandoned) or generated by Stripe internally (failed_invoice, void_invoice, or automatic).
215              
216             =item B<capture_method> retrievable with publishable key string
217              
218             One of automatic (default) or manual.
219              
220             When the capture method is automatic, Stripe automatically captures funds when the customer authorizes the payment.
221              
222             Change capture_method to manual if you wish to separate authorization and capture for payment methods that support this.
223              
224             =item B<charges> list
225              
226             Charges that were created by this PaymentIntent, if any.
227              
228             This is a L<Net::API::Stripe::Payment::Intent::Charges> object.
229              
230             =item B<client_secret> retrievable with publishable key string
231              
232             The client secret of this PaymentIntent. Used for client-side retrieval using a publishable key.
233              
234             The client secret can be used to complete a payment from your frontend. It should not be stored, logged, embedded in URLs, or exposed to anyone other than the customer. Make sure that you have TLS enabled on any page that includes the client secret.
235              
236             Please refer to L<Stripe quickstart guide|https://stripe.com/docs/payments/accept-a-payment> to learn about how client_secret should be handled.
237             confirmation_method retrievable with publishable key string
238              
239             One of automatic (default) or manual.
240              
241             When the confirmation method is automatic, a PaymentIntent can be confirmed using a publishable key. After
242             next_actions are handled, no additional confirmation is required to complete the payment.
243              
244             When the confirmation method is manual, all payment attempts must be made using a secret key. The PaymentIntent returns to the requires_confirmation state after handling next_actions, and requires your server to initiate each payment attempt with an explicit confirmation.
245              
246             Learn more about the different confirmation flows.
247              
248             =item B<created> retrievable with publishable key timestamp
249              
250             Time at which the object was created. Measured in seconds since the Unix epoch.
251             currency retrievable with publishable key currency
252              
253             Three-letter ISO currency code, in lowercase. Must be a supported currency.
254              
255             =item B<customer> string (expandable)
256              
257             ID of the Customer this PaymentIntent belongs to, if one exists.
258              
259             If present, payment methods used with this PaymentIntent can only be attached to this Customer, and payment methods attached to other Customers cannot be used with this PaymentIntent.
260              
261             This is a customer id or a L<Net::API::Stripe::Customer> object.
262              
263             =item B<description> retrievable with publishable key string
264              
265             An arbitrary string attached to the object. Often useful for displaying to users.
266              
267             =item B<invoice> string (expandable)
268              
269             ID of the invoice that created this PaymentIntent, if it exists.
270              
271             When expanded, this is a C<::API::Stripe::Billing::Invoice> object.
272              
273             =item B<last_payment_error> retrievable with publishable key hash
274              
275             The payment error encountered in the previous PaymentIntent confirmation.
276              
277             This is a L<Net::API::Stripe::Error> object.
278              
279             =item B<livemode> retrievable with publishable key boolean
280              
281             Has the value true if the object exists in live mode or the value false if the object exists in test mode.
282              
283             =item B<metadata> hash
284              
285             Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. For more information, see the documentation.
286              
287             =item B<next_action> retrievable with publishable key hash
288              
289             If present, this property tells you what actions you need to take in order for your customer to fulfill a payment using the provided source.
290              
291             This is a L<Net::API::Stripe::Payment::Intent::NextAction> object with the following properties:
292              
293             =over 8
294              
295             =item B<redirect_to_url> hash
296              
297             Contains instructions for authenticating a payment by redirecting your customer to another page or application.
298              
299             See module L<Net::API::Stripe::Payment::Intent::NextAction> for more information.
300              
301             =over 12
302              
303             =item I<return_url> string
304              
305             If the customer does not exit their browser while authenticating, they will be redirected to this specified URL after completion.
306              
307             =item I<url> string
308              
309             The URL you must redirect your customer to in order to authenticate the payment.
310              
311             =back
312              
313             =item B<type> string
314              
315             Type of the next action to perform, one of redirect_to_url or use_stripe_sdk.
316              
317             =item B<use_stripe_sdk> hash
318              
319             When confirming a PaymentIntent with Stripe.js, Stripe.js depends on the contents of this dictionary to invoke authentication flows. The shape of the contents is subject to change and is only intended to be used by Stripe.js.
320              
321             =back
322              
323             =item B<on_behalf_of> string (expandable)
324              
325             The account (if any) for which the funds of the PaymentIntent are intended. See the PaymentIntents use case for connected accounts for details.
326              
327             When expanded, this is a L<Net::API::Stripe::Connect::Account> object.
328              
329             =item B<payment_method> retrievable with publishable key string (expandable)
330              
331             ID of the payment method used in this PaymentIntent.
332              
333             =item B<payment_method_options> hash
334              
335             Payment-method-specific configuration for this PaymentIntent.
336              
337             This is a virtual L<Net::API::Stripe::Payment::Method::Options> object, ie a package created on the fly to allow the hash keys to be accessed as methods.
338              
339             =over 8
340              
341             =item B<card> hash
342              
343             If the PaymentIntent’s payment_method_types includes card, this hash contains the configurations that will be applied to each payment attempt of that type.
344              
345             =back
346              
347             =item B<payment_method_types> retrievable with publishable key array containing strings
348              
349             The list of payment method types (e.g. card) that this PaymentIntent is allowed to use.
350              
351             =item B<receipt_email> retrievable with publishable key string
352              
353             Email address that the receipt for the resulting payment will be sent to.
354              
355             =item B<review> string (expandable)
356              
357             ID of the review associated with this PaymentIntent, if any.
358              
359             This is a L<Net::API::Stripe::Fraud::Review> object.
360              
361             =item B<setup_future_usage> retrievable with publishable key string
362              
363             Indicates that you intend to make future payments with this PaymentIntent’s payment method.
364              
365             If present, the payment method used with this PaymentIntent can be attached to a Customer, even after the transaction completes.
366              
367             Use on_session if you intend to only reuse the payment method when your customer is present in your checkout flow. Use off_session if your customer may or may not be in your checkout flow. See Saving card details after a payment to learn more.
368              
369             Stripe uses setup_future_usage to dynamically optimize your payment flow and comply with regional legislation and network rules. For example, if your customer is impacted by SCA, using off_session will ensure that they are authenticated while processing this PaymentIntent. You will then be able to collect off-session payments for this customer.
370              
371             =item B<shipping> retrievable with publishable key hash
372              
373             Shipping information for this PaymentIntent.
374              
375             This is a L<Net::API::Stripe::Shipping> object.
376              
377             =item B<source>
378              
379             This is a L<Net::API::Stripe::Payment::Source>, but it seems it is not documented on the Stripe API although it is found in its response.
380              
381             =item B<statement_descriptor> string
382              
383             For non-card charges, you can use this value as the complete description that appears on your customers’ statements. Must contain at least one letter, maximum 22 characters.
384              
385             =item B<statement_descriptor_suffix> string
386              
387             Provides information about a card payment that customers see on their statements. Concatenated with the prefix (shortened descriptor) or statement descriptor that’s set on the account to form the complete statement descriptor. Maximum 22 characters for the concatenated descriptor.
388              
389             =item B<status> retrievable with publishable key string
390              
391             Status of this PaymentIntent, one of requires_payment_method, requires_confirmation, requires_action, processing, requires_capture, canceled, or succeeded. Read more about each PaymentIntent status.
392              
393             =item B<transfer_data> hash
394              
395             The data with which to automatically create a Transfer when the payment is finalized. See the PaymentIntents use case for connected accounts for details.
396              
397             This is a L<Net::API::Stripe::Payment::Intent::TransferData> object.
398              
399             =item B<transfer_group> string
400              
401             A string that identifies the resulting payment as part of a group. See the PaymentIntents use case for connected accounts for details.
402              
403             =back
404              
405             =head1 API SAMPLE
406              
407             {
408             "id": "pi_fake123456789",
409             "object": "payment_intent",
410             "amount": 1099,
411             "amount_capturable": 0,
412             "amount_received": 0,
413             "application": null,
414             "application_fee_amount": null,
415             "canceled_at": null,
416             "cancellation_reason": null,
417             "capture_method": "automatic",
418             "charges": {
419             "object": "list",
420             "data": [],
421             "has_more": false,
422             "url": "/v1/charges?payment_intent=pi_fake123456789"
423             },
424             "client_secret": "pi_fake123456789_secret_nvsnvmsbfmsbfmbfm",
425             "confirmation_method": "automatic",
426             "created": 1556596976,
427             "currency": "jpy",
428             "customer": null,
429             "description": null,
430             "invoice": null,
431             "last_payment_error": null,
432             "livemode": false,
433             "metadata": {},
434             "next_action": null,
435             "on_behalf_of": null,
436             "payment_method": null,
437             "payment_method_options": {},
438             "payment_method_types": [
439             "card"
440             ],
441             "receipt_email": null,
442             "review": null,
443             "setup_future_usage": null,
444             "shipping": null,
445             "statement_descriptor": null,
446             "statement_descriptor_suffix": null,
447             "status": "requires_payment_method",
448             "transfer_data": null,
449             "transfer_group": null
450             }
451              
452             =head1 HISTORY
453              
454             =head2 v0.1
455              
456             Initial version
457              
458             =head1 STRIPE HISTORY
459              
460             =head2 2019-02-11
461              
462             allowed_source_types has been renamed to payment_method_types.
463              
464             =head2 2019-02-11
465              
466             The next_source_action property on PaymentIntent has been renamed to next_action, and the authorize_with_url within has been renamed to redirect_to_url.
467              
468             =head1 AUTHOR
469              
470             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
471              
472             =head1 SEE ALSO
473              
474             Stripe API documentation:
475              
476             L<https://stripe.com/docs/api/payment_intents>, L<https://stripe.com/docs/payments/payment-intents/creating-payment-intents>
477              
478             =head1 COPYRIGHT & LICENSE
479              
480             Copyright (c) 2019-2020 DEGUEST Pte. Ltd.
481              
482             You can use, copy, modify and redistribute this package and associated
483             files under the same terms as Perl itself.
484              
485             =cut
486