STPPaymentContextDelegate

@protocol STPPaymentContextDelegate <NSObject>

Implement STPPaymentContextDelegate to get notified when a payment context changes, finishes, encounters errors, etc. In practice, if your app has a checkout screen view controller, that is a good candidate to implement this protocol.

  • Called when the payment context encounters an error when fetching its initial set of data. A few ways to handle this are:

    • If you’re showing the user a checkout page, dismiss the checkout page when this is called and present the error to the user.
    • Present the error to the user using a UIAlertController with two buttons: Retry and Cancel. If they cancel, dismiss your UI. If they Retry, call retryLoading on the payment context.

    To make it harder to get your UI into a bad state, this won’t be called until the context’s hostViewController has finished appearing.

    Declaration

    Objective-C

    - (void)paymentContext:(nonnull STPPaymentContext *)paymentContext
        didFailToLoadWithError:(nonnull NSError *)error;

    Swift

    func paymentContext(_ paymentContext: STPPaymentContext, didFailToLoadWithError error: Error)

    Parameters

    paymentContext

    the payment context that encountered the error

    error

    the error that was encountered

  • This is called every time the contents of the payment context change. When this is called, you should update your app’s UI to reflect the current state of the payment context. For example, if you have a checkout page with a selected payment method row, you should update its payment method with paymentContext.selectedPaymentOption.label. If that checkout page has a buy button, you should enable/disable it depending on the result of [paymentContext isReadyForPayment].

    Declaration

    Objective-C

    - (void)paymentContextDidChange:(nonnull STPPaymentContext *)paymentContext;

    Swift

    func paymentContextDidChange(_ paymentContext: STPPaymentContext)

    Parameters

    paymentContext

    the payment context that changed

  • Inside this method, you should make a call to your backend API to make a PaymentIntent with that Customer + payment method, and invoke the completion block when that is done.

    Declaration

    Objective-C

    - (void)paymentContext:(nonnull STPPaymentContext *)paymentContext
        didCreatePaymentResult:(nonnull STPPaymentResult *)paymentResult
                    completion:(nonnull STPPaymentStatusBlock)completion;

    Swift

    func paymentContext(_ paymentContext: STPPaymentContext, didCreatePaymentResult paymentResult: STPPaymentResult, completion: @escaping STPPaymentStatusBlock)

    Parameters

    paymentContext

    The context that succeeded

    paymentResult

    Information associated with the payment that you can pass to your server. You should go to your backend API with this payment result and use the PaymentIntent API to complete the payment. See https://stripe.com/docs/mobile/ios/standard#submit-payment-intents. Once that’s done call the completion block with any error that occurred (or none, if the payment succeeded). - see: STPPaymentResult.h

    completion

    Call this block when you’re done creating a payment intent (or subscription, etc) on your backend. If it succeeded, call completion(STPPaymentStatusSuccess, nil). If it failed with an error, call completion(STPPaymentStatusError, error). If the user canceled, call completion(STPPaymentStatusUserCancellation, nil).

  • This is invoked by an STPPaymentContext when it is finished. This will be called after the payment is done and all necessary UI has been dismissed. You should inspect the returned status and behave appropriately. For example: if it’s STPPaymentStatusSuccess, show the user a receipt. If it’s STPPaymentStatusError, inform the user of the error. If it’s STPPaymentStatusUserCancellation, do nothing.

    Declaration

    Objective-C

    - (void)paymentContext:(nonnull STPPaymentContext *)paymentContext
        didFinishWithStatus:(STPPaymentStatus)status
                      error:(nullable NSError *)error;

    Swift

    func paymentContext(_ paymentContext: STPPaymentContext, didFinishWith status: STPPaymentStatus, error: Error?)

    Parameters

    paymentContext

    The payment context that finished

    status

    The status of the payment - STPPaymentStatusSuccess if it succeeded, STPPaymentStatusError if it failed with an error (in which case the error parameter will be non-nil), STPPaymentStatusUserCancellation if the user canceled the payment.

    error

    An error that occurred, if any.

  • Inside this method, you should verify that you can ship to the given address. You should call the completion block with the results of your validation and the available shipping methods for the given address. If you don’t implement this method, the user won’t be prompted to select a shipping method and all addresses will be valid. If you call the completion block with nil or an empty array of shipping methods, the user won’t be prompted to select a shipping method.

    Note

    If a user updates their shipping address within the Apple Pay dialog, this address will be anonymized. For example, in the US, it will only include the city, state, and zip code. The payment context will have the user’s complete shipping address by the time paymentContext:didFinishWithStatus:error is called.

    Declaration

    Objective-C

    - (void)paymentContext:(nonnull STPPaymentContext *)paymentContext
        didUpdateShippingAddress:(nonnull STPAddress *)address
                      completion:
                          (nonnull STPShippingMethodsCompletionBlock)completion;

    Swift

    optional func paymentContext(_ paymentContext: STPPaymentContext, didUpdateShippingAddress address: STPAddress, completion: @escaping STPShippingMethodsCompletionBlock)

    Parameters

    paymentContext

    The context that updated its shipping address

    address

    The current shipping address

    completion

    Call this block when you’re done validating the shipping address and calculating available shipping methods. If you call the completion block with nil or an empty array of shipping methods, the user won’t be prompted to select a shipping method.