[Breaking] Adds async APIs to STPApplePayContext and ApplePayConfiguration

Author: yuki-stripe

CHANGELOG_v25_draft.md

@@ -0,0 +1,9 @@
+## 25.0.0 2025-XX-YY
+### PaymentSheet
+* [Changed] Replaces `PaymentSheet.ApplePayConfiguration.Handlers` completion-block based `authorizationResultHandler` with an async equivalent.
+
+### STPApplePayContext
+* [Added] Added async delegate methods.
+* [Changed] Replaces the `ApplePayContextDelegate.didCreatePaymentMethod` method with an async version.
+
+

Example/PaymentSheet Example/PaymentSheet Example/PlaygroundController.swift

@@ -57,16 +57,15 @@ class PlaygroundController: ObservableObject {
                     request.paymentSummaryItems = [billing]
                     return request
                 },
-                authorizationResultHandler: { result, completion in
-                    //                  Hardcoded order details:
-                    //                  In a real app, you should fetch these details from your service and call the completion() block on
-                    //                  the main queue.
+                authorizationResultHandler: { result in
+                    // Hardcoded order details:
+                    // In a real app, you should fetch these details from your service
                     result.orderDetails = PKPaymentOrderDetails(
                         orderTypeIdentifier: "com.myapp.order",
                         orderIdentifier: "ABC123-AAAA-1111",
                         webServiceURL: URL(string: "https://my-backend.example.com/apple-order-tracking-backend")!,
                         authenticationToken: "abc123")
-                    completion(result)
+                    return result
                 }
             )
             return PaymentSheet.ApplePayConfiguration(

MIGRATING_v25_draft.md

@@ -0,0 +1,53 @@
+#### PaymentSheet
+`PaymentSheet.ApplePayConfiguration.Handlers` completion-block based `authorizationResultHandler` has been replaced by an async equivalent. You can use the following example to quickly migrate completion-block based code:
+
+```
+// Before:
+authorizationResultHandler: { result in
+  return await withCheckedThrowingContinuation { continuation in
+    let modifiedResult = // ...modify result (details omitted)
+    continuation.resume(returning: modifiedResult)
+  }
+}
+
+// After:
+authorizationResultHandler: { result, completion in
+  // ...modify result (details omitted)
+  completion(result)
+}
+```
+
+#### STPApplePayContext
+ApplePayContextDelegate's `applePayContext:didCreatePaymentMethod:paymentInformation:completion:` has been replaced by an async equivalent. You can use the following example to quickly migrate completion-block based code:
+
+```
+// Before:
+func applePayContext(
+    _ context: STPApplePayContext,
+    didCreatePaymentMethod paymentMethod: StripeAPI.PaymentMethod,
+    paymentInformation: PKPayment,
+    completion: @escaping STPIntentClientSecretCompletionBlock
+) {
+  MyExampleNetworkManager.getPaymentIntent() { paymentIntentClientSecret in
+    completion("my client secret", nil)
+  }
+}
+
+// After:
+func applePayContext(
+    _ context: STPApplePayContext,
+    didCreatePaymentMethod paymentMethod: StripeAPI.PaymentMethod,
+    paymentInformation: PKPayment
+) async throws -> String {
+   return try await withCheckedThrowingContinuation { continuation in
+     MyExampleNetworkManager.getPaymentIntent() { paymentIntentClientSecret, error in
+        if let error {
+          continuation.resume(throwing: error)
+        } else {
+          continuation.resume(returning: paymentIntentClientSecret)
+        }
+     }
+   }
+}
+```
+

Stripe/StripeiOSTests/STPApplePayContextFunctionalTest.swift

@@ -360,17 +360,16 @@ class STPApplePayContextFunctionalTest: STPNetworkStubbingTestCase {
         // When the user taps 'Pay', PKPaymentAuthorizationController calls `didAuthorizePayment:completion:`
         // After you call its completion block, it calls `paymentAuthorizationControllerDidFinish:`
         let didCallAuthorizePaymentCompletion = expectation(description: "ApplePayContext called completion block of paymentAuthorizationController:didAuthorizePayment:completion:")
-        if let authorizationController = context?.authorizationController {
-            context?.paymentAuthorizationController(authorizationController, didAuthorizePayment: STPFixtures.simulatorApplePayPayment(), handler: { [self] result in
-                XCTAssertEqual(expectedStatus, result.status)
-                DispatchQueue.main.async(execute: { [self] in
-                    if let authorizationController = context?.authorizationController {
-                        context?.paymentAuthorizationControllerDidFinish(authorizationController)
-                    }
-                    didCallAuthorizePaymentCompletion.fulfill()
-                })
+        let authorizationController = context!.authorizationController!
+        context?.paymentAuthorizationController(authorizationController, didAuthorizePayment: STPFixtures.simulatorApplePayPayment(), handler: { [self] result in
+            XCTAssertEqual(expectedStatus, result.status)
+            DispatchQueue.main.async(execute: { [self] in
+                if let authorizationController = context?.authorizationController {
+                    context?.paymentAuthorizationControllerDidFinish(authorizationController)
+                }
+                didCallAuthorizePaymentCompletion.fulfill()
             })
-        }
+        })
     }
 }
 
@@ -380,3 +379,119 @@ class STPTestPKPaymentAuthorizationController: PKPaymentAuthorizationController
         completion?()
     }
 }
+
+// MARK: - Async delegate methods
+// Keeps track of which async delegate methods have been called
+class TestAsyncApplePayContextDelegate: NSObject, ApplePayContextDelegate {
+    enum AsyncDelegateMethods {
+        case didCreatePaymentMethod
+        case didSelectShippingMethod
+        case didSelectShippingContact
+        case didChangeCouponCode
+        case willCompleteWithResult
+        case didCompleteWithStatus
+    }
+
+    var delegateMethodsCalled: [AsyncDelegateMethods] = []
+
+    func applePayContext(
+        _ context: StripeApplePay.STPApplePayContext,
+        didCreatePaymentMethod paymentMethod: StripeCore.StripeAPI.PaymentMethod,
+        paymentInformation: PKPayment
+    ) async throws -> String {
+        delegateMethodsCalled.append(.didCreatePaymentMethod)
+        return "pi_bad_secret_1234"
+    }
+
+    func applePayContext(
+        _ context: StripeApplePay.STPApplePayContext,
+        didSelectShippingContact contact: PKContact
+    ) async -> PKPaymentRequestShippingContactUpdate {
+        delegateMethodsCalled.append(.didSelectShippingContact)
+        return .init()
+    }
+
+    func applePayContext(
+        _ context: STPApplePayContext,
+        didSelect shippingMethod: PKShippingMethod
+    ) async -> PKPaymentRequestShippingMethodUpdate {
+        delegateMethodsCalled.append(.didSelectShippingMethod)
+        return .init()
+    }
+
+    @available(iOS 15.0, *)
+    func applePayContext(
+        _ context: STPApplePayContext,
+        didChangeCouponCode couponCode: String
+    ) async -> PKPaymentRequestCouponCodeUpdate {
+        delegateMethodsCalled.append(.didChangeCouponCode)
+        return .init()
+    }
+
+    func applePayContext(
+        _ context: STPApplePayContext,
+        willCompleteWithResult authorizationResult: PKPaymentAuthorizationResult
+    ) async -> PKPaymentAuthorizationResult {
+        delegateMethodsCalled.append(.willCompleteWithResult)
+        return authorizationResult
+    }
+
+    func applePayContext(_ context: StripeApplePay.STPApplePayContext, didCompleteWith status: StripeApplePay.STPApplePayContext.PaymentStatus, error: (any Error)?) {
+        delegateMethodsCalled.append(.didCompleteWithStatus)
+    }
+}
+
+extension STPApplePayContextFunctionalTest {
+    func testAsyncDelegateMethodsCalled() {
+        let delegate = TestAsyncApplePayContextDelegate()
+        let request = StripeAPI.paymentRequest(
+            withMerchantIdentifier: "foo",
+            country: "US",
+            currency: "USD"
+        )
+        request.paymentSummaryItems = [
+            PKPaymentSummaryItem(label: "bar", amount: NSDecimalNumber(string: "1.00")),
+        ]
+        self.context = STPApplePayContext(paymentRequest: request, delegate: delegate)!
+        context.apiClient = apiClient
+        _startApplePayForContext(withExpectedStatus: .failure)
+        waitForExpectations(timeout: 50)
+        XCTAssertEqual(delegate.delegateMethodsCalled, [.didCreatePaymentMethod, .willCompleteWithResult])
+        delegate.delegateMethodsCalled = []
+
+        // Now test that the 3 optional async methods get called:
+        let e1 = expectation(description: "didSelectShippingMethod")
+        XCTAssertTrue(context.responds(to: #selector((PKPaymentAuthorizationControllerDelegate.paymentAuthorizationController(_:didSelectShippingMethod:handler:)))))
+        context.paymentAuthorizationController(
+            context.authorizationController!,
+            didSelectShippingMethod: .init()
+        ) { _ in
+            e1.fulfill()
+        }
+        // didSelectShippingContact should be called
+        let e2 = expectation(description: "didSelectShippingContact")
+        XCTAssertTrue(context.responds(to: #selector(PKPaymentAuthorizationControllerDelegate.paymentAuthorizationController(_:didSelectShippingContact:handler:))))
+        context.paymentAuthorizationController(
+            context.authorizationController!,
+            didSelectShippingContact: .init()
+        ) { _ in
+            e2.fulfill()
+        }
+
+        // didChangeCouponCode should be called
+        if #available(iOS 15.0, *) {
+            let e3 = expectation(description: "didChangeCouponCode")
+            XCTAssertTrue(context.responds(to: #selector(PKPaymentAuthorizationControllerDelegate.paymentAuthorizationController(_:didChangeCouponCode:handler:))))
+            context.paymentAuthorizationController(
+                context.authorizationController!,
+                didChangeCouponCode: .init()
+            ) { _ in
+                e3.fulfill()
+            }
+        } else {
+            // Fallback on earlier versions
+        }
+        waitForExpectations(timeout: 3)
+        XCTAssertEqual(delegate.delegateMethodsCalled, [.didCompleteWithStatus, .didSelectShippingMethod, .didSelectShippingContact, .didChangeCouponCode])
+    }
+}