Take a Payment

Payments in the Mobile Payments SDK are handled by the PaymentManager. Prior to starting a payment, you create a set of PaymentParameters to represent details of an individual payment and a set of PromptParameters indicating how the payment prompts are presented to the buyer.

Before taking a payment with the SDK in a production environment, ensure that you have done the following:

• Requested the device permissions necessary for the type of reader you're using.
• Installed and initialized the Mobile Payments SDK in your Android application.
• Authorized the Mobile Payments SDK with a Square account.
• Tested your application with mock readers in the Square Sandbox.

To begin a payment with the Mobile Payments SDK, you create a PaymentParameters object, which includes the payment amount, idempotency key, optional tip, application fee (if applicable), and the processing mode, which is used if you want to take payments while offline. For the complete list of payment parameter values and details, see the Android technical reference.

The PaymentParameters must also include an idempotency key. An idempotency key is a unique string identifier that accompanies an API operation, allowing Square to recognize potential duplicate calls. Using an idempotency key ensures that an operation can only occur once, protecting against unintended outcomes like charging a customer twice for the same transaction.

If a payment creation request doesn't receive a response due to network failure or any other error, you might be unsure whether the payment was processed. By providing a unique idempotency key in your PaymentParameters, you can recover by using that idempotency key in a call to CancelPaymentByIdempotencyKey to cancel an incomplete payment and continue with a new payment using a new idempotency key.

The Mobile Payments SDK requires that you create and manage idempotency keys for each payment created with your application. An idempotency key can be any unique string value. Don't reuse an idempotency key for a new payment. Doing so results in an error.

Along with an idempotency key, include a unique referenceID value in your PaymentParameters for each payment. This persists with the payment and can be used to identify the payment if you need to reference it later. You shouldn't use the referenceId as the idempotency key, because sometimes a payment requires multiple attempts (for example, when the first attempt is declined for expiration or insufficient funds or for any other reason).

If you don't receive a server response from a payment made with the Mobile Payments SDK, you should check the status of the payment to determine whether to retry. Use the ListPayments endpoint and query by location ID, total payment amount, or other fields to filter the list. You can use your unique referenceID to identify the correct payment and check its status. You might need to retry the payment with a new idempotency key if the prior payment exists, but cannot be completed.

Each payment also requires a set of PromptParameters, consisting of a mode and a set of additionalPaymentMethods. PromptParameters.mode determines whether your application uses the DEFAULT Square-provided payment prompt UI or a CUSTOM payment prompt where you build your own UI. The default UI provided by Square presents buyers with the payment options available from PaymentManager.availableCardInputMethods() and is presented if you don't create a set of promptParameters when starting your payment.

PromptParameters.additionalPaymentMethods specifies a set of additional payment methods available to use for this payment. The current option is KEYED (a manually entered credit card payment). When used with the DEFAULT promptMode, the Square payment prompt includes these alternative payment methods as options presented to buyers. If you create your own CUSTOM promptMode, you should use the additionalPaymentMethods available from the PaymentHandle to render these options for buyers in your own payment prompt UI.

After the callbacks have been written, you can begin processing a payment by calling PaymentManager.startPaymentActivity() with the PaymentParameters and PromptParameters you created previously and calling a callback to notify your application of results or errors from the payment flow.

During the payment:

• Square takes control of the screen display as another Android Activity to ensure that buyer information is handled securely and that the final confirmation of the payment is correctly shown to the buyer.
• The SDK provides a PaymentHandle as a way for you to interact with the ongoing payment (for example, if you need to cancel the payment).

When the payment completes, regardless of whether it completed successfully, control is returned to the user interface and your application is notified of the callback result. Your application can then display receipt or error information to the user and continue other processing.

fun startPaymentActivity() {
    val paymentManager = MobilePaymentsSdk.paymentManager()
    // Configure the payment parameters
    val paymentParams = PaymentParameters.Builder(
      amount = Money(100, CurrencyCode.USD),
      idempotencyKey = UUID.randomUUID().toString()
    )
      .referenceId("1234")
      .note("Chocolate Cookies and Lemonade")
      .autocomplete(true)
      .build()
    // Configure the prompt parameters
    val promptParams = PromptParameters(
      mode = PromptMode.DEFAULT,
      additionalPaymentMethods = listOf(Type.KEYED)
    )
    // Start the payment activity
    handle = paymentManager.startPaymentActivity(paymentParams, promptParams) { result ->
      // Handle the payment result
      when (result) {
        is Success -> showPaymentDetails(result.value)
        is Failure -> showPaymentError(result.errorCode, result.errorMessage)
      }
    }
}

fun onPause() {
    handle?.cancel()
}

As part of your application workflow, you might want to authorize a customer's transaction but delay the capture of the payment (the transfer of funds from the customer to the seller) for a period of time. For example, in a restaurant with a kiosk ordering system, you might want to authorize a customer's credit card when they order, but not complete the payment until they receive their food.

While creating PaymentParameters for a payment, set the autocomplete value to false if you want to delay the capture of a payment. By default, autocomplete is true, meaning the payment is authorized and captured immediately.

When autocomplete is false, there are two more PaymentParameter values that handle the delayed payment:

• delayDuration - The number of milliseconds to wait before canceling the payment or taking another delayAction, in RFC 3339 format. By default, this is 36 hours for card reader payments and 7 days for manually entered payments.
• delayAction - The action to take after the delayDuration passes with no other action on the payment. The possible options are CANCEL (default) or COMPLETE.

You can also add a tip to the delayed payment by calling the UpdatePayment endpoint and setting tip_money.

For more information about delayed payment capture using the Square Payments API, see Delayed Capture of a Card Payment.

If you need to cancel a pending payment for any reason, use paymentHandle.cancel() to cancel the payment. The CancelResult returned is CANCELED, NO_PAYMENT_IN_PROGRESS if there is no payment in progress to be canceled, or NOT_CANCELABLE if the payment in progress could not be canceled.

During any payment flow, if the application is sent to the background of the device or the application activity is interrupted, the payment in progress is canceled.

Your application must provide buyers with the option to receive a digital or printed receipt. These receipts aren't sent directly by Square. Therefore, to remain compliant with EMV-certification requirements, you must generate receipts including the following fields found in the cardDetails of the successful payment response object from startPaymentActivity():

• card.cardholderName (example: James Smith)
• card.brand and card.last4digits (example: Visa 0094)
• authorizationCode (example: Authorization 262921)
• emvApplicationName (example: AMERICAN EXPRESS)
• emvApplicationId (example: AID: A0 00 00 00 25 01 09 01)
• entryMethod (example: Contactless)

private fun showPaymentDetails(payment: Payment, receiptScreen: ReceiptScreen) {
    val cardDetails = (payment as OnlinePayment).cardDetails
    val card = cardDetails!!.card
    receiptScreen.setCardInformation(
      card.cardholderName,
      card.brand,
      card.lastFourDigits
    )
    receiptScreen.setEmvInformation(
      cardDetails.authorizationCode,
      cardDetails.applicationName,
      cardDetails.applicationId
    )
    receiptScreen.setEntryMethod(cardDetails.entryMethod)
}