Android Customer Payment APIs

Customer payment APIs for handling payment requests and viewing transaction history. Access these APIs through Vipaso.payment.customer.

Payment History

Fetch Payments

Retrieve a paginated list of payment transactions with optional filtering by status:

// Request: Get list of payment transactions
val payments: List<VipasoPayment> = Vipaso.payment.customer.fetchPayments(
    page = 0,
    status = VipasoPaymentStatus.COMPLETED
)

Possible VipasoPaymentStatus values:

• INITIATED: Payment has been created but processing hasn't started
• IN_PROGRESS: Payment is currently being processed
• COMPLETED: Payment has been successfully completed and funds transferred
• FAILED: Payment processing failed due to an error
• CANCELLED: Payment was cancelled by the user, merchant, or system

Example VipasoPayment properties returned:

VipasoPayment(
    paymentId = "payment-123",
    amount = "25.50",
    currency = "USD",
    tip = null, // or "0.00"
    unifiedStatus = VipasoPaymentStatus.COMPLETED,
    totalAmount = "25.50",
    instrumentId = "card-123",
    businessUser = BusinessUser(
        id = "merchant-456",
        name = "Coffee Shop",
        operatorId = "operator-456",
        currency = "USD"
    ),
    consumerUser = ConsumerUser(
        id = "user-123",
        fullName = "John Doe"
    ),
    lastUpdate = "2025-06-03T09:25:48Z"
)

Fetch Payment

Fetch the complete details of a specific payment by its ID:

// Request: Get details for a specific payment
val paymentDetails: VipasoPayment = Vipaso.payment.customer.fetchPayment(paymentId = "payment_id")

Possible VipasoPaymentStatus values:

• INITIATED: Payment has been created but processing hasn't started
• IN_PROGRESS: Payment is currently being processed
• COMPLETED: Payment has been successfully completed and funds transferred
• FAILED: Payment processing failed due to an error
• CANCELLED: Payment was cancelled by the user, merchant, or system

BLE Payment

The BLE Payment functionality allows receiving payments and payment events from Vipaso Business devices. The SDK provides a Flow-based approach to listen for and process BLE payment events.

Listen for incoming payments via BLE

Start detecting and receiving payment requests via Bluetooth Low Energy from Vipaso Business devices. This returns a Flow that emits payment events as they occur:

// Request: Start detecting Bluetooth payment requests from Vipaso Business devices
val blePaymentsFlow: Flow<VipasoCustomerPaymentEvent> = Vipaso.payment.customer.receivePaymentRequestsViaBle()

// Collect and handle payment events
scope.launch {
    blePaymentsFlow.collect { event ->
        when (event) {
            is VipasoCustomerPaymentEvent.PaymentRequestReceived -> {
                val paymentId = event.paymentId
                val amount = event.amount
                val currency = event.currency
                val businessUserId = event.businessUserID
                val operatorId = event.operatorId
                val businessUserName = event.businessUserName
                // You can accept or decline the payment request
            }
            is VipasoCustomerPaymentEvent.PaymentSuccessful -> {
                // Payment was successful, show confirmation
            }
            is VipasoCustomerPaymentEvent.PaymentCancelled -> {
                // Payment was cancelled
            }
            is VipasoCustomerPaymentEvent.AnotherUserPaid -> {
                // Another user paid instead
            }
            is VipasoCustomerPaymentEvent.PaymentFailed -> {
                // Payment failed, show error message
            }
        }
    }
}

Accept Payment

When an incoming payment request arrives via BLE, users can decide if they accept it. If the user accepts, send the acceptance to the Business device:

// Request: Accept a payment from a BLE payment request
val acceptance = VipasoPaymentAcceptanceRequest(
    paymentId = UUID.fromString("payment-id-from-request"),
    amount = "50.00",
    tip = "5.00", // optional
    currency = "USD",
    instrumentId = "selected-instrument-id",
    isDelegatedInstrument = true // set to true if instrument is delegated
)

Vipaso.payment.customer.acceptPayment(acceptance)

// The payment result will be delivered through the receivePaymentRequestsViaBle() flow
// as PaymentSuccessful, PaymentFailed, or other events

Cancel Payment

If the user does not accept a payment, cancel the operation and notify the Business device:

// Request: Reject or cancel a payment operation
Vipaso.payment.customer.cancelPayment("payment_id")

// The payment state will be updated in the BLE payment flow

Stop BLE

When your app no longer needs to listen for BLE payments (for example, when the user navigates away from the payment screen) or when closing the app, stop the BLE detection:

// Request: Stop listening for BLE payments
Vipaso.payment.customer.stopBle()

// After calling this, you will no longer receive payment requests or events
// You can call receivePaymentRequestsViaBle() again to start listening for new payments