How It Works
A deeper look at In-App Payments SDK
The In-App Payments SDK generates a single-use, encrypted payment token (nonce) from a customizable payment card entry view or digital wallet API. The nonce can be processed with Connect v2 APIs to take payments ( Payments API) and store a card on-file for future payments ( Customers API).
Note
See the Save Cards on File cookbook recipe for more information on creating a backend process that saves a card on file and uses the stored card for future purchases.
On this page
Overview
In-App Payments SDK supports payments on personal mobile devices by embedding a card entry form in a mobile app that produces nonces from customer-provided card information or digital wallet apps installed on the device. In-App Payments SDK can be used with mobile apps that are configured with a Square-assigned application ID from the Square Application Dashboard.
In-App Payments SDK must be initialized with a Square Application ID before it can be used to process payments. The general process for generating a payment nonce and completing payment on Android is outlined below.
The SDK process flow in Android
The SDK process flow on Android has 2 core flows: nonce generation and payment completion.
Nonce generation
The mobile app sets the Square application ID for In-App Payments SDK based on configuration information in AndroidManifest.xml.
The mobile app sets a card nonce background handler object reference for the In-App Payments SDK in
CardEntry
.The mobile app calls
CardEntry.startCardEntryActivity
to start the card entry activity and begin theCheckout
activity.The In-App Payments SDK collects user payment information, generates a nonce, and invokes the nonce background handler with the result.
The mobile app completes the card entry activity and gets the nonce from the background handler.
Payment completion
The mobile app sends the nonce returned by In-App Payments SDK and payment amount to a secure backend service.
The backend service creates a Payments API CreatePayment request with the provided nonce.
The Square Payments API CreatePayment endpoint processes the request and returns a Payment object that represents the captured payment.
The backend service returns an operation result with a status (
Finish
orShowError
). In the event of an error, the result should include actionable error information that can be logged or displayed.The nonce background handler in the mobile app receives the operation result:
In the case of
Finish
, the activity finishes itself and the calling activity forwards the call ofActivity.onActivityResult
to theCardEntry.onActivityResult
.In the case of
ShowError
, the app should display a localized description of the error and prompt users to edit their payment information and re-submit payment.
The mobile app handles the
CardEntryActivityResult
and runs appropriate business logic.
The SDK Process Flow in iOS
The SDK process flow on iOS has 2 core flows: nonce generation and payment completion.
Nonce generation
The mobile app uses an app delegate to set the Square application ID for In-App Payments SDK.
The mobile app creates an SDK theme object and sets UI style values on the theme.
The mobile app initializes an In-App Payments SDK card entry view controller with the theme from the previous step.
The mobile app sets the card entry view controller delegate.
The mobile app uses the app view controller to push the Card Entry view on to the navigation stack or present the Card Entry view controller modally.
The In-App Payments SDK collects user payment information with the Card Entry view, generates a nonce, and returns a nonce to the app view controller in a delegate method.
Payment completion
The nonce generation delegate method in the mobile app sends the nonce returned by In-App Payments SDK and payment amount to a secure backend service.
The backend service creates a Payments API Charge request with the provided nonce.
The Square Payments API CreatePayment endpoint processes the request and returns a Payment object that represents the captured payment.
The backend service returns an operation result with a status and, in the event of an error, actionable error information that can be logged or displayed.
The backend service returns an operation result with a status (
nil
) or an error that includes actionable information that can be logged or displayed.The app view controller of the mobile app calls the delegate completion handler with the operation result.
In the case of
nil
, the card entry view controller invokes thedidCompleteWithStatus
delegate.In the case of errors, the app should display a localized description of the error and prompt users to edit their payment information and re-submit payment.
The app view controller of the mobile app handles
didCompleteWithStatus
by dismissing the card entry view controller.