Skip to main content
Version: Next

iOS Customer Payment APIs

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

Receiving Payments​

BLE Nearby Payment​

The Nearby Payment functionality allows receiving payment requests and payment events via BLE from Vipaso Business devices in proximity.

vipaso.payment.customer.receiveNearbyPaymentRequests { paymentEvent in
    switch paymentEvent {
    case .connected:
        // The two sides are connected. Possible maintenance here.

    case .receivedPayment(let paymentRequest):
        // Display payment request to user for approval
        
    case .finishedPayment(let result):
        // Payment completed successfully
        
    case .error(let error):
        // Handle payment error
        
    case .cancelled:
        // Payment was cancelled
        
    case .otherPaid:
        // Another wallet paid the current payment
        
    case .disconnected:
        // Disconnected from terminal
    }
}

BLE Contactless Payment​

Contactless Payment allows receiving payment requests and payment events 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.


guard let tagID = UUID(uuidString: "terminal-tag-uuid").uuidString else {
    throw YourError.ForInvalidTagID
}

vipaso.payment.customer.receiveContactlessPaymentRequest(tagID: tagID) { paymentEvent in
    switch paymentEvent {
    case .connected:
        // The two sides are connected. Possible maintenance here.

    case .receivedPayment(let paymentRequest):
        // Display payment request to user for approval
        
    case .finishedPayment(let result):
        // Payment completed successfully
        
    case .error(let error):
        // Handle payment error
        
    case .cancelled:
        // Payment was cancelled
        
    case .otherPaid:
        // Another wallet paid the current payment
        
    case .disconnected:
        // Disconnected from terminal
    }
}

Accept Payment Request​

Accept an incoming payment request and process the payment:

let request = VipasoPaymentAcceptanceRequest(
    paymentID: paymentID,
    amount: amount,
    tip: tip,
    currency: currency,
    instrumentID: instrumentID,
    createdAt: Date().iso8601String,
    isDelegatedInstrumentID: false // Set to true for delegated instruments
)

vipaso.payment.customer.acceptPayment(request: request) { result in
    switch result {
    case .success(let success):
        if success {
            // Payment accepted and processing
        }
    case .failure(let error):
        print("Accept payment failed: \(error.localizedDescription)")
    }
}

Cancel Payment​

Cancel an ongoing payment request:

vipaso.payment.customer.cancelPayment(paymentID: paymentID) { result in
    switch result {
    case .success(let success):
        if success {
            // Payment cancelled successfully
        }
    case .failure(let error):
        print("Cancel payment failed: \(error.localizedDescription)")
    }
}

Stop BLE​

Stop listening for BLE payments and disconnect from terminals:

vipaso.payment.customer.stopBLE()
// Call this when closing the app or when no longer accepting payments

Payment History​

Fetch Payments​

Retrieve a paginated list of payment transactions with status filtering:

vipaso.payment.customer.fetchPayments(
    page: 0,
    status: .completed
) { result in
    switch result {
    case .success(let response):
        let payments = response.payments
        // Display payment history
    case .failure(let error):
        print("Fetch payments failed: \(error.localizedDescription)")
    }
}

Fetch Payment Details​

Get detailed information for a specific payment:

let request = FetchPaymentRequest(paymentID: "payment-123")
vipaso.payment.customer.fetchPayment(request: request) { result in
    switch result {
    case .success(let response):
        let payment = response.payment
        // Display payment details
    case .failure(let error):
        print("Fetch payment failed: \(error.localizedDescription)")
    }
}

Offline Payments​

Sync Offline Payments​

Upload offline payments stored locally to the server:

vipaso.payment.customer.syncPayments { result in
    switch result {
    case .success:
        print("Offline payments synchronized successfully")
    case .failure(let error):
        print("Sync failed: \(error.localizedDescription)")
    }
}

Fetch Offline Payments​

Get all offline payments stored locally:

let offlinePayments = vipaso.payment.customer.fetchOfflinePayments()
print("Found \(offlinePayments.count) offline payments")

// Process offline payments
for payment in offlinePayments {
    // Handle offline payment data
}

Payment Instruments​

For managing payment instruments (cards, mobile money, etc.), see the dedicated Customer Payment Instrument APIs documentation.

// Access instrument APIs through the instrument property
vipaso.payment.customer.instrument.fetchInstruments { result in
    // Handle instruments response
}

Payment Events​

The VipasoPaymentEvent enum provides different payment states:

  • receivedPayment: New payment request received from terminal
  • finishedPayment: Payment completed successfully
  • error: Payment processing error occurred
  • cancelled: Payment was cancelled by user or terminal
  • otherPaid: Another wallet processed the current payment
  • disconnected: Connection to terminal lost

Notes​

  • Delegated Instruments: Set isDelegatedInstrumentID: true for third-party payment methods
  • Offline Support: Payments can be processed offline and synchronized later
  • Cleanup: Always call stopBLE() when closing the app or switching contexts