1 - Set up SDK

Server-side

First, you need a Terminal3 account. Register now.

This integration requires your Terminal3 project credentials:

  • Project Key: Your public project identifier
  • Secret Key: Your private project key (keep this secure on your server)

Client-side

To install the SDK, add gamepaysdk to your app/build.gradle file:

// In your app-level build.gradle
dependencies {
// Your existing dependencies
    implementation 'com.terminal3:gamepaysdk:1.0.1'
}

Required Permissions

Add these permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Required Activities

Declare the payment activity in your AndroidManifest.xml:

<activity
    android:name="com.terminal3.gamepaysdk.core.PaymentSelectionActivity"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:theme="@style/PaymentwallSDKTheme"
    android:windowSoftInputMode="stateVisible|adjustResize|adjustPan" />
    
<!--Add this if you use PayAlto-->
 <activity
    android:name="com.terminal3.gamepaysdk.payalto.core.PayAltoActivity"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:theme="@style/PwsdkCustomTheme" />


2 - Enable Payment Methods

Your payment methods are configured through your Terminal3 Dashboard. Ensure you have enabled the payment methods you want to support:

  • Brick: Credit and debit cards
  • Google Pay: Google’s digital wallet
  • PayAlto: Local payment methods based on user location


3 - Build Payment Request

Import Required Classes


import com.terminal3.gamepaysdk.core.UnifiedRequest

Create Payment Request

class MainActivityViewModel : ViewModel(), IGPAPIEventHandler {

    fun createPaymentRequest(): UnifiedRequest {
        val request = UnifiedRequest()
        request.pwProjectKey = PW_PROJECT_KEY
        request.pwSecretKey = PW_SECRET_KEY

        request.amount = chargeAmount
        request.currency = chargeCurrency
        request.userId = uid
        request.userEmail = USER_EMAIL
        request.itemId = ITEM_GEM_ID
        request.itemName = ITEM_NAME
        request.merchantName = MERCHANT_NAME
        request.timeout = 30000
        request.signVersion = 3

        request.addBrick()
        request.enableFooter()
        request.addGooglePay()

        request.addPayAlto()
        request.addPayAltoParams(Const.P.WIDGET, "t3_1")
        request.addPayAltoParams(Const.P.COUNTRY_CODE, country)

        return request
    }
}


4 - Add Payment Methods

4.1 - Add Brick (Credit Cards)

Step 1: Add Brick Payment Method

// Add Brick payment method
request.addBrick()

NOTE: If you are asked to add bank information in the footer, please add the code below:

request.enableFooter();

Step 2: Handle One-time Token

The SDK automatically obtains a one-time token during the payment process. To handle this token, you need to implement the IGPAPIEventHandler interface and extract the token from the BaseResp data.

class MainActivityViewModel : ViewModel(), IGPAPIEventHandler {

override fun onResp(resp: BaseResp?) {
        when (resp?.resultCode) {
            ResponseCode.SUCCESSFUL -> {
                isProcessing = false
                paymentStatus = PaymentStatus.Success("Payment completed successfully!")
            }

            ResponseCode.FAILED -> {
                isProcessing = false
                paymentStatus = PaymentStatus.Failed("Payment failed!")
            }

            ResponseCode.CANCEL -> {
                isProcessing = false
                paymentStatus = PaymentStatus.Cancelled("Payment cancelled!")
            }

            ResponseCode.ERROR -> {
                isProcessing = false
                paymentStatus = PaymentStatus.Unknown("An error occurred!")
            }

            ResponseCode.MERCHANT_PROCESSING -> {
                isProcessing = false

                val serviceType = resp.data.getStringExtra(GPApi.KEY_SERVICE_TYPE) ?: ""

                if (GPApi.SERVICE_TYPE_BRICK == serviceType) {
                    val email = resp.data.getStringExtra(GPApi.KEY_BRICK_EMAIL) ?: ""
                    val token = resp.data.getStringExtra(GPApi.KEY_BRICK_TOKEN) ?: ""

                    // Process the payment with current charge details
                    if (token.isNotEmpty() && email.isNotEmpty()) {
                        processPayment(token, email)
                    } else {
                        paymentStatus = PaymentStatus.Unknown("Invalid payment data received")
                    }
                }
            }
        }
    }
}

Then you can use the one-time token to create a charge.

Step 3: Create a charge

After obtaining a one-time token, send a request from your backend to Terminal3 server to create a charge.

POST request to: https://api.paymentwall.com/api/brick/charge

Parameters and description can be found here.

Step 4: Handle Charge Response

After creating a charge request with the one-time token, you need to handle the response and pass it to the SDK for processing.

private fun handleChargeRequest() {
    try {
        // Execute your charge request to your backend/payment server
        val response = executeChargeRequest() // Your implementation
        
        // Get the response body as string
        val responseBody = getResponseBody(conn.inputStream)
        Log.i("CHARGE_RESPONSE", responseBody)
        
        // Pass the response to the SDK for processing
        GPApi.setBrickResponse(responseBody)
        
    } catch (e: Exception) {
        // Handle any errors during charge processing
        val errorMessage = e.message ?: "Payment processing failed"
        GPApi.setBrickError(errorMessage)
        Log.e("PaymentProcessor", "Charge request failed", e)
    }
}
  • Response Handling: Always pass the complete charge response to GPApi.setBrickResponse(response)
  • Error Handling: Use GPApi.setBrickError() for any exceptions or failures

3D Secure Integration

The SDK automatically handles 3D Secure authentication when required:

  1. Automatic Detection: The SDK detects if 3D Secure is necessary from the charge response
  2. 3D Secure UI: The SDK automatically displays the 3D Secure challenge page
  3. User Authentication: Users complete the 3D Secure verification process
  4. Token Generation: Upon successful verification, brick_secure_token and brick_charge_id are generated
  5. brick_secure_token and brick_charge_id are sent to your secure_redirect_url .
  6. Your backend processes the final charge with these parameters. Reference: https://docs.paymentwall.com/integration/direct/brick/3dsecure
  7. SDK receives the final payment result

Step 5: Handle payment result

Once the second charge is completed successfully, the SDK will send the payment result back in onResp(resp: BaseResp?)

4.2 - Add Google Pay

Step 1: Enable Google Pay

First, enable Google Pay in your AndroidManifest.xml:

<application>
<!-- Your existing application content -->

    <meta-data
        android:name="com.google.android.gms.wallet.api.enabled"
        android:value="true" />
</application>

Step 2: Add Google Pay to your request

// Add Google Pay payment method
request.addGooglePay()

Step 3: Going live with Google Pay

To move your integration from test to production, follow these steps:

  1. Request Production Access
    • Visit Google Pay’s publish guide.
    • Choose Gateway as the integration type when prompted.
    • Upload screenshots of your app showing the Google Pay integration.
    • Submit the form for review and wait for approval from Google’s onboarding team.
  2. App Signing Requirement
    • Make sure your APK is signed with your release key — the same key uploaded in the Google Pay Console.
    • ⚠️ Debug keys will not work in production.
  3. Configure Production Environment
    • Ensure you’re using production API keys
    • Test Google Pay from a signed, release build of your app.

4.3 - Add PayAlto

Step 1: Declare the PayAltoActivity

Declare the PayAlto activity in your AndroidManifest.xml:

<!--Add this if you use PayAlto-->
 <activity
    android:name="com.paymentwall.pwunifiedsdk.payalto.core.PayAltoActivity"
    android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
    android:theme="@style/PwsdkCustomTheme" />

Step 2: Add PayAlto to your request

// Add PayAlto payment methods
request.addPayAlto()
request.addPayAltoParams(Const.P.WIDGET, "t3")

// Add extra parameters for PayAlto (optional)
request.addPayAltoParams(Const.P.COUNTRY_CODE, country)


5 - Launch Payment Flow

Start Payment Activity

class MainActivity : ComponentActivity() {
		private fun createPaymentRequest() {
        val request = vm.createPaymentRequest(this)
        GPApi.sendReq(this, request)
    }
}

Handle Payment Result

class MainActivityViewModel : ViewModel(), IGPAPIEventHandler {

override fun onResp(resp: BaseResp?) {
        when (resp?.resultCode) {
            ResponseCode.SUCCESSFUL -> {
                paymentStatus = PaymentStatus.Success("Payment completed successfully!")
            }

            ResponseCode.FAILED -> {
                paymentStatus = PaymentStatus.Failed("Payment failed!")
            }

            ResponseCode.CANCEL -> {
                paymentStatus = PaymentStatus.Cancelled("Payment cancelled!")
            }

            ResponseCode.ERROR -> {
                paymentStatus = PaymentStatus.Unknown("An error occurred!")
            }

            ResponseCode.MERCHANT_PROCESSING -> {
                val serviceType = resp.data.getStringExtra(GPApi.KEY_SERVICE_TYPE) ?: ""

                if (GPApi.SERVICE_TYPE_BRICK == serviceType) {
                    val email = resp.data.getStringExtra(GPApi.KEY_BRICK_EMAIL) ?: ""
                    val token = resp.data.getStringExtra(GPApi.KEY_BRICK_TOKEN) ?: ""

                    // Process the payment with current charge details
                    if (token.isNotEmpty() && email.isNotEmpty()) {
                        processPayment(token, email)
                    } else {
                        paymentStatus = PaymentStatus.Unknown("Invalid payment data received")
                    }
                }
            }
        }
    }
}


6 - Test the Integration

Test Cards for Brick

Test your project to make sure everything works smoothly before launching your project.

Terminal3 provides you with a standard Visa test card to test payments:

  • 4242 4242 4242 4242
  • 4000 0000 0000 0002

You should use a valid expiration date to test.

CVV/CSC could be set to any 3 or 4 digits number to test payments normally. Using CVV/VSC code below will result in a different outcome while performing a test payments.

CVV/CSC Description
111 Error: Please ensure the CVV/CSC number is correct.
222 Error: Please contact your credit card issuing bank to check your balance.
333 Error: Please contact your credit card issuing bank to approve your payment.
555 Review: Your payment is under risk review and will be accept automatically after 2 mins
556 Review: Your payment is under risk review and will be declined automatically after 2 mis

Test Google Pay

  • We just support Google Pay’s production environment now
  • Ensure you have already added at least 1 payment method to Google Wallet
  • Test on a physical device in a supported country

Test PWLocal

  • Test with different country codes to see local payment methods

      request.addPayAltoParams(Const.P.COUNTRY_CODE, "KR")

  • Verify that appropriate local payment methods appear based on the currency

Next Steps

  1. Test thoroughly with all supported payment methods
  2. Set up webhook endpoints to handle payment notifications
  3. Implement proper error handling
  4. Configure your Terminal3 Dashboard with appropriate settings
  5. Test in the production environment before going live

For additional support and advanced features, visit the Terminal3 Developer Portal.

Questions?

Common questions are covered in the FAQ.
For integration and API questions, feel free to reach out Integration Team via integration@terminal3.com.
For business support, email us at sales@terminal3.com.
To contact sales, email sales@terminal3.com.