iOS Customer Payment Instrument APIs

Customer payment instrument APIs for adding, managing, and removing payment methods. Access these APIs through vipaso.payment.customer.instrument.

Managing Instruments

Fetch All Instruments

Get a list of all payment instruments associated with the customer:

vipaso.payment.customer.instrument.fetchInstruments { result in
    switch result {
    case .success(let response):
        let instruments = response.instruments
        // Display instruments list
        displayInstruments(instruments)
    case .failure(let error):
        print("Fetch instruments failed: \(error.localizedDescription)")
    }
}

Fetch Single Instrument

Get details for a specific payment instrument:

let request = FetchInstrumentRequest(id: instrumentID)
vipaso.payment.customer.instrument.fetchInstrument(request: request) { result in
    switch result {
    case .success(let response):
        let instrument = response.instrument
        // Display instrument details
        displayInstrumentDetails(instrument)
    case .failure(let error):
        print("Fetch instrument failed: \(error.localizedDescription)")
    }
}

Remove Instrument

Remove a payment instrument from the customer's account:

let request = RemoveInstrumentRequest(id: instrumentID)
vipaso.payment.customer.instrument.removeInstrument(request: request) { result in
    switch result {
    case .success:
        // Instrument removed successfully
        refreshInstrumentsList()
    case .failure(let error):
        print("Remove instrument failed: \(error.localizedDescription)")
    }
}

Creating Instruments

Create Card Instrument

Add a new credit/debit card as a payment instrument:

let request = CreateCardInstrumentRequest(
    lang: .en,
    customerName: customerName,
    creditCardNumber: creditCardNumber,
    expiryMonth: expiryMonth,
    expiryYear: expiryYear,
    cvv: cvv,
    nameOnCard: nameOnCard
)

vipaso.payment.customer.instrument.createCardInstrument(request: request) { result in
    switch result {
    case .success(let response):
        let instrumentID = response.id
        let status = response.status
        // Card instrument created
        handleNewInstrument(instrumentID, status: status)
    case .failure(let error):
        print("Create card instrument failed: \(error.localizedDescription)")
    }
}

Create Mobile Money Instrument

Add a mobile money account as a payment instrument:

let request = CreateMNOInstrumentRequest(
    phone: phoneNumber,
    customerName: customerName,
    deviceName: deviceName,
    lang: .en
)

vipaso.payment.customer.instrument.createMNOInstrument(request: request) { result in
    switch result {
    case .success(let response):
        let instrumentID = response.id
        // Mobile money instrument created
        handleNewInstrument(instrumentID)
    case .failure(let error):
        print("Create MNO instrument failed: \(error.localizedDescription)")
    }
}

Create Third-Party Instrument

Create an instrument using an existing third-party payment method ID:

let request = CreateThirdPartyInstrumentRequest(
    thirdPartyID: "existing-payment-method-id",
    instrumentType: .card,
    lang: .en
)

vipaso.payment.customer.instrument.createThirdPartyInstrument(request: request) { result in
    switch result {
    case .success(let response):
        let instrumentID = response.id
        // Third-party instrument created
        handleNewInstrument(instrumentID)
    case .failure(let error):
        print("Create third-party instrument failed: \(error.localizedDescription)")
    }
}

Instrument Operations

Top Up Instrument

Add funds to a payment instrument. This returns a web URL to complete the top-up process:

let request = TopUpRequest(
    instrumentID: instrumentID,
    amount: "50.00",
    currency: "USD"
)

vipaso.payment.customer.instrument.topUpInstrument(request: request) { result in
    switch result {
    case .success(let response):
        let webFlowURL = response.webFlowURL
        // Open web flow to complete top-up
        openWebFlow(webFlowURL)
    case .failure(let error):
        print("Top-up failed: \(error.localizedDescription)")
    }
}

Withdraw from Instrument

Transfer funds from an instrument to a mobile phone number:

let request = WithdrawalRequest(
    instrumentID: instrumentID,
    amount: "25.00",
    currency: "USD",
    phone: phoneNumber
)

vipaso.payment.customer.instrument.withdrawFromInstrument(request: request) { result in
    switch result {
    case .success(let response):
        let withdrawalID = response.id
        let status = response.status // initiated, inProgress, completed, failed, cancelled
        // Withdrawal initiated
        handleWithdrawal(withdrawalID, status: status)
    case .failure(let error):
        print("Withdrawal failed: \(error.localizedDescription)")
    }
}

Pre-Authorization (Experimental)

Pre-Authorize Amount

Pre-authorize an amount on an instrument for offline payments:

let request = PreAuthorizationRequest(
    instrumentID: instrumentID,
    amount: "100.00",
    currency: "USD"
)

vipaso.payment.customer.instrument.preAuthorizeInstrument(request: request) { result in
    switch result {
    case .success(let response):
        let authorization = response.authorization
        // Pre-authorization successful
        handlePreAuthorization(authorization)
    case .failure(let error):
        print("Pre-authorization failed: \(error.localizedDescription)")
    }
}

Clear Expired Pre-Authorizations

Remove expired pre-authorizations from all instruments:

do {
    try vipaso.payment.customer.instrument.clearExpiredPreAuthorizations()
    print("Expired pre-authorizations cleared successfully")
} catch {
    print("Clear pre-authorizations failed: \(error.localizedDescription)")
}

Notes

• Instrument Types: Supports cards, mobile money (MNO), and third-party payment methods
• Web Flows: Top-up operations require completing a web-based payment flow
• Pre-Authorization: Currently experimental feature for offline payment support
• Withdrawal Status: Monitor withdrawal status as it progresses through different states