MyFatoorah Environment Setup

Table of Contents

Adding the MyFatoorah Dependency
Configuring Your Integration
Local Testing
- Local Webhook Configuration using Ngrok
Going to Production
- MyFatoorah Production Dashboard Configuration

Adding the MyFatoorah Dependency

Once you have setup account with MyFatoorah, add the Broadleaf MyFatoorah Maven dependency to your PaymentTransactionServices project.

<dependency>
    <groupId>com.broadleafcommerce.microservices</groupId>
    <artifactId>broadleaf-myfatoorah</artifactId>
</dependency>

Note	The dependency’s version will be pulled from the Broadleaf release train `pom.xml`.

Configuring Your Integration

MyFatoorah API Token Configuration

Log in to your MyFatoorah account
Find your API token by navigating to https://demo.myfatoorah.com/En/KWT/IntegrationSettings/ApiKey
Provide your API token via the following properties:

broadleaf:
  myfatoorah:
    api-config:
      api-token: {Your API token}
      currency: {Currency related to your API token}

Note	Each API token correlates to a single currency. If you need to support multiple currencies, then it’s expected that you’ll make use of multiple API tokens.

Webhook Configuration

In the MyFatoorah dashboard, you’ll need to enable webhook notifications to help the Broadleaf ecosystem be aware of 3DS & refund transaction results. This can be achieved by:

In the Myfatoorah dashboard, navigate to Integration Settings → Webhook Settings.
Enable webhooks
Declare the webhook url using the following structure to hit the PaymentTransactionServices endpoint: https://${host}/api/payment/webhooks/MY_FATOORAH?applicationId=${applicationId}&tenantId=${tenantId}.
- Make sure to replace ${host}, ${applicationId}, & ${tenantId} with the values relevant to your environment.
Enable the webhook secret key & gather the secret key value
Enable the Transaction Status Changed & Refund Status Changed events

Using the webhook secret key that was just gathered from the MyFatoorah dashboard, set the following property for in application.

broadleaf:
  myfatoorah:
    webhook-endpoint-secret: {Your webhook secret key}

Refund Fee Configuration

broadleaf:
  myfatoorah:
    refund-charge-on-customer: false
    service-charge-on-customer: false

Cart Operation Service Configuration

Add the following properties to declare the MY_FATOORAH gateway as an available payment method.

broadleaf:
  cartoperation:
    service:
      checkout:
        checkout-payment-method-options:
          - payment-method-type: CREDIT_CARD
            payment-method-gateway-type: MY_FATOORAH

MyFatoorah should be added to the following property to declare when transactions for this gateway should be executed, relative to other gateways, during checkout processing.

broadleaf:
  cartoperations:
    service:
      checkout:
        payment-gateway-priorities:
          - ...
          - MY_FATOORAH
          - ...

By default, Authorize transactions are executed by CartOps during checkout. With MyFatoorah, 3DS is required for all transactions. Additionally, MyFatoorah does not support webhook notifications for Authorize transactions. Therefore, we suggest that you use AuthorizeAndCapture transactions during checkout by setting the following property:

broadleaf:
  cartoperations:
    service:
      checkout:
        checkout-transaction-types:
          MY_FATOORAH: AUTHORIZE_AND_CAPTURE

Note

This property is application-discriminated, allowing different values to be provided on a per-tenant or per-application basis using the following property paths:

broadleaf.cartoperation.service.checkout.tenant.mytenant.checkout-transaction-types.MY_FATOORAH=AUTHORIZE_AND_CAPTURE
broadleaf.cartoperation.service.checkout.application.myapplication.checkout-transaction-types.MY_FATOORAH=AUTHORIZE_AND_CAPTURE

"mytenant" & "myapplication" being the Broadleaf Tenant and Application ids.

Order Operation Service Configuration

MyFatoorah should be added to the following property to declare when ReverseAuthorize or Refund transactions for this gateway should be executed, relative to other gateways, when cancelling a fulfillment.

broadleaf:
  orderoperation:
    service:
      payment:
        cancel-payment-gateway-priorities:
          - ...
          - MY_FATOORAH
          - ...

MyFatoorah should be added to the following property to declare when Capture transactions for this gateway should be executed, relative to other gateways, when capturing payment for a fulfillment.

broadleaf:
  orderoperation:
    service:
      payment:
        capture-payment-gateway-priorities:
          - ...
          - MY_FATOORAH
          - ...

MY_FATOORAH should be added to the following property to declare when Refund transactions for this gateway should be executed, relative to other gateways, when refunding payment for a fulfillment return.

broadleaf:
  orderoperation:
    service:
      payment:
        refund-payment-gateway-priorities:
          - ...
          - MY_FATOORAH
          - ...

Authentication Service Data Configuration

To access the endpoint to initiate a MyFatoorah session (part of the Embedded Payment frontend integration), the following permissions must be defined:

Initiate Session Permissions

INSERT INTO auth.blc_security_scope ("id", "name", "open")VALUES ('-710', 'MYFATOORAH_INIT_SESSION', 'N');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id)
VALUES('-1022', 'MYFATOORAH_INIT_SESSION', 'Y', '-710');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id) VALUES('-1023', 'MYFATOORAH_INIT_SESSION', 'Y', '-100');

INSERT INTO auth.blc_user_permission ("id", "archived", "last_updated", "name", "is_account_perm")
VALUES('-821', 'N', '1970-01-01 00:00:00.000', 'ALL_MYFATOORAH_INIT_SESSION', 'N');
INSERT INTO auth.blc_role_permission_xref (role_id, permission_id) VALUES ('-100', '-821');

INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('anonymous', 'MYFATOORAH_INIT_SESSION');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('anonymous', 'ALL_MYFATOORAH_INIT_SESSION');

INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('openapi', 'MYFATOORAH_INIT_SESSION');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('openapi', 'ALL_MYFATOORAH_INIT_SESSION');

To access the endpoint to get available payment options from MyFatoorah then following permissions must be defined:

Initiate Payment Permissions

INSERT INTO auth.blc_security_scope ("id", "name", "open")VALUES ('-811', 'MYFATOORAH_INIT_PAYMENT', 'N');
INSERT INTO auth.blc_permission_scope (id, "permission", is_permission_root, scope_id)
VALUES('-1023', 'MYFATOORAH_INIT_PAYMENT', 'Y', '-811');

INSERT INTO auth.blc_user_permission ("id", "archived", "last_updated", "name", "is_account_perm")
VALUES('-822', 'N', '1970-01-01 00:00:00.000', 'ALL_MYFATOORAH_INIT_PAYMENT', 'N');
INSERT INTO auth.blc_role_permission_xref (role_id, permission_id) VALUES ('-100', '-822');

INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('anonymous', 'MYFATOORAH_INIT_PAYMENT');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('anonymous', 'ALL_MYFATOORAH_INIT_PAYMENT');

INSERT INTO auth.blc_client_scopes ("id", "scope") VALUES ('openapi', 'MYFATOORAH_INIT_PAYMENT');
INSERT INTO auth.blc_client_permissions ("id", "permission") VALUES ('openapi', 'ALL_MYFATOORAH_INIT_PAYMENT');

Note	Based on the Auth data configured in your environment, you may need modify the ids defined in the scripts above.

Local Testing

When adding your integration in a local environment, the following properties must be declared:

broadleaf:
  myfatoorah:
    api-config:
      api-token: {Your production API token}
      currency: {Currency related to your API token}
    webhook-endpoint-secret: {Your production webhook secret key}

Local Webhook Configuration using Ngrok

localhost is not an allowed domain for MyFatoorah webhooks. To correctly direct webhook requests from MyFatoorah to your local instance, we suggest using Ngrok.

The following steps describe how to configure Ngrok in your local environment:

Execute ngrok http https://{yourAppUri}/ to build the tunnel to your local app. Replace yourAppUri with your app URI e.g. myapp.localhost:8456
In the Admin panel go to the Security → Authorization Servers, open your app configuration and click on Authorized Clients tab (/authorization-servers/{yourAppId}?form=authorizedClients). Add the Redirect Urls - https://c746-176-115-97-170.eu.ngrok.io/callback and https://c746-176-115-97-170.eu.ngrok.io/silent-callback.html to your Authorized Client.

Going to Production

When adding your integration to a production environment, the following properties must be declared:

broadleaf:
  myfatoorah:
    provider:
      apiUrl: https://api.myfatoorah.com/
    api-config:
      api-token: {Your production API token}
      currency: {Currency related to your API token}
    webhook-endpoint-secret: {Your production webhook secret key}

Note	For usage in Saudi Arabia, `https://api-sa.myfatoorah.com/` must be used as the `apiUrl`.

MyFatoorah Production Dashboard Configuration

In the MyFatoorah production dashboard, make sure to configure your webhooks using the production url path.