@square/web-payments-sdk-types/dist/v1/types/payment-request.d.ts

Types for Square's Web Payments SDK

import type { AfterpayEventsValue, AfterpayPaymentRequestCallback, PaymentRequestCallback, PaymentRequestEventValue, PaymentRequestOptions } from './payment-method';
/**
 * An object that represents an Apple Pay or Google Pay payment request
 *
 * `PaymentRequest` encapsulates the details of an Apple Pay, Google Pay, or Afterpay/Clearpay request
 * for payment and provides a means of listening for shipping option and shipping
 * contact changes via event listeners.
 * A PaymentRequest can be constructed by calling [payments.paymentRequest](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.paymentRequest).
 *
 * The event listeners for Afterpay/Clearpay are specific to that payment method.
 *
 * @example
 * const payments = Square.payments(appId, locationId);
 *
 * const paymentRequest = payments.paymentRequest({
 *   countryCode: 'US',
 *   currencyCode: 'USD',
 *   requestBillingContact: true,
 *   requestShippingContact: true,
 *   lineItems: [
 *      { amount: '2.00', label: 'Item Cost' },
 *      { amount: '0.00', label: 'Shipping' },
 *      { amount: '0.00', label: 'Tax' },
 *   ],
 *   shippingOptions: [
 *      {
 *        amount: '0.00',
 *        id: 'shipping-option-1',
 *        label: 'Free',
 *      },
 *   ],
 *   total: {
 *     amount: '1.00',
 *     label: 'Total',
 *   }
 * });
 *
 * const applePay = await payments.applePay(paymentRequest);
 * const googlePay = await payments.googlePay(paymentRequest);
 */
interface PaymentRequest {
    /**
     * Adds an event listener to the PaymentRequest.
     * @example
     * req.addEventListener('shippingcontactchanged', (contact) => {
     *   // action
     *   return { lineItems, total, shippingOptions };
     * });
     * req.addEventListener('shippingoptionchanged', (option) => {
     *  // action
     *  // the callback can be either async or sync.
     *  return Promise.resolve({ lintItems, total });
     * });
     *
     * // Afterpay/Clearpay
     * req.addEventListener('afterpay_shippingaddresschanged', (contact) => {
     *   // action
     *   return { shippingOptions: {
     *     taxLineItems: [],
     *     total: {
     *       amount: '1.21',
     *       label: 'Total',
     *     }
     *   } };
     * });
     * req.addEventListener('afterpay_shippingoptionchanged', (option) => {
     *  //This callback is used for informational purposes only and does not change the payment request or total amount.
     * });
     * @param {PaymentRequestEvent} event
     * @param {PaymentRequestCallback} callback
     */
    addEventListener(event: PaymentRequestEventValue | AfterpayEventsValue, callback: PaymentRequestCallback | AfterpayPaymentRequestCallback): void;
    /**
     * Updates the specified options of the PaymentRequest. Returns `true` if the update was
     * successful. Updates are not allowed while the Apple Pay or Google Pay payment sheets are
     * currently being displayed to the buyer. In these cases, `update()` will return `false`.
     * Cash App Pay does not allow `update()` for its `PaymentRequest` object. Payment objects associated with Cash App Pay cannot be updated before the Cash App Pay object is destroyed.
     * For more information about limitations of `update()` with Cash App Pay payment objects and Google Pay payment sheets, see [Take a Payment with Cash App Pay
  ](https://developer.squareup.com/docs/web-payments/add-cash-app-pay).
     *
     * @example
     * const updateSuccessful = req.update({ currencyCode: 'USD' });
     * @throws {InvalidPaymentRequestError}
     * @throws {InvalidEventListenerCallbackError} if an event listener callback throws an unexpected error
     * @throws {InvalidPaymentRequestUpdateError} if a payment request update object is malformed
     * @param {Partial<PaymentRequestOptions} options
     * @return {boolean} success
     **/
    update(options: Partial<PaymentRequestOptions>): boolean;
}
export { PaymentRequest };