[Solution] MB WAY - new payment method

Owned by Pereira, Filipa (Deactivated)
Last updated: Sept 30, 2024 by Capovilla, Evandro
17 min read

Document Status

REVIEWED

Document Owner(s)

@Capovilla, Evandro

Reviewers

@Raphael Ferreira Gomes
@Felipe Rooke
@Pereira, Filipa (Deactivated)
@Augusto Romao, Vinicius

Proposed Solution

Frontend - MB WAY

After selecting the MBWay payment method, we will implement two new screens for the user to enhance their payment experience.

Create a mb way payment method

  • This screen will provide the user with clear instructions on how to complete their payment using MBWay.

https://www.figma.com/design/RtD0UFtwuwXx14lbLCAPlr/branch/OWwFfjThLHwiZkB2dvJKgv/9.-Checkout?node-id=40562-25172&t=OZuRKZNKCPJTSM5t-0

  • It will include:

    • A brief overview of the MBWay payment process.

    • A field for the user to enter their phone number. This phone number is crucial, as it will be used by Paycomet to create the payment request in the user's MBWay account.

    • A "Confirm" button for the user to proceed after entering their phone number.

    • A regex to validate phone number input (only for ES and PT)

      • The user can fill with only phone number ( PT Example )

        • User Input: 98333 0099 (no spaces)

        • Input Mask: 98333-0099

        • Final Result: 351983330099

      • The user can fill with ISO Country Code and phone number ( PT Example )

        • User Input: 351 98333 0099 (no spaces)

        • Input Mask: +351 98333-0099

        • Example: 351983330099

Input Mask Example

Create a component to be used in payment page and recent orders

  • This screen will notify the user that their payment request has been successfully created.

  • It will include:

    • A message indicating that the payment request is pending and that the user should complete their payment via the MBWay app.

    • Information on the payment details such as the amount to be paid.

    • A countdown timer displaying the remaining time for the user to complete the payment.

    • Instructions on what to do if they need to cancel the order.

  • Additionally, an order polling process will be implemented on this screen to continuously check the payment status.

    • The polling will detect when the payment status changes to (PAYMENT_SUCESSFUL, INSERT_SUCESSFUL and UPDATE_SUCESSFUL).

    • Upon successful payment, the user will be automatically redirected to the /order-confirmation screen, where they will receive confirmation of their order and further instructions.

Frontend - Payment Tracking

After the user makes a payment request and closes the app, we need to ensure the user knows what happened to their order. This is a page to which the user will be redirected when there are pending payments available.

Remember that waiting for payment is a feature for all payment methods, but for it to be displayed, two conditions must be met:

  • The order must not be paid yet. (PRICE_SUCESSFUL and PAYMENT_REQUIRED)

  • The request must contain the paymentRequestTimeLimit property in the payment property.

Create Reusable Waiting Payment Page for order pending

This page reuses the same component as the mb payment details ensuring that users are familiar with the layout and can easily find the information they need. The primary objective of this page is to offer users comprehensive details about their pending MBWay payments, in scenarios where they might have closed the whitelabel app during the payment process. It helps clarify the payment status and guides users on completing their transactions successfully.

Importantly, only the most recent pending order will be displayed to the user, focusing their attention on the latest transaction.

Backend

Create Payment Request

To create a payment request for MBWay, it is necessary to add a new endpoint called InitiatePayment that handles the initialization of a new payment. Unlike the GenerateCheckoutLink, which is used for other payment methods, in the case of MBWay, we will not generate a link. Instead, we will request Paycomet to create a payment request in the customer's MBWay account.

The InitiatePayment endpoint was created specifically for this purpose: to request or initiate a payment that will be processed outside the whitelabel.

title Create Payment Request participant Frontend participant Graphql/Fulfillment participant DB participant Payment Service participant PSP Service participant Paycomet External Frontend->Graphql/Fulfillment: Initiate Payment Graphql/Fulfillment->Payment Service: Initiate Payment Payment Service->PSP Service:Initiate Payment PSP Service->Paycomet External:Payments Endpoint PSP Service<-Paycomet External:Result Payment Service<-PSP Service:Result Payment Service->DB: Update Order \n(PaymentRequestTimeLimit) Payment Service<-DB: Order Updated DB<-Payment Service: Create Payment in Payment Table DB->Payment Service: Payment Created Graphql/Fulfillment<-Payment Service:Result Frontend<-Graphql/Fulfillment:Result group Commit Order Frontend->Graphql/Fulfillment: Commit Order\n(SaveCommitOnly) Frontend<-Graphql/Fulfillment: Commit Order Result end loop Frontend->DB:Order Polling Frontend<-DB:Order Result end

For this communication, it is necessary to transmit two important pieces of information to the Paycomet service: the amount and the cellphone. The cellphone will be used by Paycomet to create a request in the user's MBWay account. Once the data reaches the Paycomet service, we will create a payload as mentioned below for the /payments endpoint of Paycomet.

With this, Paycomet will return whether the request was created or not, allowing us to handle this data at the beginning of the request in the frontend, ensuring direct communication of the responses. If the endpoint returns success, it means that the user received a payment request. Otherwise, the user did not receive any request, and we should inform the user to try again, either because they entered an unregistered number or due to an issue on Paycomet's side.

Endpoint POST: https://rest.paycomet.com/v1/payments

"payment": { "terminal": XXXXX, "order": "000012345", // from request "amount": "202", // from request "currency": "EUR", "methodId": "38", "secure": 1, "urlOk": "https://www.paycomet.com", // psp-outcome-endpoint "urlKo": "https://www.paycomet.com", // psp-outcome-endpoint "merchantData": { "customer": { "name": "John", // from request "surname": "Doe", // from request "email": "john@doe.com", // from request "mobilePhone": { "cc": "351", // from request "subscriber": "931301715" // from request } }, "billing": { "billAddrCountry": 620 // Portugual ISO } } }

Retrieve Payment Status

The retrieval of payment status data is performed through an order polling process that waits for the order to reach the status: PAYMENT_SUCCESSFUL. To facilitate this process, we utilize a webhook in the Paycomet service, which is triggered whenever the payment status is updated in the Paycomet payment service provider.

When the Paycomet service receives this information about the status change, it will trigger the payment services to notify that there has been a change. This will, in turn, trigger all other services so that the order is updated in the database and this information is reflected on the frontend.

title Payment Status

participant Frontend
participant Graphql/Fulfillment
participant DB
participant Payment Service
participant PSP Service
participant Paycomet External

Frontend->Frontend:Order Polling
PSP Service<-Paycomet External:Payment Status
Payment Service<-PSP Service:Payment Status
DB<-Payment Service: Update Order
Frontend<-DB:Order Result

Development

This section includes some code examples that will be developed. The examples serve as a guide for development, and good practices as well as testing should be adopted.

New payment method support

This first stage involves adding the main foundation for the new payment method. Since this task is repeated for all new payment methods, I will only provide the reference for each stage. This should be the first part of the frontend development; without it, it will not be possible to continue with the development of the subsequent screens.

Add new payment method icon

This task involves adding the icon to be used later by the whitelabel

import { SVGIconComponent } from '../types'; export const endered: SVGIconComponent = ({ title = '', ...props }) => ( //svg code );

ref: https://github.com/rbilabs/ctg-components-library/pull/399

Create a new feature flag

This task aims to create the feature flag in both launchdarkly and whitelabel

Technical refinement - Front end | Task 1: Create a new feature flag

ref:https://rbictg.atlassian.net/browse/IBFEC-1758

time: 1h

Add the new payment method in the payment state and structure

This task aims to create the mbway in payment state and structure

Technical refinement - Front end | Task 2: Add the new payment method in the payment state and structure

ref: https://rbictg.atlassian.net/browse/IBFEC-1761

time: 8h

Add the new method in payment-method structure and payment list

This task aims to add mbway to the payment dropdown

Technical refinement - Front end | Task 3: Add the new method in payment method structure

Technical refinement - Front end | Task 4: Create and add a new method in payment method option structure

Technical refinement - Front end | Task 5: Adjust account payment method lists to deal with the new method

ref: https://rbictg.atlassian.net/browse/IBFEC-1760

time: 2d

Adjust the receipt email to show the correct message for the new payment method

This task aims to adjust the email to include mbway as a payment method

Technical refinement - Frontend | Task 6: Adjust the receipt email to show the correct message for the new paymen...

ref:https://rbictg.atlassian.net/browse/IBFEC-1765

time: 2h

Setup MBWay Payment

This is the second stage of the development tasks in the frontend. This phase involves the development of MBWay, where the screens and payment handling will be developed.

Create a mb way payment method

This is the first payment screen via MBWay. After selecting this payment method from the dropdown, the screen with the phone number input field should appear. This involves both the development of the screen and the validation and masking of the input.

Handle Fulfillment Initiate

This task focuses more on handling the information after the user enters the phone number and clicks "Continue." This stage involves communication with the "Initiate Payment" endpoint and returning the result. Additionally, this screen includes the invocation of the error modal.

Handle Commit Order

This task covers the order commit, where we will add a new field called paymentRequestTimeLimit, which will be responsible for recording when the payment request was generated. This field will be used in the future on the "Waiting for Payment" screen. It is important to remember that saveCommitOnly must be enabled for the order commit in the backend to be activated.

Payment Pending Tracking

Tracking Page

This task involves handling the information for the "Waiting for Payment" screen when the payment request is made. Therefore, a generic screen should be developed that can be used by other future payment methods. Additionally, this screen should be displayed when the user closes the app and returns to the homepage, as long as there is still an active payment to be completed.

Backend

Packages

This task aims to add mbway to the payment method enums

Commit Order Graphql/Fulfillment

This task aims to add mbway to the payment method enums and modify the commit order to accept this new payment method, in addition to including the new field: paymentRequestTimeLimit

Create a new request to Graphql/Fulfillment to handle MB Way on Initiate Endpoint

This task aims to add the paycometCaptureContext field to the initiatePayment endpoint

Implementation example: https://github.com/rbilabs/intl-whitelabel-graphql/pull/1150

Create a new endpoint in Paycomet PSP Service

This task aims to create the initiatePayment endpoint on paycomet psp and also its functionality.

Update the makePayment endpoint in Paycomet PSP Service

Admin App

Adding mbway within the translation enum so that the Admin App knows this new payment method and selects the correct translation.

DOP

Adding mbway within the translation enum so that the DOP knows this new payment method and selects the correct translation

Expeditor Tablet

Adding the mbway inside the enum so that the expeditor tablet knows this new payment method.

Potential Challenges

The most complex part was understanding the payment flow via endpoint and how we would achieve the result of creating the initiate payment. Since this solution does not involve an iframe, it will slightly change the way this payment method is developed and how it handles edge cases.

Another problem was dealing with the fact that we cannot cancel an MB Way payment, only the user has the power to do that. This caused some user experience difficulties in the whitelabel solution, where the user, even outside the payment page, can still complete the payment if they are within the allowed time.

Configuration

LaunchDarkly

Feature Flag

Feature Flag

enable-mbway-payment

QA Plan

Test Scenario

Steps

Screenshots

Test Scenario

Steps

Screenshots

SCENARIO 1: The user makes a payment

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field.

  3. The user is redirected to the "Waiting for Payment" screen.

  4. The user accepts the payment in the MB Way app.

  5. The user returns to the whitelabel app.

  6. The user is redirected to the order confirmation page.

https://www.figma.com/design/RtD0UFtwuwXx14lbLCAPlr/branch/OWwFfjThLHwiZkB2dvJKgv/9.-Checkout?node-id=40558-24217&t=OZuRKZNKCPJTSM5t-0

SCENARIO 2: The user makes a payment and closes the whitelabel app ( Delivery )

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field.

  3. The user is redirected to the "Waiting for Payment" screen.

  4. The user closes the whitelabel app.

  5. The user accepts the payment in the MB Way app.

  6. The user returns to the whitelabel app.

  7. A tracking modal appears for the user to track the order.

 

 

 

https://www.figma.com/design/RtD0UFtwuwXx14lbLCAPlr/branch/OWwFfjThLHwiZkB2dvJKgv/9.-Checkout?node-id=42110-4286&t=OZuRKZNKCPJTSM5t-0

SCENARIO 3: The user makes a payment and closes the whitelabel app ( Pickup )

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field.

  3. The user is redirected to the "Waiting for Payment" screen.

  4. The user closes the whitelabel app.

  5. The user accepts the payment in the MB Way app.

  6. The user returns to the whitelabel app.

 

https://www.figma.com/design/RtD0UFtwuwXx14lbLCAPlr/branch/OWwFfjThLHwiZkB2dvJKgv/9.-Checkout?node-id=42110-4287&t=OZuRKZNKCPJTSM5t-0

SCENARIO 4: The user makes a payment, closes the whitelabel app, doesn't pay in the MB Way app, opens the whitelabel app, the payment is still valid and user is redirect to waiting payment page.

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field.

  3. The user is redirected to the "Waiting for Payment" screen.

  4. The user closes the whitelabel app.

  5. The user returns to the whitelabel app.

  6. The user is redirect to waiting payment page

https://www.figma.com/design/RtD0UFtwuwXx14lbLCAPlr/branch/OWwFfjThLHwiZkB2dvJKgv/9.-Checkout?node-id=42037-29391&t=G7781FC1ZSRNblsB-0

SCENARIO 6: The user enters an incorrect phone number

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field with an incorrect number.

  3. An error modal appears.

https://www.figma.com/design/RtD0UFtwuwXx14lbLCAPlr/branch/OWwFfjThLHwiZkB2dvJKgv/9.-Checkout?node-id=42037-29246&t=OZuRKZNKCPJTSM5t-0

SCENARIO 7: The user makes a payment and the time limit expires

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field.

  3. The user is redirected to the "Waiting for Payment" screen.

  4. The timer finishes, and an error modal appears.

https://www.figma.com/design/RtD0UFtwuwXx14lbLCAPlr/branch/OWwFfjThLHwiZkB2dvJKgv/9.-Checkout?node-id=42037-29247&t=OZuRKZNKCPJTSM5t-0

SCENARIO 8: The user makes a payment and cancels in the MB Way app

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field.

  3. The user is redirected to the "Waiting for Payment" screen.

  4. The user cancels the payment in the MB Way app.

  5. An error modal appears.

https://www.figma.com/design/RtD0UFtwuwXx14lbLCAPlr/branch/OWwFfjThLHwiZkB2dvJKgv/9.-Checkout?node-id=42037-29247&t=OZuRKZNKCPJTSM5t-0

 

SCENARIO 9: Guest receives the email after placing the order

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field.

  3. The user is redirected to the "Waiting for Payment" screen.

  4. The user accepts the payment in the MB Way app.

  5. The user returns to the white-label app.

  6. The user is redirected to the order confirmation page.

  7. The user receives an email informing them that the order has been placed.

 

 

SCENARIO 10: The support tool user can see the order receipt

  1. The order is placed.

  2. The support user can see the order in the support tool.

  3. The support user selects the order.

  4. The support user can see the order details.

  5. The support user can see that the order is paid via the MB Way app.

 

 

SCENARIO 11: The DOP user can see the order receipt

  1. The order is placed.

  2. The user can see the order in the DOP.

  3. The user selects the order.

  4. The user can see the order details.

  5. The user can see that the order is paid via the MB Way app.

 

 

SCENARIO 12: The DMP user can see the order receipt

  1. The order is placed.

  2. The user can see the order in the DMP.

  3. The user selects the order.

  4. The user can see the order details.

  5. The user can see that the order is paid via the MB Way app.

 

SCENARIO 13: Make a refund in the support tool

  1. The order is placed.

  2. The support user can see the order in the support tool.

  3. The support user selects the order.

  4. The support user can see the order details.

  5. The support user can make a refund.

 

 

SCENARIO 14: Make a partial refund in the support tool

  1. The order is placed.

  2. The support user can see the order in the support tool.

  3. The support user selects the order.

  4. The support user can see the order details.

  5. The support user can make a partial refund.

 

 

SCENARIO 15: Make a refund in DMP

  1. The order is placed.

  2. The user can see the order in the DMP.

  3. The user selects the order.

  4. The user can see the order details.

  5. The user can make a refund.

 

 

SCENARIO 16: Autorefund

  1. The order is placed.

  2. The order is cancelled for any reason.

  3. The autorefund is triggered by the system.

  4. The support user can see the order in the support tool.

  5. The order is refunded

 

 

SCENARIO 17: Phone input error

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field a wrong value.

  3. The user cannot click continue button.

 

SCENARIO 18: Payment Refused

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field.

  3. The user is redirected to the "Waiting for Payment" screen.

  4. The user refuse the payment in the MB Way app.

  5. The user see a payment refused modal

  6. The user is redirect to cart page

 

 

SCENARIO 19: Payment Refused by time expired

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field a wrong value.

  3. The user is redirected to the "Waiting for Payment" screen.

  4. The user waits for time limit to end

  5. The user see a payment refused modal

  6. The user is redirect to cart page

 

 

SCENARIO 20: Insert a phone number without iso code country

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field with only phonenumber (e.g., 983334571).

  3. The user is redirect to waiting payment page.

 

 

SCENARIO 21: Insert a phone number with iso code country

  1. The user selects MB Way from the payment list.

  2. The user fills in the phone number field with only phonenumber (e.g., 351 983334571).

  3. The user is redirect to waiting payment page.

 

 

How to test

Unfortunately, Paycomet does not provide a way to perform tests in a development environment. Therefore, it will not be possible to conduct an end-to-end test of this new feature. What will be described below is a way to simulate a response from Paycomet when the payment is completed in MB Way App.

Make a Payment

The first step is to follow the happy path flow of the payment method, that is, choose an order, go to the checkout screen, fill in the necessary information, select the MB Way payment method, enter the phone number: "351 931301715" and click on pay. After that, you will be redirected to the MB Way waiting screen, and now you need to proceed to the next step.

Make a request to notification in paycomet-service

Below you will find an example of how to create the notification request to the endpoint. After creating this request, make a call to the Paycomet service at the notification endpoint. If the request is correctly created, the order status will be updated to success, and the Whitelabel app will redirect the user to the order confirmation screen.