@square/web-payments-sdk-types
Version:
Types for Square's Web Payments SDK
362 lines (361 loc) • 15 kB
TypeScript
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.
**/
export 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);
* ```
*/
export 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 {@link 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 {@link 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 {@link 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 {@link InvalidOptionError} if given invalid options
* @throws {@link WebSdkEmbedError} if the WebSDK is initialized in insecure context
* @throws {@link UnexpectedError} an internal SDK error occurred
*/
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 {@link InvalidElementPresentError} cannot build Google Pay due to the presence of a clashing DOM element
* @throws {@link InvalidPaymentRequestError} the provided payment request was invalid
* @throws {@link PaymentMethodUnsupportedError} the payment method was not supported for this merchant (See error message for reason)
* @throws {@link WebSdkEmbedError} if the WebSDK is initialized in insecure context
* @throws {@link UnexpectedError} an internal SDK error occurred
*/
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 {@link InvalidPaymentRequestError} the provided payment request was invalid
* @throws {@link PaymentMethodUnsupportedError} if Apple Pay is not supported here
* @throws {@link WebSdkEmbedError} if the WebSDK is initialized in insecure context
* @throws {@link UnexpectedError} an internal SDK error occurred
*/
applePay(paymentRequest: PaymentRequest): Promise<ApplePay>;
/**
* Creates an ACH payment method instance
*
* @example
* ```
* const ach = await payments.ach({
* 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 {@link InvalidConfigurationValueError} if given invalid option values
* @throws {@link PaymentMethodUnsupportedError} the payment method was not supported for this merchant (See error message for reason)
* @throws {@link WebSdkEmbedError} if the WebSDK is initialized in insecure context
* @throws {@link UnexpectedError} an internal SDK error occurred
*/
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 {@link InvalidOptionError} if given invalid options
* @throws {@link WebSdkEmbedError} if the WebSDK is initialized in insecure context
* @throws {@link UnexpectedError} an internal SDK error occurred
*/
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 {@link AfterpayInvalidPaymentRequestError} if the provided payment request is invalid for Afterpay specifically
* @throws {@link AfterpayRequestError} if there is a problem processing the payment request with Afterpay
* @throws {@link InvalidCurrencyFormatError} if given invalid currency values
* @throws {@link InvalidPaymentRequestError} the provided payment request was invalid
* @throws {@link PaymentMethodUnsupportedError} the payment method was not supported for this merchant (See error message for reason)
* @throws {@link WebSdkEmbedError} if the WebSDK is initialized in insecure context
* @throws {@link UnexpectedError} an internal SDK error occurred
*/
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 {@link CashAppPayInvalidPaymentRequestError} the payment request was using an unsupported currency code
* @throws {@link CashAppPayMissingRedirectUrlError} a redirect url was not provided.
* @throws {@link PaymentMethodUnsupportedError} the payment method was not supported for this merchant (See error message for reason)
* @throws {@link InvalidPaymentRequestError} the provided payment request was invalid
* @throws {@link WebSdkEmbedError} if the WebSDK is initialized in insecure context
* @throws {@link UnexpectedError} an internal SDK error occurred
*/
cashAppPay(paymentRequest: PaymentRequest, options: CashAppPaymentRequestOptions): Promise<CashAppPay>;
}