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

Types for Square's Web Payments SDK

import type { AchOptions, AfterpayClearpay, CashAppPay, CashAppPaymentRequestOptions, PaymentRequestOptions } from './payment-method';
import type { ACH } from './payment-method/ach/method';
import type { ApplePay } from './payment-method/apple-pay/method';
import type { Card } from './payment-method/cards/method';
import type { CardOptions } from './payment-method/cards/types';
import type { GiftCardOptions } from './payment-method/gift-card';
import type { GiftCard } from './payment-method/gift-card/method';
import type { GooglePay } from './payment-method/google-pay/method';
import type { PaymentRequest } from './payment-request';
import type { ChargeVerifyBuyerDetails, StoreVerifyBuyerDetails, VerifyBuyerResponseDetails } from './verify-buyer';
/**
 * The result of calling `setLocale()` on the WebPaySDK payments instance.
 **/
interface SetLocaleResult {
    /**
     * The previous [BCP 47](https://tools.ietf.org/rfc/bcp/bcp47.txt) locale string of
     * the WebPaySDK before `setLocale()` was called.
     **/
    previousLocale: string;
    /**
     * The new [BCP 47](https://tools.ietf.org/rfc/bcp/bcp47.txt) locale string after
     * WebPaySDK `setLocale()` was called.
     **/
    newLocale: string;
    /**
     * A message that indicates the result of the setLocale call.
     **/
    message?: string;
}
/**
 * Returned by `Square.payments(appId, locationId)`.
 *
 * Use this object to instantiate Payment methods.
 * @example
 * const payments = Square.payments(appId, locationId);
 */
interface Payments {
    /**
     * Starts the **Strong Customer Authentication** flow to verify the identity of
     * the payment card holder.
     * @param source The payment token received from a tokenization call or the unique ID of a card on file.
     * @param details Details about the buyer to help verify their identify.
     * @throws {VerifyBuyerError} Something went wrong trying to verify the buyer
     */
    verifyBuyer(source: string, details: ChargeVerifyBuyerDetails | StoreVerifyBuyerDetails): Promise<VerifyBuyerResponseDetails | null>;
    /**
     * Creates a new PaymentRequest instance that sets up event listeners for GooglePay, ApplePay, CashAppPay, and Afterpay payment methods.
     * @param {PaymentRequestOptions} options
     * @throws {InvalidPaymentRequestError} the provided payment request was invalid
     * @returns {PaymentRequestImpl}
     *
     * @example
     * const paymentRequest = {
     *    countryCode: 'US',
     *    currencyCode: 'USD',
     *    lineItems: [
     *       { amount: '1.23', label: 'Cat', pending: false },
     *       { amount: '4.56', label: 'Dog', pending: false },
     *    ],
     *    shippingLineItems: [
     *       { amount: '0.00', label: 'FREE', pending: false },
     *    ],
     *    taxLineItems: [
     *       { amount: '0.60', label: 'State Tax', pending: false },
     *    ],
     *    discounts: [
     *       { amount: '1.00', label: 'Holiday Discount', pending: false },
     *    ],
     *    requestBillingContact: false,
     *    requestShippingContact: true,
     *    shippingContact: {
     *       addressLines: ['1 Test St', ''],
     *       city: 'San Francisco',
     *       countryCode: 'US',
     *       email: 'test@squareup.com',
     *       familyName: 'First Name',
     *       givenName: 'Last Name',
     *       phone: '+12345678910',
     *        postalCode: '11111',
     *       state: 'CA',
     *     },
     *     shippingOptions: [
     *       { amount: '0.00', id: 'FREE', label: 'Free' },
     *       { amount: '9.99', id: 'XP', label: 'Express' },
     *     ],
     *     total: { amount: '5.79', label: 'Total', pending: false },
     *   };
     * const payments = Square.payments(appId, locationId);
     * const req = payments.paymentRequest(paymentRequest);
     */
    paymentRequest(options: PaymentRequestOptions): PaymentRequest;
    /**
     * Sets the locale of the Payments instance. If this method is not called explicitly, the user's browser
     * language specified by `navigator.language` will be used instead. If the language returned by
     * `navigator.language` is unsupported, the SDK falls back to `en-US`.
     *
     * If the specified language passed to setLocale() is not supported, the operation is a no-op.
     * If the specified language is supported, but the specified region is not, Web Payments SDK will fall
     * back to using the desired language in a different supported region.
     *
     * @param {String} locale The [BCP 47](https://tools.ietf.org/rfc/bcp/bcp47.txt) locale string
     * to set the WebPaySDK language to.
     *
     * @throws {FeatureDisabledError} if the feature is not enabled for this application
     * @returns {SetLocaleResult} An object denoting the result of calling setLocale
     */
    setLocale(locale: string): Promise<SetLocaleResult>;
    /**
     * Creates a Card payment method.
     * For more information about customizing the card form, see available [CardOptions](https://developer.squareup.com/reference/sdks/web/payments/objects/CardOptions).
     * @param options
     * @example
     * const payments = Square.payments(appId, locationId);
     * const card = await payments.card({
     *   "postalCode" : "12345",
     *   "style": {
     *     "input": {
     *       "color": "red",
     *     }
     *     "@media screen and (max-width: 600px)": {
     *         "input": {
     *           "fontSize": "12px",
     *        }
     *      }
     *   }
     * });
     * await card.attach('#card');
     * const form = document.querySelector('#card-payment');
     * form.addEventListener('submit', async (event) => {
     *    event.preventDefault();
     *    const tokenResult = await card.tokenize(verificationDetails);
     * });
     * @throws {InvalidConfigurationPropertyError} if given invalid option properties
     * @throws {InvalidConfigurationValueError} if given invalid option values
     * @throws {UnexpectedError} if the payment context cannot initialize
     * @throws {WebSdkEmbedError} if the WebSDK is initialized in insecure context
     */
    card(options?: CardOptions): Promise<Card>;
    /**
     * Create a GooglePay payment method instance.
     *
     * @example
     * const paymentRequest = payments.paymentRequest({
     *   countryCode: 'US',
     *   currencyCode: 'USD',
     *   total: {
     *     amount: '1.00',
     *     label: 'Total',
     *   },
     * });
     *
     * const googlePay = await payments.googlePay(paymentRequest);
     * // Must be an element ID.
     * await googlePay.attach('#target-element');
     *
     * const googlePayButtonTarget = document.getElementById('target-element');
     * googlePayButtonTarget.onclick = async () => {
     *   const tokenResult = await googlePay.tokenize();
     *
     *   // Pass the TokenResult to your server to complete the payment
     * }
     * @param paymentRequest - the payment request object created by [payments.paymentRequest(...)](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.paymentRequest)
     * @throws {InvalidElementPresentError} cannot build Google Pay due to the presence of a clashing DOM element
     * @throws {InvalidPaymentRequestError} the provided payment request was invalid
     * @throws {UnexpectedError} if the payment context cannot initialize
     * @throws {PaymentMethodUnsupportedError} the payment method was not supported for this merchant (See error message for reason)
     * @throws {WebSdkEmbedError} if the WebSDK is initialized in insecure context
     */
    googlePay(paymentRequest: PaymentRequest): Promise<GooglePay>;
    /**
     * Create an ApplePay payment method instance.
     *
     * @example
     * const paymentRequest = payments.paymentRequest({
     *   countryCode: 'US',
     *   currencyCode: 'USD',
     *   total: {
     *     amount: '1.00',
     *     label: 'Total',
     *   }
     * });
     *
     * const applePay = await payments.applePay(paymentRequest);
     *
     * const applePayButtonTarget = document.getElementById('target-element');
     * applePayButtonTarget.onclick = async () => {
     *   const tokenResult = await applePay.tokenize();
     *
     *   // Pass the TokenResult to your server to complete the payment
     * }
     * @param paymentRequest - the payment request object created by [payments.paymentRequest(...)](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.paymentRequest)
     * @throws {InvalidPaymentRequestError} the provided payment request was invalid
     * @throws {UnexpectedError} if the payment context cannot initialize
     * @throws {WebSdkEmbedError} if the WebSDK is initialized in insecure context
     */
    applePay(paymentRequest: PaymentRequest): Promise<ApplePay>;
    /**
     * Creates an ACH payment method instance
     *
     * @example
     * const ach = await payments.ach({
     *  redirectURI: window.location.href,
     *  transactionId: 'my-distinct-transaction-id',
     * )};
     *
     * const achButton = document.getElementById('ach-button')
     * const buyerNameField = document.getElementById('buyer-name-field');
     *
     * ach.addEventListener('ontokenization', (event) => {
     *   const { tokenResult, error } = event.detail;
     *   if (error) {
     *     console.error(error);
     *   } else if (tokenResult.status === 'OK') {
     *     const token = tokenResult.token;
     *     console.log(`Payment token is ${token}`);
     *   }
     * });
     *
     * achButton.onclick = () => {
     *   await ach.tokenize({
     *     accountHolderName: buyerNameField.value,
     *     intent: 'CHARGE',
     *     amount: '5.00',
     *     currency: 'USD',
     *   });
     * }
     * @throws {InvalidConfigurationValueError} if given invalid option values
     * @throws {UnexpectedError} if the payment context cannot initialize
     * @throws {PaymentMethodUnsupportedError} the payment method was not supported for this merchant (See error message for reason)
     * @throws {WebSdkEmbedError} if the WebSDK is initialized in insecure context
     */
    ach(achOptions?: AchOptions): Promise<ACH>;
    /**
     * Creates a GiftCard payment method instance.
     * @param options
     * @example
     * const payments = Square.payments(appId, locationId);
     * const giftCard = await payments.giftCard({
     *   "style": {
     *     "input": {
     *       "color": "red"
     *     }
     *   }
     * });
     * await giftCard.attach('#gift-card');
     * const form = document.querySelector('#gift-card-payment');
     * form.addEventListener('submit', async (event) => {
     *    event.preventDefault();
     *    const result = await giftCard.tokenize(); // the gift card nonce
     * });
     * @throws {InvalidConfigurationPropertyError} if given invalid option properties
     * @throws {InvalidConfigurationValueError} if given invalid option values
     * @throws {UnexpectedError} if the payment context cannot initialize
     * @throws {WebSdkEmbedError} if the WebSDK is initialized in insecure context
     */
    giftCard(options?: GiftCardOptions): Promise<GiftCard>;
    /**
     * Create an Afterpay/Clearpay payment method instance.
     *
     * @example
     * const paymentRequest = payments.paymentRequest({
     *   countryCode: 'US',
     *   currencyCode: 'USD',
     *   total: {
     *     amount: '5.79',
     *     label: 'Total'
     *   },
     *   requestShippingContact: true,
     * });
     *
     * paymentRequest.addEventListener('afterpay_shippingaddresschanged', function (contact) {
     *   return {
     *     shippingOptions: [
     *       {
     *         id: 'FREE',
     *         amount: '0.00',
     *         label: 'Free',
     *         taxLineItems: [
     *           {
     *             id: 'taxItem1',
     *             label: 'Taxes',
     *             amount: '3.50',
     *           }
     *         ],
     *         total: {
     *           amount: '9.29',
     *           label: 'Total'
     *         }
     *       }
     *     ],
     *   }
     * });
     *
     * const afterpayClearpay = await payments.afterpayClearpay(paymentRequest);
     * await afterpayClearpay.attach('#afterpay');
     *
     *
     * afterpayClearpayButton.onclick = async () => {
     *   const tokenResult = await afterpayClearpay.tokenize();
     *
     *   // Pass the TokenResult to your server to complete the payment
     * }
     *
     * @param paymentRequest - the PaymentRequest object created by [payments.paymentRequest(...)](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.paymentRequest)
     * @throws {AfterpayAmountOutsideLimitsError} if the amount is outside of the merchant's Afterpay payment limits
     * @throws {AfterpayInvalidPaymentRequestError} if the provided payment request is invalid for Afterpay specifically
     * @throws {AfterpayMerchantError} if Afterpay/Clearpay is not supported for a merchant
     * @throws {AfterpayOnTokenizeListenerError} if both tokenize() and onTokenize listeners are set up
     * @throws {AfterpayRequestError} if there is a problem processing the payment request
     * @throws {AfterpayUnsupportedCurrencyError} if the currency provided is not supported for use by Afterpay/Clearpay
     * @throws {InvalidCurrencyFormatError} if given invalid currency values
     * @throws {InvalidPaymentRequestError} the provided payment request was invalid
     * @throws {UnexpectedError} if the payment context cannot initialize
     * @throws {PaymentMethodUnsupportedError} the payment method was not supported for this merchant (See error message for reason)
     * @throws {WebSdkEmbedError} if the WebSDK is initialized in insecure context
     */
    afterpayClearpay(paymentRequest: PaymentRequest): Promise<AfterpayClearpay>;
    /**
     * Create a Cash App Pay payment method instance
     *
     * @example
     * const paymentRequest = payments.paymentRequest({
     * countryCode: 'US',
     * currencyCode: 'USD',
     * total: { amount: '5.79', label: 'Total', pending: false },
     * });
     *
     * const cashAppPay = await payments.cashAppPay(req, options);
     *
     * cashAppPay.addEventListener('ontokenization', (event) => {
     *  const { tokenResult } = event.detail;
     *  const tokenStatus = tokenResult.status;
     *  if (tokenStatus === 'OK') {
     *    const token = tokenResult.token;
     *   }
     * });
     *
     * await cashAppPay.attach('#cashAppPay');
     *
     * @param {PaymentRequest} paymentRequest
     * @param options
     * @throws {CashAppPayInvalidPaymentRequestError} the payment request was using an unsupported currency code
     * @throws {CashAppPayMissingRedirectUrlError} a redirect url was not provided.
     * @throws {PaymentMethodUnsupportedError} the payment method was not supported for this merchant (See error message for reason)
     * @throws {InvalidPaymentRequestError} the provided payment request was invalid
     * @throws {UnexpectedError} if the payment context cannot initialize
     * @throws {WebSdkEmbedError} if the WebSDK is initialized in insecure context
     */
    cashAppPay(paymentRequest: PaymentRequest, options: CashAppPaymentRequestOptions): Promise<CashAppPay>;
}
export { SetLocaleResult, Payments };