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
saves information about a user’s payment methods to a Stripe customer object, and requires an STPCustomerContext
to manage retrieving and modifying the customer.
-
This is a convenience initializer; it is equivalent to calling
initWithCustomerContext:customerContext configuration:[STPPaymentConfiguration sharedConfiguration] theme:[STPTheme defaultTheme]
.Declaration
Objective-C
- (nonnull instancetype)initWithCustomerContext: (nonnull STPCustomerContext *)customerContext;
Swift
init(customerContext: STPCustomerContext)
Parameters
customerContext
The customer context the payment context will use to fetch and modify its Stripe customer. - see: STPCustomerContext.h
Return Value
the newly-instantiated payment context
-
Initializes a new Payment Context with the provided customer context, configuration, and theme. After this class is initialized, you should also make sure to set its
delegate
andhostViewController
properties.See
STPPaymentConfiguration.hDeclaration
Objective-C
- (nonnull instancetype) initWithCustomerContext:(nonnull STPCustomerContext *)customerContext configuration:(nonnull STPPaymentConfiguration *)configuration theme:(nonnull STPTheme *)theme;
Swift
init(customerContext: STPCustomerContext, configuration: STPPaymentConfiguration, theme: STPTheme)
Parameters
customerContext
The customer context the payment context will use to fetch and modify its Stripe customer. - see: STPCustomerContext.h
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. - see: STPTheme.h
Return Value
the newly-instantiated payment context
-
Note: Instead of providing your own backend API adapter, we recommend using
STPCustomerContext
, which will manage retrieving and updating a Stripe customer for you. - see: STPCustomerContext.hThis 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)
-
Note: Instead of providing your own backend API adapter, we recommend using
STPCustomerContext
, which will manage retrieving and updating a Stripe customer for you. - see: STPCustomerContext.hInitializes 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
andhostViewController
properties.See
STPPaymentConfiguration.hDeclaration
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. - see: STPBackendAPIAdapter.h
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. - see: STPTheme.h
Return Value
the newly-instantiated payment context
-
Note: Instead of providing your own backend API adapter, we recommend using
STPCustomerContext
, which will manage retrieving and updating a Stripe customer for you. - see: STPCustomerContext.hThe 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.hDeclaration
Objective-C
@property (nonatomic, readonly) id<STPBackendAPIAdapter> _Nonnull apiAdapter;
Swift
var apiAdapter: STPBackendAPIAdapter { get }
-
The configuration for the payment context to use internally. - see: STPPaymentConfiguration.h
Declaration
Objective-C
@property (nonatomic, readonly) STPPaymentConfiguration *_Nonnull configuration;
Swift
var configuration: STPPaymentConfiguration { get }
-
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 (nonatomic, strong, readwrite, nullable) STPUserInformation *prefilledInformation;
Swift
var prefilledInformation: STPUserInformation? { get set }
-
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 (nonatomic, weak, readwrite, nullable) UIViewController *hostViewController;
Swift
weak var hostViewController: UIViewController? { get set }
-
This delegate will be notified when the payment context’s contents change. - see: STPPaymentContextDelegate
Declaration
Objective-C
@property (nonatomic, weak, readwrite, nullable) id<STPPaymentContextDelegate> delegate;
Swift
weak var delegate: STPPaymentContextDelegate? { get set }
-
Whether or not the payment context is currently loading information from the network.
Declaration
Objective-C
@property (nonatomic, readonly) BOOL loading;
Swift
var loading: Bool { get }
-
The user’s currently selected payment option. May be nil.
Declaration
Objective-C
@property (nonatomic, readonly, nullable) id<STPPaymentOption> selectedPaymentOption;
Swift
var selectedPaymentOption: STPPaymentOption? { get }
-
The available payment options the user can choose between. May be nil.
Declaration
Objective-C
@property (nonatomic, readonly, nullable) NSArray<id<STPPaymentOption>> *paymentOptions;
Swift
var paymentOptions: [STPPaymentOption]? { get }
-
The user’s currently selected shipping method. May be nil.
Declaration
Objective-C
@property (nonatomic, readonly, nullable) PKShippingMethod *selectedShippingMethod;
Swift
var selectedShippingMethod: PKShippingMethod? { get }
-
An array of STPShippingMethod objects that describe the supported shipping methods. May be nil.
Declaration
Objective-C
@property (nonatomic, readonly, nullable) NSArray<PKShippingMethod *> *shippingMethods;
Swift
var shippingMethods: [PKShippingMethod]? { get }
-
The user’s shipping address. May be nil. If you’ve already collected a shipping address from your user, you may prefill it by setting a shippingAddress in PaymentContext’s prefilledInformation. When your user enters a new shipping address, PaymentContext will save it to the current customer object. When PaymentContext loads, if you haven’t manually set a prefilled value, any shipping information saved on the customer will be used to prefill the shipping address form. Note that because your customer’s email may not be the same as the email provided with their shipping info, PaymentContext will not prefill the shipping form’s email using your customer’s email.
You should not rely on the shipping information stored on the Stripe customer for order fulfillment, as your user may change this information if they make multiple purchases. We recommend adding shipping information when you create a charge (which can also help prevent fraud), or saving it to your own database. https://stripe.com/docs/api#create_charge-shipping
Note: by default, your user will still be prompted to verify a prefilled shipping address. To change this behavior, you can set
verifyPrefilledShippingAddress
to NO in yourSTPPaymentConfiguration
.Declaration
Objective-C
@property (nonatomic, readonly, nullable) STPAddress *shippingAddress;
Swift
var shippingAddress: STPAddress? { get }
-
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
Note
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 yourpaymentCurrency
.Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite) NSInteger paymentAmount;
Swift
var paymentAmount: Int { get set }
-
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 ofpaymentAmount
orpaymentSummaryItems
(whichever one you didn’t directly set yourself).Declaration
Objective-C
@property (nonatomic, copy, readwrite) NSString *_Nonnull paymentCurrency;
Swift
var paymentCurrency: String { get set }
-
The two-letter country code for the country where the payment will be processed. You should set this to the country your Stripe account is in. Defaults to “US”.
Note
Changing this property will change thecountryCode
of your Apple Pay payment requests.See
PKPaymentRequest for more information.Declaration
Objective-C
@property (nonatomic, copy, readwrite) NSString *_Nonnull paymentCountry;
Swift
var paymentCountry: String { get set }
-
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 usingpaymentAmount
and your configuration’scompanyName
.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 yourpaymentCurrency.
Declaration
Objective-C
@property (nonatomic, copy, readwrite) NSArray<PKPaymentSummaryItem *> *_Nonnull paymentSummaryItems;
Swift
var paymentSummaryItems: [PKPaymentSummaryItem] { get set }
-
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
, orUIModalPresentationFormSheet
. The default value isUIModalPresentationFullScreen
.Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite) UIModalPresentationStyle modalPresentationStyle;
Swift
var modalPresentationStyle: UIModalPresentationStyle { get set }
-
The mode to use when displaying the title of the navigation bar in all view controllers presented by the context. The default value is
automatic
, which causes the title to use the same styling as the previously displayed navigation item (if the view controller is pushed onto thehostViewController
).If the
prefersLargeTitles
property of thehostViewController
‘s navigation bar is false, this property has no effect and the navigation item’s title is always displayed as a small title.If the view controller is presented modally,
automatic
andnever
always result in a navigation bar with a small title.Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite) UINavigationItemLargeTitleDisplayMode largeTitleDisplayMode;
Swift
var largeTitleDisplayMode: UINavigationItem.LargeTitleDisplayMode { get set }
-
A view that will be placed as the footer of the payment options selection view controller.
When the footer view needs to be resized, it will be sent a
sizeThatFits:
call. The view should respond correctly to this method in order to be sized and positioned properly.Declaration
Objective-C
@property (nonatomic, strong, readwrite) UIView *_Nonnull paymentOptionsViewControllerFooterView;
Swift
var paymentOptionsViewControllerFooterView: UIView { get set }
-
A view that will be placed as the footer of the add card view controller.
When the footer view needs to be resized, it will be sent a
sizeThatFits:
call. The view should respond correctly to this method in order to be sized and positioned properly.Declaration
Objective-C
@property (nonatomic, strong, readwrite) UIView *_Nonnull addCardViewControllerFooterView;
Swift
var addCardViewControllerFooterView: UIView { get set }
-
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()
-
This creates, configures, and appropriately presents an
STPPaymentOptionsViewController
on top of the payment context’shostViewController
. 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)presentPaymentOptionsViewController;
Swift
func presentPaymentOptionsViewController()
-
This creates, configures, and appropriately pushes an
STPPaymentOptionsViewController
onto the navigation stack of the context’shostViewController
. 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)pushPaymentOptionsViewController;
Swift
func pushPaymentOptionsViewController()
-
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()
-
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()
-
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, thepaymentContext:didCreatePaymentResult:completion:
andpaymentContext:didFinishWithStatus:error:
methods will be called on the context’sdelegate
.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()