Table of Contents

Table of Contents

Business problem

Payment at home with credit card represents 41% of the payments in Portugal today. With that in mind, this is a crucial feature for our customers to guarantee the best experience. The idea is to deliver a new method of payment (that we'll call here "Card at home"). To see more details: Feature - Payment with card at home

Panel

panelIconId	atlassian-warning
panelIcon	:warning:
bgColor	#FFBDAD

OUT OF SCOPE: Saving card networks (ex: Visa, Mastercard) used for “Card at home” payments for future reports. This information is not saved today.

Design analysis

Whitelabel proposed changes

PS: click on the images below to open (I don’t want to flood the document with big images).

Account payment methods

Image Added

Method payment selection

Image Added

Order confirmation

Image Added

As the flow will be similar to the payment with cash option we believe that we'll not need to change many details on this screen and we'll just change the information about the payment method.

Tracking modal

Image Added

Email receipt

Image Added

The email templates will also have to be updated to display correct payment method. Today, they only take into consideration the value of payment method, and not payment method brand.

Technical discovery

Architecture AS-IS

Image Modified

Sequence diagram (WIP)

...

intl-whitelabel-app

The app has two possible backend services: intl-whitelabel-graphql or intl-fulfillment-service. The ENABLE FULFILLMENT FT controls which service is used. Today, BK-PT is using whitelabel graphql, but BK-ES is using fulfillment service, for Dev environments.

intl-whitelabel-graphql

...

Winrest integration

The "Card at home" feature will affect the payload sent by partners-api to Winrest. We’ll need to send them the exact string of the new payment method so they can configure it on their platform (Aligned with Paulo Silva). The drawback of using payment type as CASH and a new payment method brand (eg. PAYMENT_ON_DELIVERY_CARD) is that the integration still works, but in Winrest reports these payments will be included as cash.

Tech solutions - comparison

Payment method brand

Payment method

PROS

Small changes in seven repositories: packages, fulfillment, payments, partners, WL graphql and WL app
Avoid the complexity of creating a new payment method

Avoid impacting WinRest roadmap

CONS

Impacts Winrest integration. They will have to change their code to take paymentMethodBrand into consideration

The scope of the changes necessary to include a new payment method is still unclear. This will affect the business logic of many services
Requires implementing the business logic of a new payment method from the start, instead of using the CASH workflow (high complexity in payment workflows)
Bigger changes increase the likelihood of conflicts between this feature and the ongoing refactoring of payment workflow

Tech solution 1 - Payment method brand approved by Winrest and Homeria

Using the CASH payment method, add PAYMENT_ON_DELIVERY_CARD payment method brand as an option. This solution was used also to implement Sodexo and Cheque Gourmet vouchers, which allowed us to take advantage of the groundwork laid by it: /wiki/spaces/IN/pages/3932717313. The exact changes needed are listed in Necessary changes section.

Pros and cons

Pros

Require small changes since the structure is very similar to Sodexo and Cheque Gourmet vouchers
- Reuse of components and structures that already exists on the code
Avoids the complexity of creating a new payment method from scratch, which impact many repositories and integrations

Cons

Since Winrest processes payment using paymentMethod field, it can’t differentiate between cash, voucher, or “card at home” payments. The same behavior happens today to Sodexo and Cheque Gourmet Vouchers, however. This will require changes on Winrest side to also evaluate paymentMethodBrand, othewise the driver won’t know if they have to take the card machine.

Necessary changes

intl-packages

Update Order types with new PaymentMethodBrand: https://github.com/rbilabs/intl-packages/blob/master/packages/orders/src/types/cart.ts#L862
Update SDKs

intl-fulfillment-service

Update method brand enum and intl-packages versions

intl-payment-service

Update method brand enum and intl-packages versions

intl-partners

Update method brand enum and intl-packages versions

intl-whitelabel-graphql

update graphql PaymentMethodBrand GraphQL definition: https://github.com/rbilabs/intl-whitelabel-graphql/blob/70138056e799d938a3a6bb39b502aba76c0a2c46/src/functions/graphql/schemas/payments.gql#L28
Save PAYMENT_ON_DELIVERY_CARD payments status as PAYMENT_REQUIRED

Code Block

language	js

          ...
          const isSodexoOrChequeGourmet = !!payment?.paymentMethodBrand;

          // we set the status to PAYMENT_REQUIRED for cash
          if ((isCashPayment && cashPaymentEnabled) || isSodexoOrChequeGourmet) {
            const updatedCart = {
              ...updatedOrder.cart,
              payment: {
                cardType,
                paymentMethodBrand: payment?.paymentMethodBrand || undefined,
              },
            } as ICart;

...

intl-

...

intl-packages/fulfilment

After receiving message to commit the order, the package will dispatch it to the appropiate POS Vendor and sends a message to SQS timeout queue. Here, the only payment validation check is for wrong order status and should not require changes to work with card payments at home.

Code Block

language	js

    if (isPaymentRequired) {
      // order must be in payment successful or payment required state to proceed
      if (
        status !== RbiOrderStatus.PAYMENT_SUCCESSFUL &&
        status !== RbiOrderStatus.PAYMENT_REQUIRED
      ) {
        throw new UnpaidCommitOrderError(rbiOrderId);
      }
    } else {
      // non payment required means order needs to be price successful
      if (status === RbiOrderStatus.PRICE_ERROR) {
        throw new OrderPriceError(rbiOrderId);
      } else if (status !== RbiOrderStatus.PRICE_SUCCESSFUL) {
        throw new OrderStatusMismatchError(rbiOrderId, RbiOrderStatus.PRICE_SUCCESSFUL);
      }
    }

For the winrest integration, the code messages the POS vendor configured in the rbi/{env}/{brand}/partners-api secret inRBI account secrets DynamoDB table.

Sodexo/Cheque Gourmet example

One recent change that appears to be very similar to what will be necessary for our case was the inclusion of sodexo and cheque gourmet as payment methods, that were implemented in

Jira Legacy

server	System JIRA
serverId	255417eb-03fa-3e2f-a6ba-05d325fec50d
key	PAYI-336

Winrest integration

To configure the integration with Winrest team, we’ll need to send them the exact string of the new payment method so they can configure it on their platform (Aligned with Paulo Silva). The drawback of using payment type as CASH and a new payment method brand (eg. CARD_AT_HOME) is that the integration still works, but in Winrest reports these payments will be included as cash.

Frontend