Gateway Integration

Introduction

This is the most commonly known type of integration that you need to accelerate your business applications. The payment gateway integration will be done in simple few steps, minimum development efforts, and with various capabilities. Here, you display to your customer a list of the enabled and available gateways at your portal account. So, they can select which one suitable for their needs and they will be redirected directly to the gateway page to finish their payment.

---

How it Works

From a technical point of view, you have to get this integration done within your application with two simple calls to our API. The two calls to achieve this will be:

1. Call InitiatePayment endpoint (optional step):
   This step will simply return all available and enabled Payment Methods of your portal account with the commission charge that the customer may pay on the gateway. You can call it once and store the information at your end, then use that information in the next call.

2. Call ExecutePayment endpoint:
   This step will launch the actual transaction at the MyFatoorah platform by using the PaymentMethodId parameter. It will return a payment URL. After that, use this payment URL to redirect your customers to the payment page.

---

Initiate Payment

It is the preparation step that enables your system to collect all needed information about the available payment gateways. You should provide two parameters in your request body as follows:

• InvoiceAmount
  This is the total amount of the invoice. You should give the correct invoice amount after applying coupon code, taxes, redeem, fare updates, and so on. So that, you can have the correct service charge. If you will deduct the service charge from your customers, you need display its value to your buyers before processing the payment.

• CurrencyIso
  This is the currency of the given invoice amount.

The response of the InitiatePayment endpoint contains information about all enabled Payment Methods at your portal account, as described in the following parameters:

• PaymentMethodId
  It will be used in the ExecutePayment endpoint as the value of its PaymentMethodId parameter.
• IsDirectPayment
  If the value is true, you need to use the Direct Payment flow.
• PaymentMethodAr, PaymentMethodEn, PaymentMethodCode, and ImageUrl
  This information can be displayed to your customers to select which gateway they want to use.
• ServiceCharge, CurrencyIso
  The ServiceCharge in this CurrencyIso can be used ONLY in displaying the service charge to the customer before payment processing. It was calculated based on the provided InvoiceAmount parameter and the current rate of MyFatoorah exchange rate.
• TotalAmount
  The TotalAmount is the InvoiceAmount after applying the ServiceCharge to it. Also, it is the total amount that your customers will be charged with. From your Myfatoorah vendor account, you can set the service charge or commission charge to be on the vendor, customer, or split with the customer. If it is set to be on the customer or split with the customer, you should give the correct InvoiceAmount after applying coupon code, taxes, redeem, fare updates, and so on, so that you can have the right ServiceCharge to display its value to your customers before processing the payment. If it is set to be on the vendor, ServiceCharge will have a value but it will not be added to the TotalAmount, and there is no need to pass the correct InvoiceAmount.

Follow the below steps to change the Commission Charges settings:

1. Log in to the Myfatoorah vendor account using your Super Master Account.
2. Navigate to Profile → Commission Charges
3. From the Payment Methods list, choose the gateway that you want to determine from whom to deduct the Commission Charges.

👍

Initiate Payment

As a good practice, you don't have to call the InitiatePayment endpoint every time you need to execute payment, but you have to call it at least once to save the PaymentMethodId parameter that you will need in calling ExecutePayment endpoint. This practice is only valid if you don't care about the service charges calculations.

---

Execute Payment

Calling ExecutePayment endpoint is the actual payment execution step before proceeding to the payment gateway for the transaction to be done. This will redirect the buyers to the gateway to complete their payment process.

The ExecutePayment endpoint requires two mandatory parameters: (PaymentMethodId, InvoiceValue).

The "PaymentMethodId" parameter can be obtained from the InitiatePayment endpoint as described above.

👍

Payment Status

In this communication, MyFatoorah invokes the CallBackURL/ErrorUrl parameter once the payment is done, and this will allow you to redirect the customer to your receipt page, and update the payment status accordingly.

Once a transaction is done against a certain invoice, MyFatoorah initiates a call to the CallBackURL or ErrorUrl and provides a PaymentId as a GET parameter in the URL. The call is something like:
http://www.domain.com/myurl?paymentId=100201923790872553

Then you have to call GetPaymentStatus endpoint and pass the PaymentId to it, this will give you full information about the invoice and the transaction. This is a very important step and a good practice to ensure the payment response returned from the MyFatoorah end and is verified for more secure connectivity. You will find full details on how to implement the GetPaymentStatus endpoint on the Payment Inquiry section.

📘

Webhook

Also, you can use the Webhook feature, to notify your system when a transaction status changed event happens in your application.

This endpoint is also used in other integration types like Direct Payment, Tokenization, and Recurring Payment.

---