Android Customer Payment Instrument APIs

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

Fetch Instruments

Observe payment instruments as a Flow. You’ll receive the full list initially and updates on any change (balance changes, new instruments, etc.).

scope.launch {
    Vipaso.payment.customer.paymentInstrument.fetchInstruments().collect { instruments ->
        // here you get the list of all instruments with their details
    }
}

The list emits VipasoInstrument items which include instrument details and balance information when applicable.

Key VipasoInstrument properties include:

• id, type: VipasoInstrumentType, provider: VipasoInstrumentProvider?, lastDigits?
• status: VipasoInstrumentStatus, nickname?, customerName?, phoneNumber?
• preAuthorizations?, preAuthorizedAmount?, preAuthorizationCurrency?, preAuthCapable
• thirdPartyId?, depositsEnabled, prePaid, balance?, defaultCurrency

Fetch Instrument

Observe a specific instrument as a Flow — you’ll receive the instrument details initially and updates on any change.

scope.launch {
    Vipaso.payment.customer.paymentInstrument.fetchInstrument("instrument_id").collect { instrument ->
        // here you get the instrument details
    }
}

Possible VipasoInstrumentType values:

• CARD: Credit or debit card instrument
• BANK_ACCOUNT: Direct bank account instrument
• MNO: Mobile Network Operator payment instrument

Possible VipasoInstrumentProvider values:

• VISA, MASTERCARD, AMERICAN_EXPRESS, DINERS, VERVE, OTHER

Remove Instrument

Delete a payment instrument by ID.

Vipaso.payment.customer.paymentInstrument.removeInstrument("instrument_id")

Create Card Instrument

Add a new card payment method to the user's account. The card will be validated and stored securely.

val cardRequest = CreateCardInstrumentRequest(
    customerName = "John Doe",
    creditCardNumber = "4111111111111111",
    expiryMonth = 12,
    expiryYear = 2025,
    cvv = "123",
    nameOnCard = "JOHN DOE",
    lang = VipasoLang.EN
)
val cardResponse: CreateCardInstrumentResponse =
    Vipaso.payment.customer.paymentInstrument.createCardInstrument(cardRequest)

Possible VipasoInstrumentStatus values:

• IN_PROGRESS: Instrument creation is being processed
• VERIFIED: Instrument has been successfully verified and is ready for use
• FAILED: Instrument creation or verification failed

Create MNO Instrument

Add a mobile network operator payment method to the user's account.

val mnoRequest = CreateMnoInstrumentRequest(
    phone = "+1234567890",
    customerName = "John Doe",
    deviceName = "John's Phone",
    lang = VipasoLang.EN
)
val mnoResponse: CreateMnoInstrumentResponse =
    Vipaso.payment.customer.paymentInstrument.createMnoInstrument(mnoRequest)

Create Third-Party Instrument

Create an instrument with an existing third-party ID from your own system.

val thirdPartyRequest = CreateThirdPartyInstrumentRequest(
    thirdPartyId = "account_id",
    instrumentType = VipasoInstrumentType.BANK_ACCOUNT,
    lang = VipasoLang.EN
)
val thirdPartyResponse: CreateThirdPartyInstrumentResponse =
    Vipaso.payment.customer.paymentInstrument.createThirdPartyInstrument(thirdPartyRequest)

Pre-Authorize Instrument (Experimental)

Certain instruments can be pre-authorized with an amount of money to enable users to pay in offline mode. This is an EXPERIMENTAL functionality.

val preAuthRequest = PreAuthorizationRequest(
    instrumentId = "instrument_id",
    amount = "100.00",
    currency = "USD"
)
val preAuth: VipasoPreAuthorization =
    Vipaso.payment.customer.paymentInstrument.preAuthorizeInstrument(preAuthRequest)

Possible VipasoPreAuthorizationStatus values:

• AVAILABLE: Pre-authorized funds are available for offline payments
• VOIDED: Pre-authorization voided
• EXPIRED: Pre-authorization expired and no longer usable

Top Up Instrument

Top up allows funds to be transferred from a mobile phone number to an instrument. This results in a response containing a URL which points to the web flow start page for the top-up process.

val topUpRequest = TopUpRequest(
    instrumentId = "instrument_id",
    amount = "50.00",
    currency = "USD"
)
val topUpResponse: TopUpResponse =
    Vipaso.payment.customer.paymentInstrument.topUpInstrument(topUpRequest)

TopUpResponse contains:

• webFlowUrl: URL to complete the top-up process in a web flow

Withdraw From Instrument

Withdrawal allows funds to be transferred from an instrument to a supplied phone number. The response contains an ID and a status.

val withdrawalRequest = WithdrawalRequest(
    instrumentId = "instrument_id",
    amount = "25.00",
    currency = "USD"
)
val withdrawalResponse: WithdrawalResponse =
    Vipaso.payment.customer.paymentInstrument.withdrawFromInstrument(withdrawalRequest)

Possible WithdrawalStatus values:

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