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 Nearby Payment

The Nearby Payment functionality allows receiving payment requests via BLE from Vipaso Business devices in proximity. The SDK provides a Flow-based approach to listen for and process nearby payment events.

Receive incoming nearby payments via BLE

Start detecting and receiving payment requests via BLE from Vipaso Business devices in range. This returns a Flow that emits payment events as they occur:

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

// Collect and handle payment events
scope.launch {
    nearbyPaymentsFlow.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 receiveNearbyPaymentRequests() 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

BLE Contactless Payment

Contactless Payment allows receiving payment requests via BLE from a specific business terminal identified by a tag ID. This is a targeted, one-to-one BLE payment session.

Listen for contactless payment from a specific terminal

Start a contactless BLE payment session with a specific business terminal by providing its tag ID. This returns a Flow that emits payment events from that terminal only:

// Request: Start contactless payment session with a specific terminal
val tagId = UUID.fromString("terminal-tag-id")
val contactlessPaymentsFlow: Flow<VipasoCustomerPaymentEvent> = Vipaso.payment.customer.receiveContactlessPaymentRequest(tagId)

// Collect and handle payment events
scope.launch {
    contactlessPaymentsFlow.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 contactless payment, users can decide if they accept it. If the user accepts, send the acceptance to the Business device:

// Request: Accept a payment from a contactless 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 receiveContactlessPaymentRequest() 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 contactless payment flow

Stop BLE

When your app no longer needs to listen for 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 payments
Vipaso.payment.customer.stopBle()

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