diff --git a/types/applepayjs/applepayjs-tests.ts b/types/applepayjs/applepayjs-tests.ts index 505dbd2daf..de58dd30cd 100644 --- a/types/applepayjs/applepayjs-tests.ts +++ b/types/applepayjs/applepayjs-tests.ts @@ -20,6 +20,70 @@ describe("ApplePaySession", () => { break; } }); + it("the contact fields are defined", () => { + const contacts = [ + ApplePayJS.ApplePayContactField.email, + ApplePayJS.ApplePayContactField.name, + ApplePayJS.ApplePayContactField.phone, + ApplePayJS.ApplePayContactField.phoneticName, + ApplePayJS.ApplePayContactField.postalAddress + ]; + }); + it("the error codes are defined", () => { + const errorCodes = [ + ApplePayJS.ApplePayErrorCode.addressUnserviceable, + ApplePayJS.ApplePayErrorCode.billingContactInvalid, + ApplePayJS.ApplePayErrorCode.shippingContactInvalid, + ApplePayJS.ApplePayErrorCode.unknown + ]; + }); + it("the error contact fields are defined", () => { + const contacts = [ + ApplePayJS.ApplePayErrorContactField.addressLines, + ApplePayJS.ApplePayErrorContactField.administrativeArea, + ApplePayJS.ApplePayErrorContactField.country, + ApplePayJS.ApplePayErrorContactField.countryCode, + ApplePayJS.ApplePayErrorContactField.emailAddress, + ApplePayJS.ApplePayErrorContactField.locality, + ApplePayJS.ApplePayErrorContactField.name, + ApplePayJS.ApplePayErrorContactField.phoneNumber, + ApplePayJS.ApplePayErrorContactField.phoneticName, + ApplePayJS.ApplePayErrorContactField.postalAddress, + ApplePayJS.ApplePayErrorContactField.postalCode, + ApplePayJS.ApplePayErrorContactField.subAdministrativeArea, + ApplePayJS.ApplePayErrorContactField.subLocality + ]; + }); + it("the line item types are defined", () => { + const errorCodes = [ + ApplePayJS.ApplePayLineItemType.final, + ApplePayJS.ApplePayLineItemType.pending + ]; + }); + it("the merchant capabilities are defined", () => { + const errorCodes = [ + ApplePayJS.ApplePayMerchantCapability.supports3DS, + ApplePayJS.ApplePayMerchantCapability.supportsCredit, + ApplePayJS.ApplePayMerchantCapability.supportsDebit, + ApplePayJS.ApplePayMerchantCapability.supportsEMV + ]; + }); + it("the payment method types are defined", () => { + const errorCodes = [ + ApplePayJS.ApplePayPaymentMethodType.credit, + ApplePayJS.ApplePayPaymentMethodType.debit, + ApplePayJS.ApplePayPaymentMethodType.prepaid, + ApplePayJS.ApplePayPaymentMethodType.store + ]; + }); + it("the shipping types are defined", () => { + const errorCodes = [ + ApplePayJS.ApplePayShippingType.delivery, + ApplePayJS.ApplePayShippingType.servicePickup, + ApplePayJS.ApplePayShippingType.shipping, + ApplePayJS.ApplePayShippingType.storePickup + ]; + }); it("can create a new instance", () => { const version = 1; const paymentRequest = { @@ -57,7 +121,7 @@ describe("ApplePaySession", () => { }); }); it("can call instance methods", () => { - const version = 1; + const version = 3; const paymentRequest = { countryCode: "US", currencyCode: "USD", @@ -66,7 +130,9 @@ describe("ApplePaySession", () => { "visa" ], merchantCapabilities: [ - "supports3DS" + "supports3DS", + ApplePayJS.ApplePayMerchantCapability.supportsCredit, + ApplePayJS.ApplePayMerchantCapability.supportsDebit ], total: { label: "My Store", @@ -80,8 +146,22 @@ describe("ApplePaySession", () => { session.completeMerchantValidation({ foo: "bar" }); + session.completePayment(ApplePaySession.STATUS_SUCCESS); + const authorizationResult = { + status: ApplePaySession.STATUS_FAILURE, + errors: [ + { + code: ApplePayJS.ApplePayErrorCode.addressUnserviceable, + contactField: ApplePayJS.ApplePayErrorContactField.postalCode, + message: "The specified postal code cannot be delivered to." + } + ] + }; + + session.completePayment(authorizationResult); + const total = { label: "Subtotal", type: "final", @@ -97,11 +177,12 @@ describe("ApplePaySession", () => { { label: "Free Shipping", amount: "0.00", - type: "pending" + type: ApplePayJS.ApplePayLineItemType.final }, { label: "Estimated Tax", - amount: "3.06" + amount: "3.06", + type: ApplePayJS.ApplePayLineItemType.pending } ]; @@ -120,17 +201,35 @@ describe("ApplePaySession", () => { session.completePaymentMethodSelection(total, lineItems); + const paymentUpdate = { + newTotal: total + }; + + session.completePaymentMethodSelection(paymentUpdate); + session.completeShippingContactSelection( ApplePaySession.STATUS_INVALID_SHIPPING_POSTAL_ADDRESS, shippingMethods, total, lineItems); + const contactUpdate = { + newTotal: total + }; + + session.completeShippingContactSelection(contactUpdate); + session.completeShippingMethodSelection( ApplePaySession.STATUS_SUCCESS, total, lineItems); + const shippingUpdate = { + newTotal: total + }; + + session.completeShippingMethodSelection(shippingUpdate); + session.oncancel = (event: ApplePayJS.Event): void => { event.cancelBubble = true; }; @@ -175,7 +274,7 @@ describe("ApplePayPaymentRequest", () => { merchantCapabilities: [ "supports3DS", "supportsCredit", - "supportsDebit" + ApplePayJS.ApplePayMerchantCapability.supportsDebit ], supportedNetworks: [ "amex", @@ -197,11 +296,15 @@ describe("ApplePayPaymentRequest", () => { familyName: "Patel", givenName: "Ravi", phoneNumber: "(408) 555-5555", + phoneticFamilyName: "Patel", + phoneticGivenName: "Ravi", addressLines: [ "1 Infinite Loop" ], locality: "Cupertino", + subLocality: "", administrativeArea: "CA", + subAdministrativeArea: "", postalCode: "95014", country: "United States", countryCode: "US" @@ -226,14 +329,14 @@ describe("ApplePayPaymentRequest", () => { paymentRequest.requiredBillingContactFields = [ "postalAddress", - "name" + ApplePayJS.ApplePayContactField.name ]; paymentRequest.requiredShippingContactFields = [ "postalAddress", "name", "phone", - "email" + ApplePayJS.ApplePayContactField.name ]; paymentRequest.shippingContact = { @@ -241,11 +344,15 @@ describe("ApplePayPaymentRequest", () => { familyName: "Patel", givenName: "Ravi", phoneNumber: "(408) 555-5555", + phoneticFamilyName: "Patel", + phoneticGivenName: "Ravi", addressLines: [ "1 Infinite Loop" ], locality: "Cupertino", + subLocality: "", administrativeArea: "CA", + subAdministrativeArea: "", postalCode: "95014", country: "United States", countryCode: "US" @@ -265,5 +372,6 @@ describe("ApplePayPaymentRequest", () => { ]; paymentRequest.shippingType = "storePickup"; + paymentRequest.shippingType = ApplePayJS.ApplePayShippingType.delivery; }); }); diff --git a/types/applepayjs/index.d.ts b/types/applepayjs/index.d.ts index f705a4fad2..112fb569ba 100644 --- a/types/applepayjs/index.d.ts +++ b/types/applepayjs/index.d.ts @@ -4,23 +4,23 @@ // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped /** - * A session object for managing the payment process on the web. + * ApplePaySession is the entry point for Apple Pay on the web. */ declare class ApplePaySession extends EventTarget { /** - * Creates a new instance of the ApplePaySession class. - * @param version - The version of the ApplePay JS API you are using. - * @param paymentRequest - An ApplePayPaymentRequest object that contains the information that is displayed on the Apple Pay payment sheet. + * The entry point for Apple Pay on the web. + * @param version - The version number of the ApplePay JS API you are using. The current API version number is 3. + * @param paymentRequest - An ApplePayPaymentRequest object that contains the information to be displayed on the Apple Pay payment sheet. */ constructor(version: number, paymentRequest: ApplePayJS.ApplePayPaymentRequest); /** - * A callback function that is automatically called when the payment UI is dismissed with an error. + * A callback function that is automatically called when the payment UI is dismissed. */ oncancel: (event: ApplePayJS.Event) => void; /** - * A callback function that is automatically called when the user has authorized the Apple Pay payment, typically via TouchID. + * A callback function that is automatically called when the user has authorized the Apple Pay payment with Touch ID, Face ID, or passcode. */ onpaymentauthorized: (event: ApplePayJS.ApplePayPaymentAuthorizedEvent) => void; @@ -45,28 +45,28 @@ declare class ApplePaySession extends EventTarget { onvalidatemerchant: (event: ApplePayJS.ApplePayValidateMerchantEvent) => void; /** - * Indicates whether or not the device supports Apple Pay. + * Indicates whether the device supports Apple Pay. * @returns true if the device supports making payments with Apple Pay; otherwise, false. */ static canMakePayments(): boolean; /** - * Indicates whether or not the device supports Apple Pay and if the user has an active card in Wallet. - * @param merchantIdentifier - The merchant ID received when the merchant enrolled in Apple Pay. - * @returns true if the device supports Apple Pay and there is at least one active card in Wallet; otherwise, false. + * Indicates whether the device supports Apple Pay and whether the user has an active card in Wallet. + * @param merchantIdentifier - The merchant ID created when the merchant enrolled in Apple Pay. + * @returns true if the device supports Apple Pay and there is at least one active card in Wallet that is qualified for payments on the web; otherwise, false. */ static canMakePaymentsWithActiveCard(merchantIdentifier: string): Promise; /** * Displays the Set up Apple Pay button. - * @param merchantIdentifier - The merchant ID received when the merchant enrolled in Apple Pay. + * @param merchantIdentifier - The merchant ID created when the merchant enrolled in Apple Pay. * @returns A boolean value indicating whether setup was successful. */ static openPaymentSetup(merchantIdentifier: string): Promise; /** - * Verifies if a web browser supports a given Apple Pay JS API version. - * @param version - A number representing the Apple Pay JS API version being checked. The initial version is 1. + * Verifies whether a web browser supports a given Apple Pay JS API version. + * @param version - A number representing the Apple Pay JS API version being checked. The initial version is 1. The latest version is 3. * @returns A boolean value indicating whether the web browser supports the given API version. Returns false if the web browser does not support the specified version. */ static supportsVersion(version: number): boolean; @@ -82,26 +82,38 @@ declare class ApplePaySession extends EventTarget { begin(): void; /** - * Call after the merchant has been validated. + * Completes the validation for a merchant session. * @param merchantSession - An opaque message session object. */ - completeMerchantValidation(merchantSession: any): void; + completeMerchantValidation(merchantSession: object): void; /** - * Call when a payment has been authorized. - * @param status - The status of the payment. + * Completes the payment authorization with a result for Apple Pay JS versions 1 and 2. + * @param status - The status of the payment, whether it succeeded or failed. */ completePayment(status: number): void; /** - * Call after a payment method has been selected. + * Completes the payment authorization with a result for Apple Pay JS version 3. + * @param result - The result of the payment authorization, including its status and list of errors. + */ + completePayment(result: ApplePayJS.ApplePayPaymentAuthorizationResult): void; + + /** + * Call after a payment method has been selected for Apple Pay JS versions 1 and 2. * @param newTotal - An ApplePayLineItem dictionary representing the total price for the purchase. * @param newLineItems - A sequence of ApplePayLineItem dictionaries. */ completePaymentMethodSelection(newTotal: ApplePayJS.ApplePayLineItem, newLineItems: ApplePayJS.ApplePayLineItem[]): void; /** - * Call after a shipping contact has been selected. + * Completes the selection of a payment method with an update for Apple Pay JS version 3. + * @param update - The updated payment method. + */ + completePaymentMethodSelection(update: ApplePayJS.ApplePayPaymentMethodUpdate): void; + + /** + * Completes the selection of a shipping contact with an update for Apple Pay JS versions 1 and 2. * @param status - The status of the shipping contact update. * @param newShippingMethods - A sequence of ApplePayShippingMethod dictionaries. * @param newTotal - An ApplePayLineItem dictionary representing the total price for the purchase. @@ -114,13 +126,25 @@ declare class ApplePaySession extends EventTarget { newLineItems: ApplePayJS.ApplePayLineItem[]): void; /** - * Call after the shipping method has been selected. + * Completes the selection of a shipping contact with an update for Apple Pay JS version 3. + * @param update - The updated shipping contact. + */ + completeShippingContactSelection(update: ApplePayJS.ApplePayShippingContactUpdate): void; + + /** + * Call after the shipping method has been selected for Apple Pay JS versions 1 and 2. * @param status - The status of the shipping method update. * @param newTotal - An ApplePayLineItem dictionary representing the total price for the purchase. * @param newLineItems - A sequence of ApplePayLineItem dictionaries. */ completeShippingMethodSelection(status: number, newTotal: ApplePayJS.ApplePayLineItem, newLineItems: ApplePayJS.ApplePayLineItem[]): void; + /** + * Completes the selection of a shipping method with an update for Apple Pay JS version 3. + * @param update - The updated shipping method. + */ + completeShippingMethodSelection(update: ApplePayJS.ApplePayShippingMethodUpdate): void + /** * The requested action succeeded. */ @@ -163,6 +187,79 @@ declare class ApplePaySession extends EventTarget { } declare namespace ApplePayJS { + + /** + * Field names used for requesting contact information in a payment request. + */ + enum ApplePayContactField { + email = 'email', + name = 'name', + phone = 'phone', + postalAddress = 'postalAddress', + phoneticName = 'phoneticName', + } + + /** + * A customizable error type that you create to indicate problems with the address or contact information on an Apple Pay sheet. + */ + interface ApplePayError { + /** + * The error code for this instance. + */ + code: ApplePayErrorCode; + + /** + * The name of the field that contains the error. + */ + contactField?: ApplePayErrorContactField; + + /** + * A localized, user-facing string that describes the error. + */ + message: string; + } + + /** + * The error code that indicates whether an error on the payment sheet is for shipping or billing information, or for another kind of error. + */ + enum ApplePayErrorCode { + /** + * Shipping address or contact information is invalid or missing. + */ + shippingContactInvalid = 'shippingContactInvalid', + /** + * Billing address information is invalid or missing. + */ + billingContactInvalid = 'billingContactInvalid', + /** + * The merchant cannot provide service to the shipping address (for example, can't deliver to a P.O. Box). + */ + addressUnserviceable = 'addressUnserviceable', + /** + * An unknown but nonfatal error occurred during payment processing. The user can attempt authorization again. + */ + unknown = 'unknown', + } + + /** + * Names of the fields in the shipping or billing contact information, used to locate errors in the payment sheet. + */ + enum ApplePayErrorContactField { + phoneNumber = 'phoneNumber', + emailAddress = 'emailAddress', + name = 'name', + phoneticName = 'phoneticName', + postalAddress = 'postalAddress', + addressLines = 'addressLines', + locality = 'locality', + subLocality = 'subLocality', + postalCode = 'postalCode', + administrativeArea = 'administrativeArea', + subAdministrativeArea = 'subAdministrativeArea', + country = 'country', + countryCode = 'countryCode', + } + /** * Defines a line item in a payment request - for example, total, tax, discount, or grand total. */ @@ -180,7 +277,47 @@ declare namespace ApplePayJS { /** * A value that indicates if the line item is final or pending. */ - type?: string; + type?: string | ApplePayLineItemType; + } + + /** + * A type that indicates whether a line item is final or pending. + */ + enum ApplePayLineItemType { + /** + * A line item representing the known, final cost. + */ + final = 'final', + + /** + * A line item representing an estimated or unknown cost. + */ + pending = 'pending', + } + + /** + * The payment capabilities supported by the merchant. + */ + enum ApplePayMerchantCapability { + /** + * Required. This value must be supplied. + */ + supports3DS = 'supports3DS', + + /** + * Include this value only if you support China Union Pay transactions. + */ + supportsEMV = 'supportsEMV', + + /** + * Optional. If present, only transactions that are categorized as credit cards are allowed. + */ + supportsCredit = 'supportsCredit', + + /** + * Optional. If present, only transactions that are categorized as debit cards are allowed. + */ + supportsDebit = 'supportsDebit', } /** @@ -188,7 +325,7 @@ declare namespace ApplePayJS { */ interface ApplePayPayment { /** - * The encrypted token for an authorized payment. + * The encrypted information for an authorized payment. */ token: ApplePayPaymentToken; @@ -208,11 +345,26 @@ declare namespace ApplePayJS { */ abstract class ApplePayPaymentAuthorizedEvent extends Event { /** - * The payment token used to authorize a payment. + * The authorized payment information for this transaction. */ readonly payment: ApplePayPayment; } + /** + * The result of payment authorization, including status and errors. + */ + interface ApplePayPaymentAuthorizationResult { + /** + * The status code for the authorization result. + */ + status: number; + + /** + * A list of custom errors to display on the payment sheet. + */ + errors?: ApplePayError[]; + } + /** * Encapsulates contact information needed for billing and shipping. */ @@ -238,7 +390,17 @@ declare namespace ApplePayJS { phoneNumber: string; /** - * The address for the contact. + * The phonetic spelling of the contact's family name. + */ + phoneticFamilyName: string; + + /** + * The phonetic spelling of the contact's given name. + */ + phoneticGivenName: string; + + /** + * The street portion of the address for the contact. */ addressLines: string[]; @@ -247,29 +409,39 @@ declare namespace ApplePayJS { */ locality: string; + /** + * Additional information associated with the location, typically defined at the city or town level (such as district or neighborhood), in a postal address. + */ + subLocality: string; + /** * The state for the contact. */ administrativeArea: string; /** - * The zip code, where applicable, for the contact. + * The subadministrative area (such as a county or other region) in a postal address. + */ + subAdministrativeArea: string; + + /** + * The zip code or postal code, where applicable, for the contact. */ postalCode: string; /** - * The colloquial country name for the contact. + * The name of the country for the contact. */ country: string; /** - * The contact's ISO country code. + * The contact’s two-letter ISO 3166 country code. */ countryCode: string; } /** - * Contains information about an Apple Pay payment card. + * A dictionary that describes an Apple Pay payment card. */ interface ApplePayPaymentMethod { /** @@ -279,21 +451,30 @@ declare namespace ApplePayJS { /** * A string, suitable for display, that is the name of the payment network backing the card. - * The value is one of the supported networks specified in the supportedNetworks property of the ApplePayPaymentRequest. */ network: string; /** * A value representing the card's type of payment. */ - type: string; + type: string | ApplePayPaymentMethodType; /** - * The payment pass object associated with the payment. + * The payment pass object currently selected to complete the payment. */ paymentPass: ApplePayPaymentPass; } + /** + * A payment card's type of payment. + */ + enum ApplePayPaymentMethodType { + debit = 'debit', + credit = 'credit', + prepaid = 'prepaid', + store = 'store' + } + /** * The ApplePayPaymentMethodSelectedEvent class defines the attributes contained by the ApplePaySession.onpaymentmethodselected callback function. */ @@ -304,6 +485,21 @@ declare namespace ApplePayJS { readonly paymentMethod: ApplePayPaymentMethod; } + /** + * Updated transaction details resulting from a change in payment method. + */ + interface ApplePayPaymentMethodUpdate { + /** + * An optional list of line items. + */ + newLineItems?: ApplePayLineItem[]; + + /** + * The new total resulting from a change in the payment method. + */ + newTotal: ApplePayLineItem; + } + /** * Represents a provisioned payment card for Apple Pay payments. */ @@ -331,7 +527,37 @@ declare namespace ApplePayJS { /** * The activation state of the pass. */ - activationState: string; + activationState: string | ApplePayPaymentPassActivationState; + } + + /** + * Payment pass activation states. + */ + enum ApplePayPaymentPassActivationState { + /** + * Active and ready to be used for payment. + */ + activated = 'activated', + + /** + * Not active but may be activated by the issuer. + */ + requiresActivation = 'requiresActivation', + + /** + * Not ready for use but activation is in progress. + */ + activating = 'activating', + + /** + * Not active and can't be activated. + */ + suspended = 'suspended', + + /** + * Not active because the issuer has disabled the account associated with the device. + */ + deactivated = 'deactivated', } /** @@ -357,7 +583,7 @@ declare namespace ApplePayJS { * The payment capabilities supported by the merchant. * The value must at least contain ApplePayMerchantCapability.supports3DS. */ - merchantCapabilities: string[]; + merchantCapabilities: string[] | ApplePayMerchantCapability[]; /** * The payment networks supported by the merchant. @@ -377,12 +603,12 @@ declare namespace ApplePayJS { /** * The billing information that you require from the user in order to process the transaction. */ - requiredBillingContactFields?: string[]; + requiredBillingContactFields?: string[] | ApplePayContactField[]; /** * The shipping information that you require from the user in order to fulfill the order. */ - requiredShippingContactFields?: string[]; + requiredShippingContactFields?: string[] | ApplePayContactField[]; /** * Shipping contact information for the user. @@ -397,7 +623,12 @@ declare namespace ApplePayJS { /** * How the items are to be shipped. */ - shippingType?: string; + shippingType?: string | ApplePayShippingType; + + /** + * A list of ISO 3166 country codes for limiting payments to cards from specific countries. + */ + supportedCountries?: string[]; /** * Optional user-defined data. @@ -406,7 +637,7 @@ declare namespace ApplePayJS { } /** - * Contains the user's payment credentials. + * An object that contains the user's payment credentials. */ interface ApplePayPaymentToken { /** @@ -426,7 +657,7 @@ declare namespace ApplePayJS { } /** - * The ApplePayShippingContactSelectedEvent class defines the attributes contained by the ApplePaySession.onshippingcontactselected callback function. + * Encapsulates the attributes contained by the onshippingcontactselected callback function. */ abstract class ApplePayShippingContactSelectedEvent extends Event { /** @@ -435,6 +666,31 @@ declare namespace ApplePayJS { readonly shippingContact: ApplePayPaymentContact; } + /** + * Updated transaction details resulting from a change in shipping contact, including any errors. + */ + class ApplePayShippingContactUpdate { + /** + * List of custom errors to display on the payment sheet. + */ + errors?: ApplePayError[]; + + /** + * An optional list of updated line items. + */ + newLineItems?: ApplePayLineItem[]; + + /** + * A list of shipping methods that are available to the updated shipping contact. + */ + newShippingMethods?: ApplePayShippingMethod[]; + + /** + * The new total resulting from a change in the shipping contact. + */ + newTotal: ApplePayLineItem; + } + /** * Defines a shipping method for delivering physical goods. */ @@ -471,11 +727,36 @@ declare namespace ApplePayJS { } /** - * The ApplePayValidateMerchantEvent class defines the attributes contained by the ApplePaySession.onvalidatemerchant callback function. + * Updated transaction details resulting from a change in shipping method. + */ + interface ApplePayShippingMethodUpdate { + /** + * An optional list of updated line items. + */ + newLineItems?: ApplePayLineItem[]; + + /** + * The new total resulting from a change in the shipping method. + */ + newTotal: ApplePayLineItem; + } + + /** + * A type that indicates how purchased items are to be shipped. + */ + enum ApplePayShippingType { + shipping = 'shipping', + delivery = 'delivery', + storePickup = 'storePickup', + servicePickup = 'servicePickup', + } + + /** + * The attributes contained by the onvalidatemerchant callback function. */ abstract class ApplePayValidateMerchantEvent extends Event { /** - * The URL used to validate the merchant server. + * The URL your server must use to validate itself and obtain a merchant session object. */ readonly validationURL: string; }