diff --git a/types/applepayjs/applepayjs-tests.ts b/types/applepayjs/applepayjs-tests.ts
index 505dbd2daf..99b323453b 100644
--- a/types/applepayjs/applepayjs-tests.ts
+++ b/types/applepayjs/applepayjs-tests.ts
@@ -22,7 +22,7 @@ describe("ApplePaySession", () => {
});
it("can create a new instance", () => {
const version = 1;
- const paymentRequest = {
+ const paymentRequest: ApplePayJS.ApplePayPaymentRequest = {
countryCode: "US",
currencyCode: "USD",
supportedNetworks: [
@@ -57,8 +57,8 @@ describe("ApplePaySession", () => {
});
});
it("can call instance methods", () => {
- const version = 1;
- const paymentRequest = {
+ const version = 3;
+ const paymentRequest: ApplePayJS.ApplePayPaymentRequest = {
countryCode: "US",
currencyCode: "USD",
supportedNetworks: [
@@ -66,7 +66,9 @@ describe("ApplePaySession", () => {
"visa"
],
merchantCapabilities: [
- "supports3DS"
+ "supports3DS",
+ "supportsCredit",
+ "supportsDebit"
],
total: {
label: "My Store",
@@ -80,15 +82,29 @@ describe("ApplePaySession", () => {
session.completeMerchantValidation({
foo: "bar"
});
+
session.completePayment(ApplePaySession.STATUS_SUCCESS);
- const total = {
+ const authorizationResult: ApplePayJS.ApplePayPaymentAuthorizationResult = {
+ status: ApplePaySession.STATUS_FAILURE,
+ errors: [
+ {
+ code: "addressUnserviceable",
+ contactField: "postalCode",
+ message: "The specified postal code cannot be delivered to."
+ }
+ ]
+ };
+
+ session.completePayment(authorizationResult);
+
+ const total: ApplePayJS.ApplePayLineItem = {
label: "Subtotal",
type: "final",
amount: "35.00"
};
- const lineItems = [
+ const lineItems: ApplePayJS.ApplePayLineItem[] = [
{
label: "Subtotal",
type: "final",
@@ -97,11 +113,12 @@ describe("ApplePaySession", () => {
{
label: "Free Shipping",
amount: "0.00",
- type: "pending"
+ type: "final"
},
{
label: "Estimated Tax",
- amount: "3.06"
+ amount: "3.06",
+ type: "pending"
}
];
@@ -120,17 +137,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;
};
@@ -201,7 +236,9 @@ describe("ApplePayPaymentRequest", () => {
"1 Infinite Loop"
],
locality: "Cupertino",
+ subLocality: "",
administrativeArea: "CA",
+ subAdministrativeArea: "",
postalCode: "95014",
country: "United States",
countryCode: "US"
@@ -233,7 +270,7 @@ describe("ApplePayPaymentRequest", () => {
"postalAddress",
"name",
"phone",
- "email"
+ "name"
];
paymentRequest.shippingContact = {
@@ -241,11 +278,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 +306,6 @@ describe("ApplePayPaymentRequest", () => {
];
paymentRequest.shippingType = "storePickup";
+ paymentRequest.shippingType = "delivery";
});
});
diff --git a/types/applepayjs/index.d.ts b/types/applepayjs/index.d.ts
index f705a4fad2..a37f60b6fd 100644
--- a/types/applepayjs/index.d.ts
+++ b/types/applepayjs/index.d.ts
@@ -1,26 +1,26 @@
-// Type definitions for Apple Pay JS 1.0
+// Type definitions for Apple Pay JS 3.0
// Project: https://developer.apple.com/reference/applepayjs
-// Definitions by: Martin Costello
+// Definitions by: Martin Costello
// 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,33 @@ 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;
/**
- * Call when a payment has been authorized.
- * @param status - The status of the payment.
+ * Completes the payment authorization with a result.
+ * @param result - The status of the payment, whether it succeeded or failed for Apple Pay JS versions 1 and 2,
+ * or the result of the payment authorization, including its status and list of errors for Apple Pay JS version 3.
*/
- completePayment(status: number): void;
+ completePayment(result: number | ApplePayJS.ApplePayPaymentAuthorizationResult): void;
/**
- * Call after a payment method has been selected.
+ * 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 +121,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 +182,78 @@ declare class ApplePaySession extends EventTarget {
}
declare namespace ApplePayJS {
+ /**
+ * Field names used for requesting contact information in a payment request.
+ */
+ type ApplePayContactField =
+ 'email' |
+ 'name' |
+ 'phone' |
+ 'postalAddress' |
+ '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.
+ */
+ type ApplePayErrorCode =
+ /**
+ * Shipping address or contact information is invalid or missing.
+ */
+ 'shippingContactInvalid' |
+
+ /**
+ * Billing address information is invalid or missing.
+ */
+ 'billingContactInvalid' |
+
+ /**
+ * The merchant cannot provide service to the shipping address (for example, can't deliver to a P.O. Box).
+ */
+ 'addressUnserviceable' |
+
+ /**
+ * An unknown but nonfatal error occurred during payment processing. The user can attempt authorization again.
+ */
+ 'unknown';
+
+ /**
+ * Names of the fields in the shipping or billing contact information, used to locate errors in the payment sheet.
+ */
+ type ApplePayErrorContactField =
+ 'phoneNumber' |
+ 'emailAddress' |
+ 'name' |
+ 'phoneticName' |
+ 'postalAddress' |
+ 'addressLines' |
+ 'locality' |
+ 'subLocality' |
+ 'postalCode' |
+ 'administrativeArea' |
+ 'subAdministrativeArea' |
+ 'country' |
+ 'countryCode';
+
/**
* Defines a line item in a payment request - for example, total, tax, discount, or grand total.
*/
@@ -180,15 +271,53 @@ declare namespace ApplePayJS {
/**
* A value that indicates if the line item is final or pending.
*/
- type?: string;
+ type?: ApplePayLineItemType;
}
+ /**
+ * A type that indicates whether a line item is final or pending.
+ */
+ type ApplePayLineItemType =
+ /**
+ * A line item representing the known, final cost.
+ */
+ 'final' |
+
+ /**
+ * A line item representing an estimated or unknown cost.
+ */
+ 'pending';
+
+ /**
+ * The payment capabilities supported by the merchant.
+ */
+ type ApplePayMerchantCapability =
+ /**
+ * Required. This value must be supplied.
+ */
+ 'supports3DS' |
+
+ /**
+ * Include this value only if you support China Union Pay transactions.
+ */
+ 'supportsEMV' |
+
+ /**
+ * Optional. If present, only transactions that are categorized as credit cards are allowed.
+ */
+ 'supportsCredit' |
+
+ /**
+ * Optional. If present, only transactions that are categorized as debit cards are allowed.
+ */
+ 'supportsDebit';
+
/**
* Represents the result of authorizing a payment request and contains encrypted payment information.
*/
interface ApplePayPayment {
/**
- * The encrypted token for an authorized payment.
+ * The encrypted information for an authorized payment.
*/
token: ApplePayPaymentToken;
@@ -208,11 +337,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.
*/
@@ -220,56 +364,76 @@ declare namespace ApplePayJS {
/**
* An email address for the contact.
*/
- emailAddress: string;
+ emailAddress?: string;
/**
* The contact's family name.
*/
- familyName: string;
+ familyName?: string;
/**
* The contact's given name.
*/
- givenName: string;
+ givenName?: string;
/**
* A phone number for the contact.
*/
- phoneNumber: string;
+ phoneNumber?: string;
/**
- * The address for the contact.
+ * The phonetic spelling of the contact's family name.
*/
- addressLines: string[];
+ phoneticFamilyName?: string;
+
+ /**
+ * The phonetic spelling of the contact's given name.
+ */
+ phoneticGivenName?: string;
+
+ /**
+ * The street portion of the address for the contact.
+ */
+ addressLines?: string[];
/**
* The city for the contact.
*/
- locality: string;
+ 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;
+ administrativeArea?: string;
/**
- * The zip code, where applicable, for the contact.
+ * The subadministrative area (such as a county or other region) in a postal address.
*/
- postalCode: string;
+ subAdministrativeArea?: string;
/**
- * The colloquial country name for the contact.
+ * The zip code or postal code, where applicable, for the contact.
*/
- country: string;
+ postalCode?: string;
/**
- * The contact's ISO country code.
+ * The name of the country for the contact.
*/
- countryCode: string;
+ country?: string;
+
+ /**
+ * 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 +443,29 @@ 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: 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.
+ */
+ type ApplePayPaymentMethodType =
+ 'debit' |
+ 'credit' |
+ 'prepaid' |
+ 'store';
+
/**
* The ApplePayPaymentMethodSelectedEvent class defines the attributes contained by the ApplePaySession.onpaymentmethodselected callback function.
*/
@@ -304,6 +476,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,9 +518,38 @@ declare namespace ApplePayJS {
/**
* The activation state of the pass.
*/
- activationState: string;
+ activationState: ApplePayPaymentPassActivationState;
}
+ /**
+ * Payment pass activation states.
+ */
+ type ApplePayPaymentPassActivationState =
+ /**
+ * Active and ready to be used for payment.
+ */
+ 'activated' |
+
+ /**
+ * Not active but may be activated by the issuer.
+ */
+ 'requiresActivation' |
+
+ /**
+ * Not ready for use but activation is in progress.
+ */
+ 'activating' |
+
+ /**
+ * Not active and can't be activated.
+ */
+ 'suspended' |
+
+ /**
+ * Not active because the issuer has disabled the account associated with the device.
+ */
+ 'deactivated';
+
/**
* Encapsulates a request for payment, including information about payment processing capabilities, the payment amount, and shipping information.
*/
@@ -357,7 +573,7 @@ declare namespace ApplePayJS {
* The payment capabilities supported by the merchant.
* The value must at least contain ApplePayMerchantCapability.supports3DS.
*/
- merchantCapabilities: string[];
+ merchantCapabilities: ApplePayMerchantCapability[];
/**
* The payment networks supported by the merchant.
@@ -377,12 +593,12 @@ declare namespace ApplePayJS {
/**
* The billing information that you require from the user in order to process the transaction.
*/
- requiredBillingContactFields?: string[];
+ requiredBillingContactFields?: ApplePayContactField[];
/**
* The shipping information that you require from the user in order to fulfill the order.
*/
- requiredShippingContactFields?: string[];
+ requiredShippingContactFields?: ApplePayContactField[];
/**
* Shipping contact information for the user.
@@ -397,7 +613,12 @@ declare namespace ApplePayJS {
/**
* How the items are to be shipped.
*/
- shippingType?: string;
+ shippingType?: ApplePayShippingType;
+
+ /**
+ * A list of ISO 3166 country codes for limiting payments to cards from specific countries.
+ */
+ supportedCountries?: string[];
/**
* Optional user-defined data.
@@ -406,7 +627,7 @@ declare namespace ApplePayJS {
}
/**
- * Contains the user's payment credentials.
+ * An object that contains the user's payment credentials.
*/
interface ApplePayPaymentToken {
/**
@@ -426,7 +647,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 +656,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 +717,35 @@ 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.
+ */
+ type ApplePayShippingType =
+ 'shipping' |
+ 'delivery' |
+ 'storePickup' |
+ '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;
}