Connect your Android POS app on the same device as the Peach Payments Payment App using the Intent API library (com.peach:intent_api).

For payment flows (sale, refund, void, recovery), see Terminal integration flows.

Integration modes

Amounts are always Long in minor currency units (cents). Sale amount must be > 0.

Installation

Maven repository

Add the Peach Payments GitLab package registry to your project settings.gradle - no access token required:

repositories {
    maven {
        url 'https://gitlab.com/api/v4/projects/61399867/packages/maven'
    }
}

Dependency

dependencies {
    implementation 'com.peach:intent_api:2.0.8'
}

Pin the version Peach Payments confirms for your integration. Refund and void require 2.0.6+.

Architecture

Your POS app
    │
    ├─ Sale / Refund / Void / TransactionLookup builders
    │
    ├─ [binder available] ──► AIDL to Payment App
    │
    └─ [no binder] ──► CommunicationActivity ──► Payment App
            │
            ▼
    ResultObject JSON ──► your listener callback (UI thread)

The Payment App package follows com.finimo.paymentapp (variant suffixes per build).

Kotlin quick start

Sale.Builder(context)
    .amount(1000L)  // R 10.00
    .disableReceiptingOnOutcome(true)
    .setExternalPosData(mapOf("merchantTransactionId" to orderId))
    .setListener(object : SaleTransactionListener {
        override fun alertSaleTransactionResponse(response: PosTransactionSummary) {
            val success = response.isApproved &&
                (response.transactionType == PosTransactionType.SALE ||
                 response.transactionType == PosTransactionType.SALE_WITH_CASHBACK)
        }
        override fun alertError(error: IntentError) { /* see Intent error codes */ }
    })
    .startTransaction()

Implement SaleTransactionListener, RefundTransactionListener, VoidTransactionListener, or TransactionLookupListener depending on the operation.

Java quick start

new Sale.Builder(context)
    .amount(1000L)
    .setExternalPosData(Collections.singletonMap("merchantTransactionId", orderId))
    .setListener(new SaleTransactionListener() {
        @Override
        public void alertSaleTransactionResponse(PosTransactionSummary response) { }
        @Override
        public void alertError(IntentError error) { }
    })
    .startTransaction();

Web POS (Kotlin shell + WebView)

Supported pattern for React or other web clients:

1. Your Kotlin app hosts a WebView with your POS URL.
2. Expose a @JavascriptInterface (or replicate the web-wrapper PaymentInterface or FinimoPay bridge).
3. On payment request from JavaScript, call Intent API builders from Kotlin - do not call the Payment App directly from JavaScript.

In Peach Payments' web-wrapper sample, the bridge object is window.FinimoPay. Older samples may reference PaymentInterface.

Your page implements callbacks (for example, onSaleComplete, onError) registered by the bridge.

Operations

Refund and void availability

The original sale and refund must be processed on the same terminal. The Payment App asks for a supervisor PIN and a refund reason. Multiple partial refunds are supported for up to 180 days, provided that their total does not exceed the original sale amount.

Limit access to the supervisor PIN to reduce refund fraud risk.

Builder options (common)

Lookup flags on results

lastTransaction() vs searchTransaction

• lastTransaction() - returns only the most recent transaction where the customer tapped, inserted, or swiped a card. Attempts where no card details were provided are not returned.
• searchTransaction - use for broader recovery by amount, date range, RRN, and other supported filters. You cannot search by posData.merchantTransactionId.

If lookup returns an error or no matching successful result, always treat the payment as unsuccessful in your POS - do not mark the order paid.

Callbacks and response models

PosTransactionSummary (sale/refund) includes transactionId, transactionType, isApproved, transactionResult, posData, rrn, amount.

See Intent API data models for full field tables.

Error codes

See Intent error codes for all IntentErrorCode values and descriptions.

Next steps

1. Terminal integration flows: end-to-end sale, refund, void, and recovery flows.
2. Test your integration: Mock Payments App and UAT terminal testing.
3. Request a UAT account and install the UAT Payment App before terminal testing.