In-App Payments SDK

How It Works

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 Square APIs to take payments (Payments API) and store a card on-file for future payments (Customers API). For more information about creating a backend process that saves a card on file and uses the stored card for future purchases, see Save Cards on File.

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 application that produces nonces from customer-provided card information or digital wallet applications installed on the device. In-App Payments SDK can be used with mobile applications that are configured with a Square-assigned application ID from the Square Developer 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 a payment on Android is outlined in the following sections.

SDK process flow on Android Permalink Get a link to this section

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

Nonce generation Permalink Get a link to this section

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

  2. The mobile application sets a card nonce background handler object reference for 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. In-App Payments SDK collects user payment information, generates a nonce, and invokes the nonce background handler with the result.

  5. The mobile application 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 application sends the nonce returned by 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 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 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 buyer's to edit their payment information and resubmit the payment.

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

    android-process-flow

SDK process flow on iOS Permalink Get a link to this section

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

Nonce generation Permalink Get a link to this section

  1. The mobile application uses an application delegate to set the Square application ID for 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. In-App Payments SDK collects user payment information with the Card Entry view, generates a nonce, and returns a nonce to the application view controller in a delegate method.

Payment completion Permalink Get a link to this section

  1. The nonce generation delegate method in the mobile application sends the nonce returned by In-App Payments SDK and the 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 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.

    ios-process-flow