1 | import {Token, PaymentMethod, Source} from '../api';
|
2 |
|
3 | export interface PaymentRequest {
|
4 | /**
|
5 | * Returns a `Promise` that resolves with a truthy value if an enabled wallet is ready to pay.
|
6 | * If no wallet is available, it resolves with `null`.
|
7 | */
|
8 | canMakePayment(): Promise<CanMakePaymentResult | null>;
|
9 |
|
10 | /**
|
11 | * Shows the browser’s payment interface.
|
12 | * When using the `PaymentRequestButtonElement`, this is called for you automatically.
|
13 | * This method must be called as the result of a user interaction (for example, in a click handler).
|
14 | */
|
15 | show(): void;
|
16 |
|
17 | /**
|
18 | * Closes the browser’s payment interface.
|
19 | */
|
20 | abort: () => void;
|
21 |
|
22 | /**
|
23 | * `true` if the browser’s payment interface is showing.
|
24 | * When using the `PaymentRequestButtonElement`, this is called for you automatically.
|
25 | */
|
26 | isShowing: () => boolean;
|
27 |
|
28 | /**
|
29 | * `PaymentRequest` instances can be updated with an options object.
|
30 | *
|
31 | * `paymentRequest.update` can only be called when the browser payment interface is not showing.
|
32 | * Listen to the [click](https://stripe.com/docs/js/element/events) and [cancel](https://stripe.com/docs/js/element/events) events to detect if the payment interface has been initiated.
|
33 | * To update the `PaymentRequest` right before the payment interface is initiated, call `paymentRequest.update` in your click event handler.
|
34 | */
|
35 | update(options: PaymentRequestUpdateOptions): void;
|
36 |
|
37 | /**
|
38 | * Stripe.js automatically creates a `Token` after the customer is done interacting with the browser’s payment interface.
|
39 | * To access the created `Token`, listen for this event.
|
40 | */
|
41 | on(
|
42 | eventType: 'token',
|
43 | handler: (event: PaymentRequestTokenEvent) => any
|
44 | ): this;
|
45 | once(
|
46 | eventType: 'token',
|
47 | handler: (event: PaymentRequestTokenEvent) => any
|
48 | ): this;
|
49 | off(
|
50 | eventType: 'token',
|
51 | handler?: (event: PaymentRequestTokenEvent) => any
|
52 | ): this;
|
53 |
|
54 | /**
|
55 | * Stripe.js automatically creates a `PaymentMethod` after the customer is done interacting with the browser’s payment interface.
|
56 | * To access the created `PaymentMethod`, listen for this event.
|
57 | */
|
58 | on(
|
59 | eventType: 'paymentmethod',
|
60 | handler: (event: PaymentRequestPaymentMethodEvent) => any
|
61 | ): this;
|
62 | once(
|
63 | eventType: 'paymentmethod',
|
64 | handler: (event: PaymentRequestPaymentMethodEvent) => any
|
65 | ): this;
|
66 | off(
|
67 | eventType: 'paymentmethod',
|
68 | handler?: (event: PaymentRequestPaymentMethodEvent) => any
|
69 | ): this;
|
70 |
|
71 | /**
|
72 | * Stripe.js automatically creates a `Source` after the customer is done interacting with the browser’s payment interface.
|
73 | * To access the created `Source`, listen for this event.
|
74 | */
|
75 | on(
|
76 | eventType: 'source',
|
77 | handler: (event: PaymentRequestSourceEvent) => any
|
78 | ): this;
|
79 | once(
|
80 | eventType: 'source',
|
81 | handler: (event: PaymentRequestSourceEvent) => any
|
82 | ): this;
|
83 | off(
|
84 | eventType: 'source',
|
85 | handler?: (event: PaymentRequestSourceEvent) => any
|
86 | ): this;
|
87 |
|
88 | /**
|
89 | * The cancel event is emitted from a `PaymentRequest` when the browser's payment interface is dismissed.
|
90 | *
|
91 | * Note that in some browsers, the payment interface may be dismissed by the customer even after they authorize the payment.
|
92 | * This means that you may receive a cancel event on your `PaymentRequest` object after receiving a `token`, `paymentmethod`, or `source` event.
|
93 | * If you’re using the cancel event as a hook for canceling the customer’s order, make sure you also refund the payment that you just created.
|
94 | */
|
95 | on(eventType: 'cancel', handler: () => any): this;
|
96 | once(eventType: 'cancel', handler: () => any): this;
|
97 | off(eventType: 'cancel', handler?: () => any): this;
|
98 |
|
99 | /**
|
100 | * The `shippingaddresschange` event is emitted from a `PaymentRequest` whenever the customer selects a new address in the browser's payment interface.
|
101 | */
|
102 | on(
|
103 | eventType: 'shippingaddresschange',
|
104 | handler: (event: PaymentRequestShippingAddressEvent) => any
|
105 | ): this;
|
106 | once(
|
107 | eventType: 'shippingaddresschange',
|
108 | handler: (event: PaymentRequestShippingAddressEvent) => any
|
109 | ): this;
|
110 | off(
|
111 | eventType: 'shippingaddresschange',
|
112 | handler?: (event: PaymentRequestShippingAddressEvent) => any
|
113 | ): this;
|
114 |
|
115 | /**
|
116 | * The `shippingoptionchange` event is emitted from a `PaymentRequest` whenever the customer selects a new shipping option in the browser's payment interface.
|
117 | */
|
118 | on(
|
119 | eventType: 'shippingoptionchange',
|
120 | handler: (event: PaymentRequestShippingOptionEvent) => any
|
121 | ): this;
|
122 | once(
|
123 | eventType: 'shippingoptionchange',
|
124 | handler: (event: PaymentRequestShippingOptionEvent) => any
|
125 | ): this;
|
126 | off(
|
127 | eventType: 'shippingoptionchange',
|
128 | handler?: (event: PaymentRequestShippingOptionEvent) => any
|
129 | ): this;
|
130 | }
|
131 |
|
132 | export type CanMakePaymentResult = Record<string, boolean>;
|
133 |
|
134 | export interface PaymentRequestUpdateOptions {
|
135 | /**
|
136 | * Three character currency code (e.g., `usd`).
|
137 | */
|
138 | currency?: string;
|
139 |
|
140 | /**
|
141 | * This `PaymentRequestItem` is shown to the customer in the browser’s payment interface.
|
142 | */
|
143 | total?: PaymentRequestItem;
|
144 |
|
145 | /**
|
146 | * An array of PaymentRequestItem objects.
|
147 | * These objects are shown as line items in the browser’s payment interface.
|
148 | * Note that the sum of the line item amounts does not need to add up to the `total` amount above.
|
149 | */
|
150 | displayItems?: PaymentRequestItem[];
|
151 | /**
|
152 | * An array of `ShippingOption` objects.
|
153 | * The first shipping option listed appears in the browser payment interface as the default option.
|
154 | */
|
155 |
|
156 | shippingOptions?: PaymentRequestShippingOption[];
|
157 | }
|
158 |
|
159 | /**
|
160 | * An set of options to create this `PaymentRequest` instance with.
|
161 | * These options can be updated using `paymentRequest.update`.
|
162 | */
|
163 | export interface PaymentRequestOptions {
|
164 | /**
|
165 | * The two-letter country code of your Stripe account (e.g., `US`).
|
166 | */
|
167 | country: string;
|
168 |
|
169 | /**
|
170 | * Three character currency code (e.g., `usd`).
|
171 | */
|
172 | currency: string;
|
173 |
|
174 | /**
|
175 | * This `PaymentRequestItem` is shown to the customer in the browser’s payment interface.
|
176 | */
|
177 | total: PaymentRequestItem;
|
178 |
|
179 | /**
|
180 | * An array of PaymentRequestItem objects.
|
181 | * These objects are shown as line items in the browser’s payment interface.
|
182 | * Note that the sum of the line item amounts does not need to add up to the `total` amount above.
|
183 | */
|
184 | displayItems?: PaymentRequestItem[];
|
185 |
|
186 | /**
|
187 | * By default, the browser's payment interface only asks the customer for actual payment information.
|
188 | * A customer name can be collected by setting this option to `true`.
|
189 | * This collected name will appears in the `PaymentRequestEvent` object.
|
190 | *
|
191 | * We highly recommend you collect at least one of name, email, or phone as this also results in collection of billing address for Apple Pay.
|
192 | * The billing address can be used to perform address verification and block fraudulent payments.
|
193 | * For all other payment methods, the billing address is automatically collected when available.
|
194 | */
|
195 | requestPayerName?: boolean;
|
196 |
|
197 | /**
|
198 | * See the `requestPayerName` option.
|
199 | */
|
200 | requestPayerPhone?: boolean;
|
201 |
|
202 | /**
|
203 | * See the `requestPayerName` option.
|
204 | */
|
205 | requestPayerEmail?: boolean;
|
206 |
|
207 | /**
|
208 | * Collect shipping address by setting this option to `true`.
|
209 | * The address appears in the `PaymentRequestEvent`.
|
210 | *
|
211 | * You must also supply a valid `PaymentRequestShippingOption` to the `shippingOptions` property.
|
212 | * This can be up front at the time `stripe.paymentRequest` is called, or in response to a `shippingaddresschange` event using the `updateWith` callback.
|
213 | */
|
214 | requestShipping?: boolean;
|
215 |
|
216 | /**
|
217 | * An array of `ShippingOption` objects.
|
218 | * The first shipping option listed appears in the browser payment interface as the default option.
|
219 | */
|
220 | shippingOptions?: PaymentRequestShippingOption[];
|
221 |
|
222 | /**
|
223 | * An array of wallet strings.
|
224 | * Can be one or more of `applePay`, `googlePay` and `browserCard`.
|
225 | * Use this option to disable Google Pay, Apple Pay and/or browser-saved cards.
|
226 | */
|
227 | disableWallets?: PaymentRequestWallet[];
|
228 |
|
229 | /**
|
230 | * @deprecated
|
231 | * Use disableWallets instead.
|
232 | */
|
233 | wallets?: PaymentRequestWallet[];
|
234 | }
|
235 |
|
236 | /**
|
237 | * A `PaymentRequestItem` object is used to configure a `PaymentRequest`.
|
238 | */
|
239 | export interface PaymentRequestItem {
|
240 | /**
|
241 | * The amount in the currency's subunit (e.g. cents, yen, etc.)
|
242 | */
|
243 | amount: number;
|
244 |
|
245 | /**
|
246 | * A name that the browser shows the customer in the payment interface.
|
247 | */
|
248 | label: string;
|
249 |
|
250 | /**
|
251 | * If you might change this amount later (for example, after you have calcluated shipping costs), set this to `true`.
|
252 | * Note that browsers treat this as a hint for how to display things, and not necessarily as something that will prevent submission.
|
253 | */
|
254 | pending?: boolean;
|
255 | }
|
256 |
|
257 | /**
|
258 | * The `ShippingOption` object describes a shipping method used with a `PaymentRequest`.
|
259 | */
|
260 | export interface PaymentRequestShippingOption {
|
261 | /**
|
262 | * A unique ID you create to keep track of this shipping option.
|
263 | * You’ll be told the ID of the selected option on changes and on completion.
|
264 | */
|
265 | id: string;
|
266 |
|
267 | /**
|
268 | * A short label for this shipping option.
|
269 | */
|
270 | label: string;
|
271 |
|
272 | /**
|
273 | * A longer description of this shipping option.
|
274 | */
|
275 | detail: string;
|
276 |
|
277 | /**
|
278 | * The amount to show for this shipping option.
|
279 | * If the cost of this shipping option depends on the shipping address the customer enters, listen for the `shippingaddresschange` event.
|
280 | */
|
281 | amount: number;
|
282 | }
|
283 |
|
284 | export type PaymentRequestWallet = 'applePay' | 'googlePay' | 'browserCard';
|
285 |
|
286 | export type PaymentRequestCompleteStatus =
|
287 | /**
|
288 | * Report to the browser that the payment was successful, and that it can close any active payment interface.
|
289 | */
|
290 | | 'success'
|
291 |
|
292 | /**
|
293 | * Report to the browser that you were unable to process the customer‘s payment.
|
294 | * Browsers may re-show the payment interface, or simply show a message and close.
|
295 | */
|
296 | | 'fail'
|
297 |
|
298 | /**
|
299 | * Equivalent to `fail`, except that the browser can choose to show a more-specific error message.
|
300 | */
|
301 | | 'invalid_payer_name'
|
302 |
|
303 | /**
|
304 | * Equivalent to `fail`, except that the browser can choose to show a more-specific error message.
|
305 | */
|
306 | | 'invalid_payer_phone'
|
307 |
|
308 | /**
|
309 | * Equivalent to `fail`, except that the browser can choose to show a more-specific error message.
|
310 | */
|
311 | | 'invalid_payer_email'
|
312 |
|
313 | /**
|
314 | * Equivalent to `fail`, except that the browser can choose to show a more-specific error message.
|
315 | */
|
316 | | 'invalid_shipping_address';
|
317 |
|
318 | export interface PaymentRequestEvent {
|
319 | /**
|
320 | * Call this function with a `CompleteStatus` when you have processed the token data provided by the API.
|
321 | * Note that you must must call complete within 30 seconds.
|
322 | */
|
323 | complete: (status: PaymentRequestCompleteStatus) => void;
|
324 |
|
325 | /**
|
326 | * The customer's name.
|
327 | * Only present if it was explicitly asked for [creating the PaymentRequest object](https://stripe.com/docs/js/payment_request/create).
|
328 | */
|
329 | payerName?: string;
|
330 |
|
331 | /**
|
332 | * The customer's email.
|
333 | * Only present if it was explicitly asked for [creating the PaymentRequest object](https://stripe.com/docs/js/payment_request/create).
|
334 | */
|
335 | payerEmail?: string;
|
336 |
|
337 | /**
|
338 | * The customer's phone.
|
339 | * Only present if it was explicitly asked for [creating the PaymentRequest object](https://stripe.com/docs/js/payment_request/create).
|
340 | */
|
341 | payerPhone?: string;
|
342 |
|
343 | /**
|
344 | * The final `ShippingAddress` the customer selected.
|
345 | * Only present when `requestShipping` is `true` when [creating the PaymentRequest object](https://stripe.com/docs/js/payment_request/create), and you've supplied at least one `ShippingOption`.
|
346 | */
|
347 | shippingAddress?: PaymentRequestShippingAddress;
|
348 |
|
349 | /**
|
350 | * The final `ShippingOption` the customer selected.
|
351 | * Only present when `requestShipping` is `true` when [creating the PaymentRequest object](https://stripe.com/docs/js/payment_request/create), and you've supplied at least one `ShippingOption`.
|
352 | */
|
353 | shippingOption?: PaymentRequestShippingOption;
|
354 |
|
355 | /**
|
356 | * The unique name of the wallet the customer chose to authorize payment.
|
357 | * For example, `browserCard`.
|
358 | */
|
359 | walletName: PaymentRequestWallet | string;
|
360 |
|
361 | /**
|
362 | * @deprecated
|
363 | * Use walletName instead.
|
364 | */
|
365 | methodName: string;
|
366 | }
|
367 |
|
368 | /**
|
369 | * Describes a shipping address collected with a `PaymentRequest`.
|
370 | */
|
371 | export interface PaymentRequestShippingAddress {
|
372 | /**
|
373 | * Two-letter country code, capitalized.
|
374 | * Valid two-letter country codes are specified by ISO3166 alpha-2.
|
375 | */
|
376 | country?: string;
|
377 |
|
378 | /**
|
379 | * An array of address line items.
|
380 | * For example, `185 Berry St.`, `Suite 500`, `P.O. Box 12345`, etc.
|
381 | */
|
382 | addressLine?: string[];
|
383 |
|
384 | /**
|
385 | * The most coarse subdivision of a country.
|
386 | * Depending on the country, this might correspond to a state, a province, an oblast, a prefecture, or something else along these lines.
|
387 | */
|
388 | region?: string;
|
389 |
|
390 | /**
|
391 | * The name of a city, town, village, etc.
|
392 | */
|
393 | city?: string;
|
394 |
|
395 | /**
|
396 | * The postal code or ZIP code, also known as PIN code in India.
|
397 | */
|
398 | postalCode?: string;
|
399 |
|
400 | /**
|
401 | * The name of the recipient.
|
402 | * This might be a person, a business name, or contain “care of” (c/o) instructions.
|
403 | */
|
404 | recipient?: string;
|
405 |
|
406 | /**
|
407 | * The phone number of the recipient.
|
408 | * Note that this might be different from any phone number you collect with `requestPayerPhone`.
|
409 | */
|
410 | phone?: string;
|
411 |
|
412 | /**
|
413 | * The sorting code as used in, for example, France.
|
414 | * Not present on Apple platforms.
|
415 | */
|
416 | sortingCode?: string;
|
417 |
|
418 | /**
|
419 | * A logical subdivision of a city.
|
420 | * Can be used for things like neighborhoods, boroughs, districts, or UK dependent localities.
|
421 | * Not present on Apple platforms.
|
422 | */
|
423 | dependentLocality?: string;
|
424 | }
|
425 |
|
426 | export interface PaymentRequestTokenEvent extends PaymentRequestEvent {
|
427 | token: Token;
|
428 | }
|
429 |
|
430 | export interface PaymentRequestPaymentMethodEvent extends PaymentRequestEvent {
|
431 | paymentMethod: PaymentMethod;
|
432 | }
|
433 |
|
434 | export interface PaymentRequestSourceEvent extends PaymentRequestEvent {
|
435 | source: Source;
|
436 | }
|
437 |
|
438 | export interface PaymentRequestShippingAddressEvent {
|
439 | /**
|
440 | * Call this with an `UpdateDetails` object to merge updates into the current `PaymentRequest` object.
|
441 | * Note that if you subscribe to `shippingaddresschange` events, then you must call `updateWith` within 30 seconds.
|
442 | */
|
443 | updateWith: (details: PaymentRequestUpdateDetails) => void;
|
444 |
|
445 | /**
|
446 | * The customer's selected `ShippingAddress`.
|
447 | * To maintain privacy, browsers may anonymize the shipping address by removing sensitive information that is not necessary to calculate shipping costs.
|
448 | * Depending on the country, some fields can be missing or partially redacted.
|
449 | * For example, the shipping address in the U.S. may only contain a city, state, and ZIP code.
|
450 | * The full shipping address appears in the `PaymentRequestEvent` object after the purchase is confirmed in the browser’s payment interface
|
451 | */
|
452 | shippingAddress: PaymentRequestShippingAddress;
|
453 | }
|
454 |
|
455 | export type PaymentRequestUpdateDetailsStatus =
|
456 | /**
|
457 | * Let the customer proceed.
|
458 | */
|
459 | | 'success'
|
460 |
|
461 | /**
|
462 | * Prevent the customer from making the change they just made.
|
463 | */
|
464 | | 'fail'
|
465 |
|
466 | /**
|
467 | * Equivalent to `fail`, except we show a more specific error message.
|
468 | * Can only be used in a `shippingaddresschange` handler.
|
469 | */
|
470 | | 'invalid_shipping_address';
|
471 |
|
472 | /**
|
473 | * An object to pass to the `updateWith` callback on `shippingaddresschange` and `shippingoptionchange` events.
|
474 | */
|
475 | export interface PaymentRequestUpdateDetails {
|
476 | /**
|
477 | * The browser uses this value to show an error message to the customer if they've taken an action that invalidates the payment request.
|
478 | */
|
479 | status?: PaymentRequestUpdateDetailsStatus;
|
480 |
|
481 | /**
|
482 | * The new total amount, if applicable.
|
483 | */
|
484 | total?: PaymentRequestItem;
|
485 |
|
486 | /**
|
487 | * These `PaymentRequestItem`s are shown as line items in the browser's payment interface.
|
488 | * Note that the sum of the line item amounts does not need to add up to the `total` amount.
|
489 | */
|
490 | displayItems?: PaymentRequestItem[];
|
491 |
|
492 | /**
|
493 | * The first shipping option listed appears in the browser payment interface as the default option.
|
494 | */
|
495 | shippingOptions?: PaymentRequestShippingOption[];
|
496 | }
|
497 |
|
498 | export interface PaymentRequestShippingOptionEvent {
|
499 | /**
|
500 | * Call this with an `UpdateDetails` object to merge updates into the current `PaymentRequest` object.
|
501 | * Note that if you subscribe to `shippingaddresschange` events, then you must call `updateWith` within 30 seconds.
|
502 | */
|
503 | updateWith: (details: PaymentRequestUpdateDetails) => void;
|
504 |
|
505 | /**
|
506 | * The customer's selected `ShippingOption`.
|
507 | */
|
508 | shippingOption: PaymentRequestShippingOption;
|
509 | }
|