In-App Payments SDK

How It Works

A deeper look at In-App Payments SDK

Android
iOS
UI
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.

Overview
Permalink Get a link to this section

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
Permalink Get a link to this section

The SDK process flow on Android has 2 core flows: nonce generation and payment completion.

Nonce generation
Permalink Get a link to this section

  1. The mobile app sets the Square application ID for In-App Payments SDK based on configuration information in AndroidManifest.xml.

  2. The mobile app sets a card nonce background handler object reference for the In-App Payments SDK in CardEntry.

  3. The mobile app 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 nonce, and invokes the nonce background handler with the result.

  5. The mobile app completes the card entry activity and gets the nonce from the background handler.

Payment completion
Permalink Get a link to this section

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

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

  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 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 of Activity.onActivityResult to the CardEntry.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.

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


android-process-flow

The SDK Process Flow in iOS
Permalink Get a link to this section

The SDK process flow on iOS has 2 core flows: nonce generation and payment completion.

Nonce generation
Permalink Get a link to this section

  1. The mobile app uses an app delegate to set the Square application ID for In-App Payments SDK.

  2. The mobile app creates an SDK theme object and sets UI style values on the theme.

  3. The mobile app initializes an In-App Payments SDK card entry view controller with the theme from the previous step.

  4. The mobile app sets the card entry view controller delegate.

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

  6. 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
Permalink Get a link to this section

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

  2. The backend service creates a Payments API Charge request with the provided nonce.

  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 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 the didCompleteWithStatus 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.

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


ios-process-flow