Verify a Buyer

Use Strong Customer Authentication (SCA) to verify the buyer for one-time charges or for storing a customer card on file.

Overview

The In-App Payment SDK supports the Strong Customer Authentication (SCA) buyer verification flow for transactions where the buyer is present. When a buyer uses a payment card issued in the United Kingdom, the issuing bank might require your In-App Payments SDK application to challenge the buyer for additional identifying information. This can happen in a one-time charge when a card is stored on file with Square or when a stored card is used in a transaction.

To add the SCA flow to your application, complete the following steps to update your existing code. The In-App Payments SDK handles all the buyer verification logic and the verification UI. You provide the location ID, buyer contact name, and payment ID (the payment token or stored customer payment card ID) to the buyer verification method and the SDK completes the SCA flow to return a verification token to your application.

Link to section

Before you start

For Android, follow the steps in In-App Payments SDK: Build on Android.
For iOS, follow the steps in In-App Payments SDK: Build on iOS.

Link to section

Step 1: Add buyer verification dependencies

Add the following buyer verification dependency to your module build.gradle file:

dependencies {
  def buyerVerificationVersion = 'REPLACE_WITH_IAP_LIBRARY_VERSION'
  implementation "com.squareup.sdk.in-app-payments:buyer-verification:$buyerVerificationVersion"
}

Make sure that the buyerVerificationVersion dependency version matches the version used for the In-App Payments SDK library version, and is the latest version.

Link to section

Cocoapod installation

Install with CocoaPods by adding the following to your Podfile:

use_frameworks!

pod "SquareInAppPaymentsSDK"
pod "SquareBuyerVerificationSDK" ## Optional

Link to section

Manual installation

Add the SquareBuyerVerificationSDK SDK to your project:
1. Open the General tab for your application target in Xcode.
2. Drag the newly downloaded SquareBuyerVerificationSDK.framework into the Embedded Binaries section.
3. Choose Copy Items if Needed, and then choose Finish in the dialog box that appears.

Link to section

Step 2: Prepare for the verification flow

Create a VerificationParameters object in your activity to encapsulate the information in the following list:
- Contact - You should build the Contact object with as many contact field values as possible. You must provide the given name. The contact family name and city should be provided. The more complete the contact object, the lower the chance that the buyer is challenged by the card-issuing bank.
- Payment source ID - This ID can be the payment token returned by the CardEntry activity or a card-on-file ID for the buyer's payment card stored with Square.
- Location ID - The location IDs are found on the Locations page for your application in the Developer Dashboard. The ID references a seller location and stores the physical address of the seller.
- Buyer action - The buyer's intention of storing the card on file or charging it.
Pass the VerificationParameters object into the SDK verify method in step 3.

This example creates a contact and sets the verification parameters to the contact and a payment source ID.

Create a SQIPVerificationParameters object to encapsulate the information in the following list:
- SQIPContact - You should build the SQIPContact object with as many contact field values as possible. You must provide the given name. The contact family name and city should be provided. The more complete the contact object, the lower the chance that the buyer is challenged by the card-issuing bank.
- Payment source ID - This ID can be the payment token returned by the CardEntry view controller or a card-on-file ID for the buyer's payment card stored with Square.
- Location ID - The location IDs are found on the Locations page for your application in the Developer Dashboard. The ID references a seller location and stores the physical address of the seller.
- Buyer action - The buyer's intention of storing the card on file or charging it.
Pass it into the In-App-Payments SDK buyer verify method in step 3.
Create a SQIPTheme. You must provide a theme to style the verification challenge controller that SQIPBuyerVerificationSDK starts if the card-issuing bank needs to get more identifying information from the buyer. To learn more about creating a theme, see Customize the Payment Entry Form.

func makeVerificationParameters(paymentSourceID: String, buyerAction: SQIPBuyerAction) -> SQIPVerificationParameters {
    let contact = SQIPContact()
    contact.givenName = "John"
    contact.familyName = "Doe"
    contact.email = "[email protected]"
    contact.addressLines = ["London Eye","Riverside Walk"]
    contact.city = "London"
    contact.country = .GB
    contact.postalCode = "SE1 7"
    contact.phone = "8001234567"

    return SQIPVerificationParameters(
        paymentSourceID: paymentSourceID,   
        buyerAction: buyerAction,
        locationID: VERIFY_BUYER_LOCATION_ID,
        contact: contact
    )
}

func makeSquareTheme() -> SQIPTheme{
     let theme = SQIPTheme()
     theme.errorColor = .red
     theme.tintColor = Color.primaryAction
     theme.keyboardAppearance = .light
     theme.messageColor = Color.descriptionFont
     return theme
}

Link to section

Step 3: Verify a buyer

Important

SCA should be called for all customer-initiated transactions, including digital wallet payments. If the seller doesn't have SCA called for digital wallet payments, the transactions may be declined due to lack of authentication.

Complete this step if your application stores a buyer's payment card after the buyer enters the card information in the card entry view controller.

Did you know?

If your application uses Apple Pay, the verify function should be called in the paymentAuthorizationViewControllerDidFinish method (and not in the didAuthorizePayment method) after the buyer dismisses Apple Wallet. Buyer verification won't occur if the Apple Wallet overlay is being displayed.

In this example, note the following:

The buyer's action is set to buyerAction: .store().
The verification token is passed to the success completion handler of the verify function.
A cURL command is printed with the verification token, card payment token, and customer ID. The command gives an example of the Cards API Create Card operation.

This steps verifies a buyer for a card to be stored or charged.

A stored buyer's card ID can be used in place of a payment token in any of the example code that sets the first parameter of the VerificationParameters object.

extension MainViewController: SQIPCardEntryViewControllerDelegate {

    func cardEntryViewController(
         _ cardEntryViewController: SQIPCardEntryViewController,
         didObtain cardDetails: SQIPCardDetails,
         completionHandler: @escaping (Error?) -> Void) {
        let params = makeVerificationParameters(
            paymentSourceID: cardDetails.nonce,
            buyerAction: .store(),  //1: set buyer action to store
        )

        SQIPBuyerVerificationSDK.shared.verify(
            with: params,
            theme: makeSquareTheme(),
            viewController: cardEntryViewController,
            success: { (details) in   //2: verification token available
                storeCard(
                   nonce: cardDetails.nonce, 
                   customerID: CUSTOMER_ID, 
                   verificationToken: details.verificationToken,
                   completionHandler: completionHandler
                ) 
            },
            failure: { error in
                // Stop Square card entry UI spinner and display error message.
                completionHandler(error)
            }
        )
    }

    //3: Print cURL command that stores the customer card on file
    func storeCard(
        nonce: String,
        customerID: String,
        verificationToken: String,
        completionHandler: @escaping (Error?) -> Void) {

            let uuid = UUID().uuidString
            print("curl --request POST https://connect.squareup.com/v2/customers/{customerID}/cards \\" +
                "--header \"Content-Type: application/json\" \\" +
                "--header \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\" +
                "--header \"Accept: application/json\" \\" +
                "--data \'{" +
                "\"idempotency_key\": \"\(uuid)\"," +
                "\"card_nonce\": \"\(nonce)\"," +
                "\"billing_address\": {" +
                "\"address_line_1\": \"London Eye\"," +
                "\"address_line_2\": \"Riverside Walk\"," +
                "\"locality\": \"London\"," +
                "\"postal_code\": \"SE1 7\"," +
                "\"country\": \"UK\"}," +
                "\"cardholder_name\": \"John Doe\"" +
                "}\'");

             // Call Square card entry completion handler to stop the
             // UI spinner and indicate that the transaction was successful.
             completionHandler(nil)
    }
}

For information about storing a customer card on file after the payment token has been verified, see Integrate Customer Profiles with Other Services.

Link to section

Step 4: Charge the payment token or customer card ID

Note

In production, the CreateCard and CreatePayment operations are run on your backend after your client provides the payment token and verification token.

In this step, you charge a card for a verified buyer.

In onActivityResult for requestCode == DEFAULT_BUYER_VERIFICATION_REQUEST_CODE, send the payment source ID (the payment token or stored customer payment card ID) you got in step 3 and the verification token from this step to your backend to complete a payment with verification.

In this example, note the following:

Create a helper method to print a cURL command to save a card on file.
Create a helper method to print a cURL command to create a payment with the Payments API CreatePayment.

Note

The cURL command is run when requestCode is DEFAULT_BUYER_VERIFICATION_REQUEST_CODE.

Verify the buyer payment card and send the resulting verification token and the payment source ID (the payment token or stored customer payment card ID) to your backend to complete a payment with verification.

In this example, note the following:

The buyer action is set to buyerAction: .charge(SQIPMoney).
The verification token is passed to the success completion handler of the verify function.
A cURL command is printed with the verification token, payment source ID, and SQIPMoney. The command gives an example of the Payments API CreatePayment operation.

  extension PurchaseController {
    func checkout(paymentSourceID: String, purchaseAmount: SQIPMoney) {
        let params = makeVerificationParameters(
            paymentSourceID: paymentSourceID,
            buyerAction: .charge(purchaseAmount)  //1: Set buyer action to charge
        )

        SQIPBuyerVerificationSDK.shared.verify(
            with: params,
            theme: makeSquareTheme(),
            viewController: self,
            success: { (details) in   //2: Verification token available
               // Send payment request to your backend with token here.
                processPayment(
                    paymentSourceID: paymentSourceID,
                    verificationToken: details.verificationToken,
                    purchaseAmount: purchaseAmount,
                    successHandler: {
                        print(“Successfully processed payment”)
   //                   self.navigationController.push(
   //                       ReceiptViewController(item:self.item))
                    },
                    errorHandler: { error in
                        print(error.localizedDescription)
                    }
                )
            },

            failure: { error in
                // Unable to verify buyer identity. Handle error.
            })
        }

    //3: Print cURL command that completes a payment with verfied payment source
        func processPayment(
            paymentSourceID: String,
            verificationToken: String,
            purchaseAmount: SQIPMoney,
            successHandler: (Void) -> Void,
            errorHandler: (Error) -> Void
            ) {
            let uuid = UUID().uuidString
            print("curl --request POST https://connect.squareup.com/v2/payments \\" +
                "--header \"Content-Type: application/json\" \\" +
                "--header \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\" +
                "--header \"Accept: application/json\" \\" +
                "--data \'{" +
                "\"idempotency_key\": \"\(uuid)\"," +
                "\"autocomplete\": true," +
                "\"amount_money\": {" +
                "\"amount\": \(purchaseAmount.amount)," +
                "\"currency\":\"\(purchaseAmount.currency)\"}," +
                "\"verification_token\": \"\(verificationToken)\"," +
                "\"source_id\": \"\(paymentSourceID)\"" +
                "}\'");

            successHandler()
        }
  }

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Verify a Buyer

Swift

Kotlin

Java

On this page

Overview

Before you start

Step 1: Add buyer verification dependencies

Cocoapod installation

Manual installation

Step 2: Prepare for the verification flow

Step 3: Verify a buyer

Important

Did you know?

Step 4: Charge the payment token or customer card ID

Note

Note

On this page