Square Mobile Payments SDK Sample App

This Android application demonstrates how to integrate Square's Mobile Payments SDK to accept in-person payments using Square Readers or Tap to Pay on Android.

✨ Features Jetpack Compose permission screen with Material Design 3!

Features

• Square Mobile Payments SDK integration
• Modern Jetpack Compose UI for permission handling
• Clean, modern Material Design UI
• Payment processing with Square Readers
• Tap to Pay on Android support (on compatible devices)
• Real-time payment status updates

Prerequisites

Before you begin, ensure you have:

1. A Square Account enabled for payment processing

   • Visit squareup.com/activation if needed

2. Square Developer Account

   • Sign up at developer.squareup.com

3. Android Development Environment

   • Android Studio (latest version recommended)
   • Minimum SDK: API 28 (Android 9)
   • Target SDK: API 35 (Android 15) or later

4. A Compatible Device

   • Android device running Android 9 or later
   • For Tap to Pay: A compatible Android phone

Setup Instructions

1. Get Your Square Credentials

1. Go to the Square Developer Console
2. Create a new application or select an existing one
3. Navigate to the Credentials page
4. Copy the following:
   • Application ID (for both Sandbox and Production)
   • Access Token (use Sandbox for testing)
5. Navigate to the Locations page
   • Copy your Location ID

2. Configure the App

Open app/src/main/java/com/example/custompromptsample/MainActivity.kt and replace the placeholder values:

private val squareApplicationId = "YOUR_SQUARE_APPLICATION_ID"
private val squareAccessToken = "YOUR_SQUARE_ACCESS_TOKEN"
private val squareLocationId = "YOUR_SQUARE_LOCATION_ID"

Important Security Note:

• The access token should NEVER be hardcoded in a production app
• Instead, implement OAuth or use a backend server to securely provide authorization
• This sample uses hardcoded values for simplicity only

3. Build and Run

1. Open the project in Android Studio
2. Sync Gradle files using File > Sync Project with Gradle Files
3. Connect your Android device or start an emulator
4. Click Run or press Shift + F10

Using the App

Testing Payments in Sandbox Mode

When using Sandbox credentials, you can test payments without real money:

1. With Mock Readers:

   • The SDK automatically provides mock readers in Sandbox mode
   • No physical reader is required for testing

2. Test Card Numbers:

   • Use Square's test card numbers
   • Example: 4111 1111 1111 1111 (Visa)

Taking a Real Payment

1. Enter a payment amount in the text field
2. Tap the Pay with Card button
3. Follow the on-screen prompts to:
   • Select a connected reader, OR
   • Use Tap to Pay on Android (if available), OR
   • Enter card details manually (if enabled)
4. Complete the payment
5. View the payment confirmation

Settings Screen

The app includes a comprehensive settings screen accessible via the settings button (⚙️) in the top-right corner of the main screen.

What's Displayed

SDK Information

• SDK Version - Current version of the Mobile Payments SDK
• Environment - PRODUCTION or SANDBOX mode
• Security Compliance Version - Current security compliance version

Authorization Details

• Authorization Status - Whether the SDK is authorized
• Business Name - Your Square business name
• Location Name - The authorized location name
• Currency - Currency code (e.g., USD)
• Card Processing Status - Whether card processing is activated
• Merchant ID - Your Square merchant identifier
• Location ID - Your Square location identifier

Payment Settings

• Offline Processing - Whether offline payments are enabled
• Max Offline Transaction - Maximum single offline transaction amount
• Max Total Stored Offline - Maximum total offline payment amount

Privacy Controls

• Tracking Consent - Current analytics/performance tracking consent state
• Update Consent - Modify tracking consent preferences

Available Actions

1. Deauthorize SDK - Disconnect the app from your Square account (requires confirmation)
2. Update Tracking Consent - Grant or deny analytics data collection
3. Open Square Settings - Access the Square-provided settings screen
4. Refresh Settings - Reload all settings from the SDK

Color Indicators

• 🟢 Green - Active, enabled, or authorized
• 🔴 Red - Inactive, disabled, or not authorized
• 🟠 Orange - Pending or warning state
• ⚪ Gray - Neutral or informational

Project Structure

app/
├── src/main/
│   ├── java/com/example/custompromptsample/
│   │   └── MainActivity.kt          # Main app logic
│   ├── res/
│   │   ├── layout/
│   │   │   └── activity_main.xml    # UI layout
│   │   └── values/
│   │       ├── strings.xml          # String resources
│   │       ├── colors.xml           # Color definitions
│   │       └── themes.xml           # App themes
│   └── AndroidManifest.xml          # App configuration
└── build.gradle.kts                 # App dependencies

Key SDK Components

Initialization

MobilePaymentsSdk.initialize(squareApplicationId, this)

Authorization

authorizationManager.authorize(accessToken, locationId) { result ->
    when (result) {
        is Result.Success -> // Handle success
        is Result.Failure -> // Handle error
    }
}

Taking a Payment

val paymentParams = PaymentParameters.Builder(
    amount = Money(amountInCents, CurrencyCode.USD),
    paymentAttemptId = UUID.randomUUID().toString()
)
.referenceId(UUID.randomUUID().toString())
.note("Payment description")
.autocomplete(true)
.build()

val promptParams = PromptParameters(mode = PromptMode.DEFAULT)

paymentManager.startPaymentActivity(paymentParams, promptParams) { result ->
    // Handle result
}

Permissions

The app requires the following permissions for Square Mobile Payments SDK:

Runtime Permissions (User Must Grant)

• ACCESS_FINE_LOCATION - To confirm that payments are occurring in a supported Square location
• RECORD_AUDIO - To receive data from magstripe readers
• BLUETOOTH_CONNECT (Android 12+) - To receive data from contactless and chip readers
• BLUETOOTH_SCAN (Android 12+) - To discover and pair with Square Readers
• READ_PHONE_STATE - To identify the device sending information to Square servers

Normal Permissions (Automatically Granted)

• INTERNET - To communicate with Square servers
• BLUETOOTH (Android 11 and below) - To connect to Square Readers

Permission Granting Screen

The app includes a dedicated PermissionActivity that:

1. Shows before the main payment screen on first launch
2. Displays educational cards explaining why each permission is needed
3. Allows granting individually or all at once
4. Provides rationale dialogs when permissions are denied
5. Handles Android version differences (API 28-36)
6. Remembers permission state to avoid repeated prompts
7. Directs to Settings if permissions are permanently denied

The permission screen follows Android best practices and Material Design guidelines for a modern, user-friendly experience.

Connecting Square Readers

Contactless and Chip Reader

1. Ensure your reader is charged and turned on
2. Follow the pairing guide
3. Use the ReaderManager to pair and manage readers

Tap to Pay on Android

• Automatically available on compatible devices
• No physical reader required
• Works when no other readers are paired

Troubleshooting

Common Issues

1. "SDK Not Authorized" Error

   • Verify your Application ID, Access Token, and Location ID are correct
   • Ensure the Access Token has the required permissions:
     • MERCHANT_PROFILE_READ
     • PAYMENTS_WRITE
     • PAYMENTS_WRITE_IN_PERSON

2. "No Network" Error

   • Check your internet connection
   • Verify the device has proper network access

3. Build Errors

   • Ensure you've added the Square Maven repository in settings.gradle.kts
   • Sync Gradle files using File > Sync Project with Gradle Files
   • Clean and rebuild the project

4. Reader Connection Issues

   • Ensure Bluetooth is enabled
   • Check location permissions are granted
   • Make sure the reader is charged and within range

Additional Resources

• Square Mobile Payments SDK Documentation
• API Reference
• Developer Forums
• Sample Apps on GitHub

Production Considerations

Before deploying to production:

1. Implement Secure Authorization

   • Use OAuth for authorization
   • Never hardcode access tokens
   • Implement token refresh logic

2. Error Handling

   • Add comprehensive error handling
   • Log errors for debugging
   • Provide user-friendly error messages

3. Testing

   • Test with real Square Readers
   • Test various payment scenarios
   • Verify error handling

4. Compliance

   • Follow PCI compliance guidelines
   • Adhere to Square's branding requirements
   • Review Square's terms of service

5. Application Signature

   • When using Mobile Payments SDK version 2.1 or later
   • Provide your application signature to Square before production

Version Information

• Square Mobile Payments SDK: 2.3.2
• Min SDK Version: 28 (Android 9)
• Target SDK Version: 36 (Android 15)
• Kotlin Version: 2.0.21

License

This sample app is provided for demonstration purposes. Please review Square's SDK license terms for production use.

Support

For help and support:

• Visit the Square Developer Documentation
• Ask questions in the Developer Forums
• Contact Square Developer Support