✅ Proposed Solution

...

After the user makes a payment request and closes the app, we need to ensure the user knows what happened to their order. This involves two developments: one is a new component to handle pending payments, and the other is a page to which the user will be redirected when attempting to view their there are pending payments available.

Create a reusable component to search for pending payment

On the main screen of the Whitelabel app, we will add a component similar to the order tracking feature. However, this component will specifically monitor pending payments that are still within the payment deadline.

The primary goal of this component is to provide clarity to users who may close the Whitelabel app during the payment process. It ensures that users do not mistakenly believe their payment has been canceled. Even if the user closes the app, we do not have the capability to cancel their payment request in the MBWay application.

This component will include a button labeled SHOW which will redirect the user to a new MBWay page, that will be detailed in the next topic.

...

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.

...

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.

...

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.

...

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.

...

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
Graphql/Fulfillment<-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->Frontend:Order Polling>Graphql/Fulfillment:     Commit Order\n(SaveCommitOnly)
Frontend<-DB: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.

...

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

...

Create a new feature flag

https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4362960979/Technical+refinement+-+Front+end#Task-1%3A-Create-a-new-feature-flag

ref:

time: 1h

...

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
);

export * from './mbway';

mbway: 'mbway',

mbway: string;

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

https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4362960979/Technical+refinement+-+Front+end#Task-2%3A1%3A-AddCreate-thea-new-payment-method-in-the-payment-state-and-structurefeature-flag

ref:

time: 8h1h

Add the new payment method in the payment

...

state and structure

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

https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4362960979/Technical+refinement+-+Front+end#Task-3%3A2%3A-Add-the-new-payment-method-in-the-payment-state-and-structure

ref:

time: 8h

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

This task aims to add mbway to the payment dropdown

https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4362960979/Technical+refinement+-+Front+end#Task-4%3A3%3A-CreateAdd-andthe-add-a-new-method-in-payment-method-option-structure

https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4362960979/Technical+refinement+-+Front+end#Task-4%3A-5%3ACreate-Adjustand-add-accounta-paymentnew-method-listsin-topayment-dealmethod-with-option-structure

https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4362960979/Technical+refinement+-+Front+end#Task-5%3A-Adjust--account-payment-method-lists-to-deal-with-the-new-method

ref:

...

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

https://rbictg.atlassian.net/wiki/spaces/IBC/pages/4449861673/Technical+refinement+-+Frontend#Task-6%3A-Adjust-the-receipt-email-to-show-the-correct-message-for-the-new-payment-method

...

This task covers the order commit, where we will add a new field called paymentRequestCreatedAt 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.

commitInput = {
  ...commitInput,
  payment: {
    paymentRequestCreatedAtpaymentRequestTimeLimit: 1627383253213, //timestamp
    ...commitInput.paymemt
  }
}

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.

...

export const routes = {
  pendingPage: 'pendingPage'
}

const MBWayPaymentPage: LazyRoute = lazyWithFallback(() => import('pages/mbway'));

return(
  ...
      <Route
        noIndex
        path={`${routes.pendingPage}/:orderId`}
        element={<pendingPage />}
      />
  ...
)

const pendingPage = () => {
  const { orderId } = useParams();
  const MBWayPendingPayment = LocalStorage.getItem(StorageKeys.PENDING_PAYMENT);
  
  let data;
  if(MBWayPendingPayment && MBWayPendingPayment.id === orderId){
    data = MBWayPendingPayment;
  } else {
    try{
      const orders = GetUserOrders(); 
      // map the order list to show only the latest information needed
      data = orders[0];
    }
  }
  
  return (
    <MBWayComponent data={data} />
  )
}

Backend

Packages

export declare enum PaymentMethodType {
    ...
    MBWay = 'MBWay'
}

export declare enum RBIPaymentType {
    ...
    MBWay = 'MBWay'
}

Commit Order Graphql/Fulfillment

export enum CartPaymentType {
  ...
  MBWay = 'MBWay',
}

export interface IPaycometPaymentSaleEvent extends IBaseSale {
  ...
  paymentRequestCreatedAt?: number;
}

paycometSale = {
  ...
  paymentRequestCreatedAt: payment.paymentRequestCreatedAt,
};

private mapPaymentMethod(
    params: IPaycometPaymentSaleEvent,
  ): {
    paymentMethodType: string;
    paymentMethod: string;
  } {
    ...

    return {
      paymentMethodType: params.paymentRequestCreatedAt &&
                           params.paymentMethodType ? 'MBWay' : 'scheme',
      paymentMethod: JSON.stringify({
        type: 'scheme',
        subtype: 'onetime',
      }),
    };
  }

//PaymentType = MBWay;
//PaymentMethodBrand = null;

CommitOrderInput
  Input.payment.mbway = {
    cellphone: string
    createdAt: number;
  }

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

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

input PaycometCaptureContextInput {
  amount: number!
  rbiOrderId: String!
  cellphone: number
  method: string!
}

input InitiatePaymentInput {
  storeId: String!
  paymentMethodType: String!
  cybersourcePaSetup: CybersourcePaSetupInput
  cybersourceCaptureContext: CybersourceCaptureContextInput
  paycometCaptureContext: PaycometCaptureContextInput
}

Create a new endpoint in Paycomet PSP Service

export enum TypePayment {
  ...
  MBWay = 'MBWay'
}

export abstract class PspInitiateRequestDto {
  @AmountApiProperty()
  @IsOptional()
  @IsNumber()
  public amount: number;
  
  @RbiOrderIdApiProperty()
  @IsString()
  @IsNotEmpty()
  public rbiOrderId!: string;
  
  @IsOptional()
  @IsNumber()
  public cellphone: number;
  
  @IsString()
  @IsNotEmpty()
  public method!: string;
}

public initiatePayment(
    @Headers('region') region: string,
    @Body() pspInitiateRequestDto: PspInitiateRequestDto,
  ): Promise<ApiResult<unknown>> {
    if(pspInitiateRequestDto.method === TypePayment.MBWAY){
      return initiatePaymentMBWay(region, pspInitiateRequestDto);
    }
    return throw ApiErrorHttpException.createConflict(
        new ApiError(501, 'Initiate Payment request failed', 'initiatePayment'),
    );
  }

public async initiatePaymentMBWay(
    region: string,
    request: InitiateRequestDto,
  ): Promise<InitiateResult> {
    try{
      const result = this.createPaymentMBWayRequest(request);
      // Add log about payment initiation attempt
      if(result.errorCode === TransactionStatus.SUCCESSFUL){
        return this.handleSuccesful(region, request, result);
      }
      return this.handleFailure(region, request, result);
    } catch(error){
      return this.handleFailure(region, request, error);
    }
}

Update the order to include the time left to finish the MB Way Payment

...

.

...

export const routes = {
  pendingPage: 'pendingPage'
}

const MBWayPaymentPage: LazyRoute = lazyWithFallback(() => import('pages/mbway'));

return(
  ...
      <Route
        noIndex
        path={`${routes.pendingPage}/:orderId`}
        element={<pendingPage />}
      />
  ...
)

const pendingPage = () => {
  const { orderId } = useParams();
  const MBWayPendingPayment = LocalStorage.getItem(StorageKeys.PENDING_PAYMENT);
  
  let data;
  if(MBWayPendingPayment && MBWayPendingPayment.id === orderId){
    data = MBWayPendingPayment;
  } else {
    try{
      const orders = GetUserOrders(); 
      // map the order list to show only the latest information needed
      data = orders[0];
    }
  }
  
  return (
    <MBWayComponent data={data} />
  )
}

Backend

Packages

This task aims to add mbway to the payment method enums

export declare enum PaymentMethodType {
    ...
    MBWay = 'MBWay'
}

export declare enum RBIPaymentType {
    ...
    MBWay = 'MBWay'
}

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

export enum CartPaymentType {
  ...
  MBWay = 'MBWay',
}

export interface IPaycometPaymentSaleEvent extends IBaseSale {
  ...
  paymentRequestTimeLimit?: number;
}

paycometSale = {
  ...
  paymentRequestTimeLimit: payment?.paymentRequestTimeLimit,
};

private mapPaymentMethod(
    params: IPaycometPaymentSaleEvent,
  ): {
    paymentMethodType: string;
    paymentMethod: string;
  } {
    ...

    return {
      paymentMethodType: params.paymentRequestTimeLimit &&
                           params.paymentMethodType ? 'MBWay' : 'scheme',
      paymentMethod: JSON.stringify({
        type: 'scheme',
        subtype: 'onetime',
      }),
    };
  }

//PaymentType = MBWay;
//PaymentMethodBrand = null;

CommitOrderInput
  Input.payment.mbway = {
    cellphone: string
    createdAt: number;
  }

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

input PaycometCaptureContextInput {
  amount: number!
  rbiOrderId: String!
  cellphone: number
  method: string!
}

input InitiatePaymentInput {
  storeId: String!
  paymentMethodType: String!
  cybersourcePaSetup: CybersourcePaSetupInput
  cybersourceCaptureContext: CybersourceCaptureContextInput
  paycometCaptureContext: PaycometCaptureContextInput
}

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.

export enum TypePayment {
  ...
  MBWay = 'MBWay'
}

export abstract class PspInitiateRequestDto {
  @AmountApiProperty()
  @IsOptional()
  @IsNumber()
  public amount: number;
  
  @RbiOrderIdApiProperty()
  @IsString()
  @IsNotEmpty()
  public rbiOrderId!: string;
  
  @IsOptional()
  @IsNumber()
  public cellphone: number;
  
  @IsString()
  @IsNotEmpty()
  public method!: string;
}

public initiatePayment(
    @Headers('region') region: string,
    @Body() pspInitiateRequestDto: PspInitiateRequestDto,
  ): Promise<ApiResult<unknown>> {
    if(pspInitiateRequestDto.method === TypePayment.MBWAY){
      return initiatePaymentMBWay(region, pspInitiateRequestDto);
    }
    return throw ApiErrorHttpException.createConflict(
        new ApiError(501, 'Initiate Payment request failed', 'initiatePayment'),
    );
  }

public async initiatePaymentMBWay(
    region: string,
    request: InitiateRequestDto,
  ): Promise<InitiateResult> {
    try{
      const result = this.createPaymentMBWayRequest(request);
      // Add log about payment initiation attempt
      if(result.errorCode === TransactionStatus.SUCCESSFUL){
        return this.handleSuccesful(region, request, result);
      }
      return this.handleFailure(region, request, result);
    } catch(error){
      return this.handleFailure(region, request, error);
    }
}

Update the makePayment endpoint in Paycomet PSP Service

private isOneTimePayment(paymentMethod: PaymentMethod): paymentMethod is OneTimeSchemeDto {
return (
    (paymentMethod.type === PaymentMethodType.Scheme ||
    paymentMethod.type === PaymentMethodType.MBWay) &&
    paymentMethod.subtype === SchemePaymentMethodType.OneTime
  );
}

public getPaymentLinkId(
  ...
): TypePayment | undefined {
  if (!methodId) {
    const paymentLink = transaction?.payment?.history.find(
      (order) =>
        ... ||
        order.methodId === TransactionMethodId.APPLEPAYLINK ||
        order.methodId === TransactionMethodId.MBWAY ||,
    );

    methodId = Number(paymentLink?.methodId);
  }
}

export enum TransactionMethodId {
  APPLEPAYLINK = 1,
  MBWAY = 38
}

Admin App

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

const paymentMethodType = order?.cart?.payment?.type;

if (paymentMethodType === 'MBWay') {
      return formatMessage({ id: paymentMethodBrandTranslationMap(paymentMethodType) });
    }
    
if (paymentMethodBrand) {
      return formatMessage({ id: paymentMethodBrandTranslationMap(paymentMethodBrand) });
    }

DOP

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

export const paymentMethodTranslation: Record<string, keyof LocalizedDictionary> = {
  MBWAY: `${pathPaymentTranslations}.mbway`,
};

Expeditor Tablet

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

export enum PaymentMethod {
  ...,
  MBWAY = "MBWAY",
}

...

Test Scenario	Steps	Screenshots
SCENARIO 1: The user makes a payment	The user selects MB Way from the payment list. The user fills in the phone number field. The user is redirected to the "Waiting for Payment" screen. The user accepts the payment in the MB Way app. The user returns to the whitelabel app. 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 )	The user selects MB Way from the payment list. The user fills in the phone number field. The user is redirected to the "Waiting for Payment" screen. The user closes the whitelabel app. The user accepts the payment in the MB Way app. The user returns to the whitelabel app. 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 )	The user selects MB Way from the payment list. The user fills in the phone number field. The user is redirected to the "Waiting for Payment" screen. The user closes the whitelabel app. The user accepts the payment in the MB Way app. 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.	The user selects MB Way from the payment list. The user fills in the phone number field. The user is redirected to the "Waiting for Payment" screen. The user closes the whitelabel app. The user returns to the whitelabel app. 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	The user selects MB Way from the payment list. The user fills in the phone number field with an incorrect number. 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	The user selects MB Way from the payment list. The user fills in the phone number field. The user is redirected to the "Waiting for Payment" screen. 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	The user selects MB Way from the payment list. The user fills in the phone number field. The user is redirected to the "Waiting for Payment" screen. The user cancels the payment in the MB Way app. 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	The user selects MB Way from the payment list. The user fills in the phone number field. The user is redirected to the "Waiting for Payment" screen. The user accepts the payment in the MB Way app. The user returns to the white-label app. The user is redirected to the order confirmation page. The user receives an email informing them that the order has been placed.
SCENARIO 10: The support tool user can see the order receipt	The order is placed. The support user can see the order in the support tool. The support user selects the order. The support user can see the order details. 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	The order is placed. The user can see the order in the DOP. The user selects the order. The user can see the order details. The user can see that the order is paid via the MB Way app.
SCENARIO 12: The DMP user can see the order receipt	The order is placed. The user can see the order in the DMP. The user selects the order. The user can see the order details. The user can see that the order is paid via the MB Way app.
SCENARIO 13: Make a refund in the support tool	The order is placed. The support user can see the order in the support tool. The support user selects the order. The support user can see the order details. The support user can make a refund.
SCENARIO 14: Make a partial refund in the support tool	The order is placed. The support user can see the order in the support tool. The support user selects the order. The support user can see the order details. The support user can make a partial refund.
SCENARIO 15: Make a refund in DMP	The order is placed. The user can see the order in the DMP. The user selects the order. The user can see the order details. The user can make a refund.
SCENARIO 16: Autorefund	The order is placed. The order is cancelled for any reason. The autorefund is triggered by the system. The support user can see the order in the support tool. The order is refunded
SCENARIO 17: Phone input error	The user selects MB Way from the payment list. The user fills in the phone number field a wrong value. The user see a payment error modal The user continues in the payment page Image Removed cannot click continue button.	Image Added
SCENARIO 18: Payment Refused	The user selects MB Way from the payment list. The user fills in the phone number field. The user is redirected to the "Waiting for Payment" screen. The user refuse the payment in the MB Way app. The user see a payment refused modal The user is redirect to cart page
SCENARIO 19: Payment Refused by time expired	The user selects MB Way from the payment list. The user fills in the phone number field a wrong value. The user is redirected to the "Waiting for Payment" screen. The user waits for time limit to end The user see a payment refused modal The user is redirect to cart page
SCENARIO 20: Insert a phone number without iso code country	The user selects MB Way from the payment list. The user fills in the phone number field with only phonenumber (e.g., 983334571). The user is redirect to waiting payment page.
SCENARIO 21: Insert a phone number with iso code country	The user selects MB Way from the payment list. The user fills in the phone number field with only phonenumber (e.g., 351 983334571). The user is redirect to waiting payment page.

...