STPPaymentContext

@interface STPPaymentContext : NSObject

An STPPaymentContext keeps track of all of the state around a payment. It will manage fetching a user’s saved payment methods, tracking any information they select, and prompting them for required additional information before completing their purchase. It can be used to power your application’s payment confirmation page with just a few lines of code.

STPPaymentContext also provides a unified interface to multiple payment methods - for example, you can write a single integration to accept both credit card payments and Apple Pay.

STPPaymentContext requires an API Adapter to communicate with your backend API to retrieve and modify a customer’s payment methods - see https://stripe.com/docs/mobile/ios/standard#prepare-your-api for how to implement this. You can also look at CheckoutViewController.swift in our example app to see STPPaymentContext in action.

  • This is a convenience initializer; it is equivalent to calling initWithAPIAdapter:apiAdapter configuration:[STPPaymentConfiguration sharedConfiguration] theme:[STPTheme defaultTheme].

    Declaration

    Objective-C

    - (nonnull instancetype)initWithAPIAdapter:
    (nonnull id<STPBackendAPIAdapter>)apiAdapter;

    Swift

    init(apiAdapter: STPBackendAPIAdapter)
    Show on GitHub

  • Initializes a new Payment Context with the provided API adapter and configuration. After this class is initialized, you should also make sure to set its delegate and hostViewController properties.

    Declaration

    Objective-C

    - (nonnull instancetype)
initWithAPIAdapter:(nonnull id<STPBackendAPIAdapter>)apiAdapter
     configuration:(nonnull STPPaymentConfiguration *)configuration
             theme:(nonnull STPTheme *)theme;

    Swift

    init(apiAdapter: STPBackendAPIAdapter, configuration: STPPaymentConfiguration, theme: STPTheme)

    Parameters

    apiAdapter

    The API adapter the payment context will use to fetch and modify its contents. You need to make a class conforming to this protocol that talks to your server.

    configuration

    The configuration for the payment context to use. This lets you set your Stripe publishable API key, required billing address fields, etc.

    theme

    The theme describing the visual appearance of all UI that the payment context automatically creates for you.

    Return Value

    the newly-instantiated payment context

    Show on GitHub

  • The API adapter the payment context will use to fetch and modify its contents. You need to make a class conforming to this protocol that talks to your server. - see: STPBackendAPIAdapter.h

    Declaration

    Objective-C

    @property (readonly, nonatomic) id<STPBackendAPIAdapter> _Nonnull apiAdapter;

    Swift

    var apiAdapter: STPBackendAPIAdapter { get }
    Show on GitHub

  • The configuration for the payment context to use internally. - see: STPPaymentConfiguration.h

    Declaration

    Objective-C

    @property (readonly, nonatomic) STPPaymentConfiguration *_Nonnull configuration;

    Swift

    var configuration: STPPaymentConfiguration { get }
    Show on GitHub

  • The visual appearance that will be used by any views that the context generates. - see: STPTheme.h

    Declaration

    Objective-C

    @property (readonly, nonatomic) STPTheme *_Nonnull theme;

    Swift

    var theme: STPTheme { get }
    Show on GitHub

  • If you’ve already collected some information from your user, you can set it here and it’ll be automatically filled out when possible/appropriate in any UI that the payment context creates.

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic, nullable)
    STPUserInformation *prefilledInformation;

    Swift

    var prefilledInformation: STPUserInformation? { get set }
    Show on GitHub

  • The view controller that any additional UI will be presented on. If you have a checkout view controller in your app, that should be used as the host view controller.

    Declaration

    Objective-C

    @property (readwrite, nonatomic, nullable) UIViewController *hostViewController;
    Show on GitHub

  • This delegate will be notified when the payment context’s contents change. - see: STPPaymentContextDelegate

    Declaration

    Objective-C

    @property (readwrite, nonatomic, nullable) id<STPPaymentContextDelegate>
    delegate;

    Swift

    weak var delegate: STPPaymentContextDelegate? { get set }
    Show on GitHub

  • Whether or not the payment context is currently loading information from the network.

    Declaration

    Objective-C

    @property (readonly, nonatomic) BOOL loading;

    Swift

    var loading: Bool { get }
    Show on GitHub

  • The user’s currently selected payment method. May be nil.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) id<STPPaymentMethod>
    selectedPaymentMethod;

    Swift

    var selectedPaymentMethod: STPPaymentMethod? { get }
    Show on GitHub

  • The available payment methods the user can choose between. May be nil.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable)
    NSArray<id<STPPaymentMethod>> *paymentMethods;

    Swift

    var paymentMethods: [STPPaymentMethod]? { get }
    Show on GitHub

  • The user’s currently selected shipping method. May be nil.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable)
    PKShippingMethod *selectedShippingMethod;

    Swift

    var selectedShippingMethod: UnsafeMutablePointer
    Show on GitHub

  • An array of STPShippingMethod objects that describe the supported shipping methods. May be nil.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable)
    NSArray<PKShippingMethod *> *shippingMethods;

    Swift

    var shippingMethods: [Any]? { get }
    Show on GitHub

  • The user’s shipping address. May be nil.

    Declaration

    Objective-C

    @property (readonly, nonatomic, nullable) STPAddress *shippingAddress;

    Swift

    var shippingAddress: STPAddress? { get }
    Show on GitHub

  • The amount of money you’re requesting from the user, in the smallest currency unit for the selected currency. For example, to indicate $10 USD, use 1000 (i.e. 1000 cents). For more information see https://stripe.com/docs/api#charge_object-amount . This value must be present and greater than zero in order for Apple Pay to be automatically enabled.

    Note

    You should only set either this or paymentSummaryItems, not both. The other will be automatically calculated on demand using your paymentCurrency.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSInteger paymentAmount;

    Swift

    var paymentAmount: Int { get set }
    Show on GitHub

  • The three-letter currency code for the currency of the payment (i.e. USD, GBP, JPY, etc). Defaults to USD.

    Note

    Changing this property may change the return value of paymentAmount or paymentSummaryItems (whichever one you didn’t directly set yourself).

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic) NSString *_Nonnull paymentCurrency;

    Swift

    var paymentCurrency: String { get set }
    Show on GitHub

  • If you support Apple Pay, you can optionally set the PKPaymentSummaryItems you want to display here instead of using paymentAmount. Note that the grand total (the amount of the last summary item) must be greater than zero. If not set, a single summary item will be automatically generated using paymentAmount and your configuration’s companyName. - see: PKPaymentRequest for more information

    Note

    You should only set either this or paymentAmount, not both. The other will be automatically calculated on demand using your paymentCurrency.

    Warning

    PKPaymentSummaryItem is only available in iOS8+. If you support iOS 7 you should do a runtime availability check before accessing or setting this property.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic)
    NSArray<PKPaymentSummaryItem *> *_Nonnull paymentSummaryItems;
    Show on GitHub

  • The presentation style used for all view controllers presented modally by the context. Since custom transition styles are not supported, you should set this to either UIModalPresentationFullScreen, UIModalPresentationPageSheet, or UIModalPresentationFormSheet. The default value is UIModalPresentationFullScreen.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic)
    UIModalPresentationStyle modalPresentationStyle;

    Swift

    var modalPresentationStyle: Int32 { get set }
    Show on GitHub

  • If paymentContext:didFailToLoadWithError: is called on your delegate, you can in turn call this method to try loading again (if that hasn’t been called, calling this will do nothing). If retrying in turn fails, paymentContext:didFailToLoadWithError: will be called again (and you can again call this to keep retrying, etc).

    Declaration

    Objective-C

    - (void)retryLoading;

    Swift

    func retryLoading()
    Show on GitHub

  • This creates, configures, and appropriately presents an STPPaymentMethodsViewController on top of the payment context’s hostViewController. It’ll be dismissed automatically when the user is done selecting their payment method.

    Note

    This method will do nothing if it is called while STPPaymentContext is already showing a view controller or in the middle of requesting a payment.

    Declaration

    Objective-C

    - (void)presentPaymentMethodsViewController;

    Swift

    func presentPaymentMethodsViewController()
    Show on GitHub

  • This creates, configures, and appropriately pushes an STPPaymentMethodsViewController onto the navigation stack of the context’s hostViewController. It’ll be popped automatically when the user is done selecting their payment method.

    Note

    This method will do nothing if it is called while STPPaymentContext is already showing a view controller or in the middle of requesting a payment.

    Declaration

    Objective-C

    - (void)pushPaymentMethodsViewController;

    Swift

    func pushPaymentMethodsViewController()
    Show on GitHub

  • This creates, configures, and appropriately presents a view controller for collecting shipping address and shipping method on top of the payment context’s hostViewController. It’ll be dismissed automatically when the user is done entering their shipping info.

    Note

    This method will do nothing if it is called while STPPaymentContext is already showing a view controller or in the middle of requesting a payment.

    Declaration

    Objective-C

    - (void)presentShippingViewController;

    Swift

    func presentShippingViewController()
    Show on GitHub

  • This creates, configures, and appropriately pushes a view controller for collecting shipping address and shipping method onto the navigation stack of the context’s hostViewController. It’ll be popped automatically when the user is done entering their shipping info.

    Note

    This method will do nothing if it is called while STPPaymentContext is already showing a view controller, or in the middle of requesting a payment.

    Declaration

    Objective-C

    - (void)pushShippingViewController;

    Swift

    func pushShippingViewController()
    Show on GitHub

  • Requests payment from the user. This may need to present some supplemental UI to the user, in which case it will be presented on the payment context’s hostViewController. For instance, if they’ve selected Apple Pay as their payment method, calling this method will show the payment sheet. If the user has a card on file, this will use that without presenting any additional UI. After this is called, the paymentContext:didCreatePaymentResult:completion: and paymentContext:didFinishWithStatus:error: methods will be called on the context’s delegate.

    Note

    This method will do nothing if it is called while STPPaymentContext is already showing a view controller, or in the middle of requesting a payment.

    Declaration

    Objective-C

    - (void)requestPayment;

    Swift

    func requestPayment()
    Show on GitHub