File Coverage

lib/Net/API/Stripe/Payment/Intent.pm
Criterion Covered Total %
statement 19 62 30.6
branch n/a
condition n/a
subroutine 7 50 14.0
pod 39 43 90.7
total 65 155 41.9


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## Stripe API - ~/lib/Net/API/Stripe/Payment/Intent.pm
3             ## Version v0.102.0
4             ## Copyright(c) 2020 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2019/11/02
7             ## Modified 2022/10/29
8             ## All rights reserved
9             ##
10             ## This program is free software; you can redistribute it and/or modify it
11             ## under the same terms as Perl itself.
12             ##----------------------------------------------------------------------------
13             ## https://stripe.com/docs/api/payment_intents
14             package Net::API::Stripe::Payment::Intent;
15             BEGIN
16             {
17 2     2   21251777 use strict;
  2         13  
  2         63  
18 2     2   10 use warnings;
  2         8  
  2         59  
19 2     2   13 use parent qw( Net::API::Stripe::Generic );
  2         7  
  2         11  
20 2     2   147 use vars qw( $VERSION );
  2         7  
  2         115  
21 2     2   39 our( $VERSION ) = 'v0.102.0';
22             };
23              
24 2     2   14 use strict;
  2         4  
  2         54  
25 2     2   15 use warnings;
  2         4  
  2         1924  
26              
27 0     0 1   sub id { return( shift->_set_get_scalar( 'id', @_ ) ); }
28              
29 0     0 1   sub object { return( shift->_set_get_scalar( 'object', @_ ) ); }
30              
31             ## 2019-02-11
32             ## Stripe: allowed_source_types has been renamed to payment_method_types.
33             ## sub allowed_source_types { return( shift->_set_get_scalar( 'allowed_source_types', @_ ) ); }
34              
35 0     0 0   sub allowed_source_types { return( shift->payment_method_types( @_ ) ); }
36              
37 0     0 1   sub amount { return( shift->_set_get_number( 'amount', @_ ) ); }
38              
39 0     0 1   sub amount_capturable { return( shift->_set_get_number( 'amount_capturable', @_ ) ); }
40              
41 0     0 1   sub amount_details { return( shift->_set_get_class( 'amount_details',
42             {
43             tip => {
44             package => "Net::API::Stripe::Balance::ConnectReserved",
45             type => "object",
46             },
47             }, @_ ) ); }
48              
49 0     0 1   sub amount_received { return( shift->_set_get_number( 'amount_received', @_ ) ); }
50              
51 0     0 1   sub application { return( shift->_set_get_scalar_or_object( 'application', 'Net::API::Stripe::Connect::Account', @_ ) ); }
52              
53 0     0 1   sub application_fee_amount { return( shift->_set_get_number( 'application_fee_amount', @_ ) ); }
54              
55             ## 2019-02-11
56             ## Stripe: authorize_with_url within has been renamed to redirect_to_url.
57              
58 0     0 0   sub authorize_with_url { return( shift->redirect_to_url( @_ ) ); }
59              
60 0     0 1   sub automatic_payment_methods { return( shift->_set_get_object( 'automatic_payment_methods', 'Net::API::Stripe::Payment::Installment', @_ ) ); }
61              
62 0     0 1   sub canceled_at { return( shift->_set_get_datetime( 'canceled_at', @_ ) ); }
63              
64 0     0 1   sub cancellation_reason { return( shift->_set_get_scalar( 'cancellation_reason', @_ ) ); }
65              
66 0     0 1   sub capture_method { return( shift->_set_get_scalar( 'capture_method', @_ ) ); }
67              
68 0     0 1   sub charges { return( shift->_set_get_object( 'charges', 'Net::API::Stripe::Payment::Intent::Charges', @_ ) ); }
69              
70 0     0 1   sub client_secret { return( shift->_set_get_scalar( 'client_secret', @_ ) ); }
71              
72 0     0 1   sub confirmation_method { return( shift->_set_get_scalar( 'confirmation_method', @_ ) ); }
73              
74 0     0 1   sub created { return( shift->_set_get_datetime( 'created', @_ ) ); }
75              
76 0     0 1   sub currency { return( shift->_set_get_scalar( 'currency', @_ ) ); }
77              
78 0     0 1   sub customer { return( shift->_set_get_scalar_or_object( 'customer', 'Net::API::Stripe::Customer', @_ ) ); }
79              
80 0     0 1   sub description { return( shift->_set_get_scalar( 'description', @_ ) ); }
81              
82 0     0 1   sub invoice { return( shift->_set_get_scalar_or_object( 'invoice', 'Net::API::Stripe::Billing::Invoice', @_ ) ); }
83              
84 0     0 1   sub last_payment_error { return( shift->_set_get_object( 'last_payment_error', 'Net::API::Stripe::Error', @_ ) ); }
85              
86 0     0 1   sub livemode { return( shift->_set_get_boolean( 'livemode', @_ ) ); }
87              
88 0     0 1   sub metadata { return( shift->_set_get_hash( 'metadata', @_ ) ); }
89              
90 0     0 1   sub next_action { return( shift->_set_get_object( 'next_action', 'Net::API::Stripe::Payment::Intent::NextAction', @_ ) ); }
91              
92             # 2019-02-11
93             # Stripe: The next_source_action property on PaymentIntent has been renamed to next_action
94             # sub next_source_action { shift->_set_get_scalar( 'next_source_action', @_ ); }
95              
96 0     0 0   sub next_source_action { return( shift->next_action( @_ ) ); }
97              
98 0     0 1   sub on_behalf_of { return( shift->_set_get_scalar_or_object( 'on_behalf_of', 'Net::API::Stripe::Connect::Account', @_ ) ); }
99              
100 0     0 1   sub payment_method { return( shift->_set_get_scalar_or_object( 'payment_method', 'Net::API::Stripe::Payment::Method', @_ ) ); }
101              
102 0     0 1   sub payment_method_options { return( shift->_set_get_object( 'payment_method_options', 'Net::API::Stripe::Payment::Method::Options', @_ ) ); }
103              
104 0     0 1   sub payment_method_types { return( shift->_set_get_array( 'payment_method_types', @_ ) ); }
105              
106 0     0 1   sub processing { return( shift->_set_get_object( 'processing', 'Net::API::Stripe::Issuing::Authorization::Transaction', @_ ) ); }
107              
108 0     0 1   sub receipt_email { return( shift->_set_get_scalar( 'receipt_email', @_ ) ); }
109              
110 0     0 0   sub return_url { return( shift->_set_get_uri( 'return_url', @_ ) ); }
111              
112 0     0 1   sub review { return( shift->_set_get_scalar_or_object( 'review', 'Net::API::Stripe::Fraud::Review', @_ ) ); }
113              
114 0     0 1   sub setup_future_usage { return( shift->_set_get_scalar( 'setup_future_usage', @_ ) ); }
115              
116 0     0 1   sub shipping { return( shift->_set_get_object( 'shipping', 'Net::API::Stripe::Shipping', @_ ) ); }
117              
118 0     0 1   sub source { return( shift->_set_get_scalar_or_object( 'source', 'Net::API::Stripe::Payment::Source', @_ ) ); }
119              
120 0     0 1   sub statement_descriptor { return( shift->_set_get_scalar( 'statement_descriptor', @_ ) ); }
121              
122 0     0 1   sub statement_descriptor_suffix { return( shift->_set_get_scalar( 'statement_descriptor_suffix', @_ ) ); }
123              
124 0     0 1   sub status { return( shift->_set_get_scalar( 'status', @_ ) ); }
125              
126 0     0 1   sub transfer_data { return( shift->_set_get_object( 'transfer_data', 'Net::API::Stripe::Connect::Transfer', @_ ) ); }
127              
128 0     0 1   sub transfer_group { return( shift->_set_get_scalar( 'transfer_group', @_ ) ); }
129              
130             1;
131              
132             __END__
133              
134             =encoding utf8
135              
136             =head1 NAME
137              
138             Net::API::Stripe::PaymentIntent - The PaymentIntent object
139              
140             =head1 SYNOPSIS
141              
142             my $intent = $stripe->payment_intent({
143             amount => 2000,
144             amount_capturable => 2000,
145             application => $connect_account_object,
146             application_fee_amount => 20,
147             capture_method => 'automatic',
148             customer => $customer_object,
149             description => 'Preparation for payment',
150             invoice => $invoice_object,
151             metadata => { transaction_id => 123, customer_id => 456 },
152             receipt_email => 'john.doe@example.com',
153             });
154              
155             See documentation in L<Net::API::Stripe> for example to make api calls to Stripe to create those objects.
156              
157             =head1 VERSION
158              
159             v0.102.0
160              
161             =head1 DESCRIPTION
162              
163             A PaymentIntent guides you through the process of collecting a payment from your customer.
164             We recommend 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.
165             A PaymentIntent transitions through L<multiple statuses|https://stripe.com/docs/payments/intents#intent-statuses> throughout its lifetime as it interfaces with Stripe.js to perform authentication flows and ultimately creates at most one successful charge.
166              
167             Related guide: L<Payment Intents API|https://stripe.com/docs/payments/payment-intents>.
168              
169             Creating payments takes five steps:
170              
171             =over 4
172              
173             =item 1. Create a PaymentIntent on the server
174              
175             =item 2. Pass the PaymentIntent’s client secret to the client
176              
177             =item 3. Collect payment method details on the client
178              
179             =item 4. Submit the payment to Stripe from the client
180              
181             =item 5. Asynchronously fulfill the customer’s order
182              
183             =back
184              
185             More info here: L<https://stripe.com/docs/payments/payment-intents/web>
186              
187             =head1 METHODS
188              
189             =head2 id string
190              
191             Unique identifier for the object.
192              
193             =head2 object string
194              
195             String representing the object's type. Objects of the same type share the same value.
196              
197             =head2 amount integer
198              
199             Amount intended to be collected by this PaymentIntent. A positive integer representing how much to charge in the L<smallest currency unit|https://stripe.com/docs/currencies#zero-decimal> (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or L<equivalent in charge currency|https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts>. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).
200              
201             =head2 amount_capturable integer
202              
203             Amount that can be captured from this PaymentIntent.
204              
205             =head2 amount_details hash
206              
207             Details about items included in the amount
208              
209             It has the following properties:
210              
211             =over 4
212              
213             =item C<tip> hash
214              
215             Details about the tip.
216              
217             When expanded, this is a L<Net::API::Stripe::Balance::ConnectReserved> object.
218              
219             =back
220              
221             =head2 amount_received integer
222              
223             Amount that was collected by this PaymentIntent.
224              
225             =head2 application expandable
226              
227             ID of the Connect application that created the PaymentIntent.
228              
229             When expanded this is an L<Net::API::Stripe::Connect::Account> object.
230              
231             =head2 application_fee_amount integer
232              
233             The amount of the application fee (if any) that will be requested to be applied to the payment and transferred to the application owner's Stripe account. The amount of the application fee collected will be capped at the total payment amount. For more information, see the PaymentIntents L<use case for connected accounts|https://stripe.com/docs/payments/connected-accounts>.
234              
235             =head2 automatic_payment_methods object
236              
237             Settings to configure compatible payment methods from the L<Stripe Dashboard|https://dashboard.stripe.com/settings/payment_methods>
238              
239             This is a L<Net::API::Stripe::Payment::Installment> object.
240              
241             =head2 canceled_at timestamp
242              
243             Populated when C<status> is C<canceled>, this is the time at which the PaymentIntent was canceled. Measured in seconds since the Unix epoch.
244              
245             =head2 cancellation_reason string
246              
247             Reason for cancellation of this PaymentIntent, either user-provided (C<duplicate>, C<fraudulent>, C<requested_by_customer>, or C<abandoned>) or generated by Stripe internally (C<failed_invoice>, C<void_invoice>, or C<automatic>).
248              
249             =head2 capture_method string
250              
251             Controls when the funds will be captured from the customer's account.
252              
253             =head2 charges object
254              
255             Charges that were created by this PaymentIntent, if any.
256              
257             This is a L<Net::API::Stripe::List> object.
258              
259             =head2 client_secret string
260              
261             The client secret of this PaymentIntent. Used for client-side retrieval using a publishable key.
262              
263             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.
264              
265             Refer to our docs to L<accept a payment|https://stripe.com/docs/payments/accept-a-payment?integration=elements> and learn about how C<client_secret> should be handled.
266              
267             =head2 confirmation_method string
268              
269             Possible enum values
270              
271             =over 4
272              
273             =item I<automatic>
274              
275             (Default) PaymentIntent can be confirmed using a publishable key. After next_actions are handled, no additional confirmation is required to complete the payment.
276              
277             =item I<manual>
278              
279             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.
280              
281             =back
282              
283             =head2 created timestamp
284              
285             Time at which the object was created. Measured in seconds since the Unix epoch.
286              
287             =head2 currency currency
288              
289             Three-letter L<ISO currency code|https://www.iso.org/iso-4217-currency-codes.html>, in lowercase. Must be a L<supported currency|https://stripe.com/docs/currencies>.
290              
291             =head2 customer expandable
292              
293             ID of the Customer this PaymentIntent belongs to, if one exists.
294              
295             Payment methods attached to other Customers cannot be used with this PaymentIntent.
296              
297             If present in combination with L<setup_future_usage|https://stripe.com#payment_intent_object-setup_future_usage>, this PaymentIntent's payment method will be attached to the Customer after the PaymentIntent has been confirmed and any required actions from the user are complete.
298              
299             When expanded this is an L<Net::API::Stripe::Customer> object.
300              
301             =head2 description string
302              
303             An arbitrary string attached to the object. Often useful for displaying to users.
304              
305             =head2 invoice expandable
306              
307             ID of the invoice that created this PaymentIntent, if it exists.
308              
309             When expanded this is an L<Net::API::Stripe::Billing::Invoice> object.
310              
311             =head2 last_payment_error hash
312              
313             The payment error encountered in the previous PaymentIntent confirmation. It will be cleared if the PaymentIntent is later updated for any reason.
314              
315             This is a L<Net::API::Stripe::Error> object.
316              
317             =head2 livemode boolean
318              
319             Has the value C<true> if the object exists in live mode or the value C<false> if the object exists in test mode.
320              
321             =head2 metadata hash
322              
323             Set of L<key-value pairs|https://stripe.com/docs/api/metadata> 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 L<documentation|https://stripe.com/docs/payments/payment-intents/creating-payment-intents#storing-information-in-metadata>.
324              
325             =head2 next_action object
326              
327             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.
328              
329             This is a L<Net::API::Stripe::Payment::Intent::NextAction> object.
330              
331             =head2 on_behalf_of expandable
332              
333             The account (if any) for which the funds of the PaymentIntent are intended. See the PaymentIntents L<use case for connected accounts|https://stripe.com/docs/payments/connected-accounts> for details.
334              
335             When expanded this is an L<Net::API::Stripe::Connect::Account> object.
336              
337             =head2 payment_method expandable
338              
339             ID of the payment method used in this PaymentIntent.
340              
341             When expanded this is an L<Net::API::Stripe::Payment::Method> object.
342              
343             =head2 payment_method_options object
344              
345             Payment-method-specific configuration for this PaymentIntent.
346              
347             This is a L<Net::API::Stripe::Payment::Method> object.
348              
349             =head2 payment_method_types array of string
350              
351             The list of payment method types (e.g. card) that this PaymentIntent is allowed to use.
352              
353             =head2 processing object
354              
355             If present, this property tells you about the processing state of the payment.
356              
357             This is a L<Net::API::Stripe::Issuing::Authorization::Transaction> object.
358              
359             =head2 receipt_email string
360              
361             Email address that the receipt for the resulting payment will be sent to. If C<receipt_email> is specified for a payment in live mode, a receipt will be sent regardless of your L<email settings|https://dashboard.stripe.com/account/emails>.
362              
363             =head2 review expandable
364              
365             ID of the review associated with this PaymentIntent, if any.
366              
367             When expanded this is an L<Net::API::Stripe::Fraud::Review> object.
368              
369             =head2 setup_future_usage string
370              
371             Indicates that you intend to make future payments with this PaymentIntent's payment method.
372              
373             Providing this parameter will L<attach the payment method|https://stripe.com/docs/payments/save-during-payment> to the PaymentIntent's Customer, if present, after the PaymentIntent is confirmed and any required actions from the user are complete. If no Customer was provided, the payment method can still be L<attached|https://stripe.com/docs/api/payment_methods/attach> to a Customer after the transaction completes.
374              
375             When processing card payments, Stripe also uses C<setup_future_usage> to dynamically optimize your payment flow and comply with regional legislation and network rules, such as L<SCA|https://stripe.com/docs/strong-customer-authentication>.
376              
377             =head2 shipping object
378              
379             Shipping information for this PaymentIntent.
380              
381             This is a L<Net::API::Stripe::Shipping> object.
382              
383             =head2 source
384              
385             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.
386              
387             =head2 statement_descriptor string
388              
389             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.
390              
391             =head2 statement_descriptor_suffix string
392              
393             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.
394              
395             =head2 status string
396              
397             Status of this PaymentIntent, one of C<requires_payment_method>, C<requires_confirmation>, C<requires_action>, C<processing>, C<requires_capture>, C<canceled>, or C<succeeded>. Read more about each PaymentIntent L<status|https://stripe.com/docs/payments/intents#intent-statuses>.
398              
399             =head2 transfer_data object
400              
401             The data with which to automatically create a Transfer when the payment is finalized. See the PaymentIntents L<use case for connected accounts|https://stripe.com/docs/payments/connected-accounts> for details.
402              
403             This is a L<Net::API::Stripe::Connect::Transfer> object.
404              
405             It uses the following methods:
406              
407             =over 4
408              
409             =item I<amount> integer
410              
411             Amount intended to be collected by this PaymentIntent. A positive integer representing how much to charge in the L<smallest currency unit|https://stripe.com/docs/currencies#zero-decimal> (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or L<equivalent in charge currency|https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts>. The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).
412              
413             =item I<destination> string expandable
414              
415             The account (if any) the payment will be attributed to for tax reporting, and where funds from the payment will be transferred to upon
416             payment success.
417              
418             When expanded this is an L<Net::API::Stripe::Connect::Account> object.
419              
420             =back
421              
422             =head2 transfer_group string
423              
424             A string that identifies the resulting payment as part of a group. See the PaymentIntents L<use case for connected accounts|https://stripe.com/docs/payments/connected-accounts> for details.
425              
426             =head1 API SAMPLE
427              
428             {
429             "id": "pi_1Dik5W2eZvKYlo2CDeNJH1A5",
430             "object": "payment_intent",
431             "amount": 1999,
432             "amount_capturable": 0,
433             "amount_received": 0,
434             "application": null,
435             "application_fee_amount": null,
436             "canceled_at": null,
437             "cancellation_reason": null,
438             "capture_method": "automatic",
439             "charges": {
440             "object": "list",
441             "data": [
442             ],
443             "has_more": false,
444             "url": "/v1/charges?payment_intent=pi_1Dik5W2eZvKYlo2CDeNJH1A5"
445             },
446             "client_secret": "pi_1Dik5W2eZvKYlo2CDeNJH1A5_secret_YsxmIGlVxOrzmONrMv6KzeqGS",
447             "confirmation_method": "automatic",
448             "created": 1545145346,
449             "currency": "gbp",
450             "customer": null,
451             "description": null,
452             "invoice": null,
453             "last_payment_error": null,
454             "livemode": false,
455             "metadata": {
456             },
457             "next_action": null,
458             "on_behalf_of": null,
459             "payment_method": null,
460             "payment_method_options": {
461             },
462             "payment_method_types": [
463             "card"
464             ],
465             "receipt_email": null,
466             "review": null,
467             "setup_future_usage": null,
468             "shipping": null,
469             "statement_descriptor": null,
470             "statement_descriptor_suffix": null,
471             "status": "requires_payment_method",
472             "transfer_data": null,
473             "transfer_group": null
474             }
475              
476             =head1 HISTORY
477              
478             =head2 v0.1.0
479              
480             Initial version
481              
482             =head1 STRIPE HISTORY
483              
484             =head2 2019-02-11
485              
486             allowed_source_types has been renamed to payment_method_types.
487              
488             =head2 2019-02-11
489              
490             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.
491              
492             =head1 AUTHOR
493              
494             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
495              
496             =head1 SEE ALSO
497              
498             Stripe API documentation:
499              
500             L<https://stripe.com/docs/api/payment_intents>, L<https://stripe.com/docs/payments/payment-intents/creating-payment-intents>
501              
502             =head1 COPYRIGHT & LICENSE
503              
504             Copyright (c) 2019-2020 DEGUEST Pte. Ltd.
505              
506             You can use, copy, modify and redistribute this package and associated
507             files under the same terms as Perl itself.
508              
509             =cut