Generate PaymentUIRequest

TerraCore v0

Usage#

Using PaymentUIRequestBuilder to create a request for opening payment page.

iOS
Android
Flutter

We have a pre-built activity in UI module that contains payment method list, transaction detail and transaction result and also handling process payment.

Client can be open the activity from activity or fragment by providing request data and using the provided method which will look something like this

At first, we need prepare payload, Let's using PaymentUIRequestBuilder as below to make request.

Open available methods screen#

In general, Main app couldn't/unknown define what methods will pay for the order. So The SDK will show available methods as default to make user able to choose any method will pay after call start transaction

// prepare payload  
 val paymentRequestBuilder = PaymentUIRequestBuilder()
                .setOrderCode(orderCode = "yourOrderCode")
                .setOrderAmount(orderAmount = 1000)
                .setMainMethod(PaymentMainMethodRequest.All(amount = 1000)) // All method mean user can using any available method
    

 // Other way
 val paymentRequestBuilder = PaymentUIRequestBuilder()
                .setOrderCode(orderCode = "yourOrderCode")
                .setOrderAmount(orderAmount = 1100)
                .setLoyaltyMethod(LoyaltyMethodRequest(point =  100, amount = 100)) // if has loyalty
                .setMainMethod(PaymentMainMethodRequest.All(amount = 1000))

Payment directly (without available methods screen)#

There are some cases the main app has defined what exactly methods will pay for the order, that mean main app want to ignore available methods screen. So We has already provided the solution to solved that problem. Let's see below.

// prepare payload
 val paymentRequestBuilder = PaymentUIRequestBuilder()
               .setOrderCode(orderCode = "yourOrderCode")
               .setLoyaltyMethod(LoyaltyMethodRequest(point =  100, amount = 100)) // optional
               .setMainMethod(PaymentMainMethodRequest.VNPayGatewayQR(amount = 1000)) // define VNPayGatewayQR method will payment

Refer to PaymentMainMethodRequest class to get all available methods.

Payment methods metadata config(Optional)#

There are some methods must add more config to payment, For example VNPayEWallet. So you must be passing metadata into paymentRequestBuilder before call startUI.

 paymentRequestBuilder
    .setMetadata(
          PaymentV2Request.Metadata(
                methods = arrayListOf(
                    PaymentV2Request.Metadata.MethodConfig.VNPayEWallet(
                        partnerId = "0918913795",
                        phone = "0918913795",
                        name = "Nguyen Van a",
                        email = "078langha@gmail.com"
                    )
                )
            )
        )

Notes: refer to PaymentV2Request.Metadata.MethodConfig to see all metadata

Firstly, we need create PaymentUIRequestBuilder instance by pass PaymentOrder param and PaymentClient param.

    let order = PaymentOrder(orderCode: orderCode, amount: amount)
    let builder = PaymentUIRequestBuilder.init(
        order: order,
        client: .init(
            userId: "2c59afde1f11489b8d5bd2cd2xxxxxx",
            escrowMerchantCode: nil
        )
    )

Then, we set main payment methods

let _ = builder.setMainMethod(.vnPayQRGateway(amount: onlineAmount))

After that, we set loyalty info methods if needed

    if let loyaltyAmount = loyaltyAmount, loyaltyAmount > 0 {
        let _ = builder.setLoyaltyMethod(
            points: loyaltyAmount,
            amount: loyaltyAmount
        )
    }

Finally, we using build() function of this builder to get a payment request for next step.

let request = builder.build()

Generate payment request#

Open available methods screen

final paymentRequestBuilder = PaymentUIRequestBuilder(Order(amount: 1000, orderCode: "order-code"))
    .setMainMethod(MainMethodAll(1000))
    .setExtraOptions(ExtraOptions(shouldShowPaymentResultScreen: true));

Payment directly (without available methods screen)

final paymentRequestBuilder = PaymentUIRequestBuilder(Order(amount: 1000, orderCode: "order-code"))
    .setMainMethod(MainMethodVNPayGatewayQr(1000)) // use your expected method, but not MainMethodAll
    .setExtraOptions(ExtraOptions(shouldShowPaymentResultScreen: true));

Supported payment method:

MainMethodAll(int amount)
MainMethodVNPayGatewayQr(int amount)
MainMethodVNPayGatewayAtm(int amount)
MainMethodVNPayGatewayInternationalCard(int amount)
MainMethodVNPayGatewayMobileBanking(int amount)
MainMethodVNPayQrMms(int amount)
MainMethodVNPayEWallet(int amount)
MainMethodVNPayCustomer(int amount)
MainMethodVNPaySposCard(int amount)
MainMethodMomoGateway(int amount)
MainMethodCod(int amount)
MainMethodCash(int amount)
MainMethodRefInput(int amount, string methodCode)
MainMethodBankTransfer(int amount)
MainMethodInstallment(int amount)

Payment methods metadata config(Optional)

There are some methods must add more config to payment, For example VNPayEWallet. So you must be passing metadata into paymentRequestBuilder before call startUI.

paymentRequestBuilder.setMetadata(
    Metadata(
        vnPayEWallet: MetadataVnPayEWallet(
            partnerId: "0912345678", // Use phone number for partnerId, this is a recommendation from the EWallet team
            phone: "0912345678",
            name: "Nguyen Van A",
            email: "a.nv@mail.com"
        ),
    ),
);

Currently MinervaUI only supports following online payment methods:

all(amount: Double, metadata: [MethodMetadata]) // Using it if we wanna using built-in UI with full of allowed payment methods interface
vnPayQRMMS(amount: Double)
vnPayQRGateway(amount: Double)
vnPayATMGateway(amount: Double, route: BankRoute)
vnPayInternationalCardGateway(amount: Double)
vnPayQRReversal(amount: Double)
vnPayEWallet(amount: Double, customer: VNPayEWalletCustomer)
mobileBanking(amount: Double)
momoGateway(amount: Double)
sposApp(amount: Double)
cod(amount: Double)
cash(amount: Double)
refInput(amount: Double, subMethodCode: String)
pos(amount: Double)
bankTransfer(amount: Double)
installment(amount: Double)

Usage#

Open available methods screen#

Payment directly (without available methods screen)#

Payment methods metadata config(Optional)#

Generate payment request#

References#