How It Works

The In-App Payments SDK generates a one-time-use, encrypted payment token from a customizable payment card entry view or digital wallet API. The payment token can be processed with Square APIs to take payments (Payments API) and store a card on file for future payments (Cards API). For more information about creating a backend process that saves a card on file for future purchases, see Create a Card on File from a Payment ID, Create a Card on File and a Payment, and Create a Shared Card on File and Make a Payment.

The In-App Payments SDK supports payments on personal mobile devices by embedding a card entry form in a mobile application that produces payment tokens from customer-provided card information or digital wallet applications installed on the device. The In-App Payments SDK can be used with mobile applications that are configured with a Square-assigned application ID from the Developer Dashboard.

The 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 token and completing a payment on Android is outlined in the following sections.

The SDK process flow on Android has two core flows: payment token generation and payment completion.

1. The mobile application sets the Square application ID for the In-App Payments SDK based on configuration information in AndroidManifest.xml.
2. The mobile application sets a card payment token background handler object reference for the In-App Payments SDK in CardEntry.
3. The mobile application calls CardEntry.startCardEntryActivity to start the card entry activity and begin the Checkout activity.
4. The In-App Payments SDK collects user payment information, generates a payment token, and invokes the payment token background handler with the result.
5. The mobile application completes the card entry activity and gets the payment token from the background handler.

1. The mobile application sends the payment token returned by the In-App Payments SDK and the payment amount to a secure backend service.

2. The backend service creates a Payments API CreatePayment request with the provided payment token.

3. The Square Payments API CreatePayment endpoint processes the request and returns a Payment object that represents the captured payment.

4. The backend service returns an operation result with a status (Finish or ShowError). In the event of an error, the result should include actionable error information that can be logged or displayed.

5. The payment token background handler in the mobile application receives the operation result:

   • In the case of Finish, the activity finishes itself and the calling activity forwards the call of Activity.onActivityResult to CardEntry.onActivityResult.
   • In the case of ShowError, the application should display a localized description of the error and prompt buyers to edit their payment information and resubmit the payment.

6. The mobile application handles CardEntryActivityResult and runs the appropriate business logic.

   

The SDK process flow on iOS has two core flows: payment token generation and payment completion.

1. The mobile application uses an application delegate to set the Square application ID for the In-App Payments SDK.
2. The mobile application creates an SDK theme object and sets UI style values on the theme.
3. The mobile application initializes an In-App Payments SDK card entry view controller with the theme from the previous step.
4. The mobile application sets the card entry view controller delegate.
5. The mobile application uses the application view controller to push the card entry view on to the navigation stack or present the card entry view controller modally.
6. The In-App Payments SDK collects user payment information with the card entry view, generates a payment token, and returns a payment token to the application view controller in a delegate method.

1. The payment token generation delegate method in the mobile application sends the payment token returned by the In-App Payments SDK and the payment amount to a secure backend service.

2. The backend service creates a Payments API CreatePayment request with the provided payment token.

3. The Square Payments API CreatePayment endpoint processes the request and returns a Payment object that represents the captured payment.

4. 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.

5. The backend service returns an operation result with a status (nil) or an error that includes actionable information that can be logged or displayed.

6. The application view controller of the mobile application calls the delegate completion handler with the operation result:

   • In the case of nil, the card entry view controller invokes the didCompleteWithStatus delegate.
   • In the case of errors, the application should display a localized description of the error and prompt users to edit their payment information and resubmit the payment.

7. The application view controller of the mobile application handles didCompleteWithStatus by dismissing the card entry view controller.