Apple Pay

Introduction

To provide a better user experience to your Apple Pay users, MyFatoorah is providing the Apple Pay embedded payment.

MyFatoorah Apple Pay embedded payment is a Javascript library that provides the Apple Pay button to your website. This button can be placed on your checkout page. When your customers click the button, MyFatoorah will direct the customers to the Apple Pay payment sheet page to authorize the payment. Then you can smoothly complete the payment using ExecutePayment endpoint by following the below steps.

Apple Pay Button

Apple Pay Payment Sheet Page

---

Verify your domain with Apple Pay

🚧

Note

This step is not required in the case of integrating using MyFatoorah IOS SDK.

To use Apple Pay Button, you need to register with Apple on all of your web domains that will show an Apple Pay button. This includes both top-level domains and subdomains. You need to do this for domains you use in both demo and live servers.

1. Host your domain verification file.
2. Register your domain with Myfatoorah.

Step1: Host your domain verification file

Steps:
1- Create a folder in the root path and name it ".well-known"
2- Paste the file inside the ".well-known" folder.
3- Test that the file is located in the correct place by opening the below URL
https://{example.com}/.well-known/apple-developer-merchantid-domain-association
Replace only the {example.com} with your site URL.

Path

https://{example.com}/.well-known/apple-developer-merchantid-domain-association

🚧

Domain Verification File

Do not remove the file from the server. Apple might need to revalidate the domain on a yearly basis and this file must be available for successful validation.

❗️

SSL

Domain should be TLS (HTTPS) enabled.

Step2: Register your domain with Myfatoorah

To register your domain with Myfatoorah and Apple Pay, you need to call v2/RegisterApplePayDomain endpoint. The request is a POST request with the following parameters.

Request

{ 
 "DomainName": "example.com" 
}

Success Response

{
  "IsSuccess": true,
  "Message": "OK",
  "ValidationErrors": null,
  "Data": null
}

Failed Response

{
  "IsSuccess": false,
  "Message": "Please make sure that domain verification file in the following path 'https://<YourDomainName>/.well-known/apple-developer-merchantid-domain-association' is valid and accessible",
  "ValidationErrors": null,
  "Data": null
}

End Point:

Test Url

https://apitest.myfatoorah.com/v2/RegisterApplePayDomain

Live Url

https://api.myfatoorah.com/v2/RegisterApplePayDomain

SAU

https://api-sa.myfatoorah.com/v2/RegisterApplePayDomain

Qatar

https://api-qa.myfatoorah.com/v2/RegisterApplePayDomain

📘

Notes

• Domain name in the request JSON should be domain name without a scheme (HTTPS)
• Header should have a valid token to access it.
• You may receive failed response with error detail in case of an invalid request.

---

How it Works

👍

Before You start

Kindly refer to the prerequisite section in the Embedded Payment.

The following detailed steps will explain how to add the MyFatoorah Apple Pay embedded payment form to your checkout page.

1. Include the Javascript library

HTML

// Test Environment
<script src="https://demo.myfatoorah.com/applepay/v3/applepay.js"></script>

// Live Environment Except Saudi Arabia and Qatar
<script src="https://portal.myfatoorah.com/applepay/v3/applepay.js"></script>

// Live Environment for Saudi Arabia
<script src="https://sa.myfatoorah.com/applepay/v3/applepay.js"></script>

// Live Environment for Qatar
<script src="https://qa.myfatoorah.com/applepay/v3/applepay.js"></script>

2. Add the form

You need to define a div element with a unique id attribute. The form will be loaded inside this div after passing the div id to the configuration variable.

HTML

<div id="card-element"></div>

3. Apple Pay Configuration

Now you need to add the configuration variables. Place the following snippet in a new script tag after loading the library in step 1, and replace the sessionId parameter with the "SessionId" you receive from the InitiateSession Endpoint. Moreover, you need to add the country code, currency code, and invoice amount.

For the currencyCode parameter check our list of ISO Lookups.

JavaScript

var config = {
    sessionId: "", // Here you add the "SessionId" you receive from InitiateSession Endpoint.
    countryCode: "KWT", // Here, add your Country Code. 
    currencyCode: "KWD", // Here, add your Currency Code.
    amount: "10", // Add the invoice amount.
    cardViewId: "card-element",
    callback: payment,
    sessionStarted: sessionStarted,
    sessionCanceled: sessionCanceled   
};

myFatoorahAP.init(config);

This will load the Apple Pay button on your page. When customers click the button, they will be redirected to the Apple Pay payment sheet to authorize the payment.

Update Display Amount (Optional)

You can update the amount to be displayed in the payment sheet after initializing the button by calling the following function:

JavaScript

myFatoorahAP.updateAmount(amount);

4. Call the payment function to load the response

In response to the payment function, you will receive the SessionId and CardBrand.

JavaScript

function payment(response) {
    // Here you need to pass session id to you backend here 
    var sessionId = response.sessionId;
    var cardBrand = response.cardBrand;
}

---

Personalized Apple Pay Button:

Achieve a personalized look for the Apple Pay button by following these steps:

• Omit the div element specified in step #2.
• Exclude the cardViewId field from the config object outlined in step #3.
• Create an Apple Pay button that follows the Apple Pay Button Guidelines.
• Once the customer clicks on the Apple Pay button on your checkout page, initiate the Apple Pay functionality by calling myFatoorahAP.initPayment().

5. Call the ExecutePayment Endpoint

Then, you need to send the SessionId to your server to process the actual transaction, which should be done in your backend environment using ExecutePayment endpoint.

❗️

Parameters conflict

Do not pass the PaymentMethodId parameter in the ExecutePayment request and use the SessionId parameter instead. As PaymentMethodId overwrite SessionId.

The "SessionId" you receive from InitiateSession Endpoint can not be used directly in ExecutePayment Endpoint.

---