(This article was originally published on Medium)

This is part one of the tutorial, the second part can be found here.

Before we start

With the launch of PowerApps Portals in preview this July, I rolled up my sleeves to test its abilities. While this article doesn’t require you to have advanced knowledge of Dynamics Portals, Power Platform, CDS and Azure functions, I will not be going into an explanation of the basics of these, rather give the necessary background to understand the context of what we are doing here.

The steps to build the payment processing and screenshots are given for PowerApps Portals, but the same applies to the Dynamics Portal which is based on the same technology.

I will use the eWAY payment gateway, but this is not gateway specific — you can do it with PayPal and others. I found Paypal requires just a few more script lines

Ready? Let’s go.

Credit cards and PCI DSS

If you want to accept payments from your customers online, there are a few payment gateways available there for you. The part I’d like to focus on is capturing payment on the Dynamics/PowerApp Portals as a part of your business process which will allow you to automatically reconcile the payment to a contact or trigger dispatch of goods etc.

If your business accepts payments from customers using credit cards, the last thing you want is to store or process the actual card details. All businesses that store, process or transmit payment cardholder data must be PCI DSS compliant.

PCI DSS is an industry-standard aimed to protect cardholders and card schemes (Visa, Mastercard, etc) from fraud mainly and it’s mandated for any organisation that stores, processes or transmits cardholders data. The cost of compliance may be really high, but non-compliance is not worth the risk.

The good news is though that we live in the 21st century and this problem has been solved for us if the right patterns are used. The key idea is that your application must not “store, process or transmit” credit card details, but rather use the payment gateway to securely do it for you (and let them deal with all that compliance stuff).

The high-level components involved and interaction between them are as explained below.

1. Your application consisting of server and client-side renders the UI necessary
2. On the client-side (web page) you use your payment gateway’s embedded form to capture the credit card details which will send it to the payment gateway directly bypassing your application, but advising you some kind of a reference (or token or nonce) associated with that transaction.
3. Your application then retrieves the payment status from the payment gateway using that reference.

In this way, your application will not “see” the client customers details, but only operates using abstract references.

Let’s implement this on the Portal.

The whole solution will consist of the following elements :

• eWAY payment gateway — you’ll need to create a (free sandbox) account there.
• CDS entity “Payment” which will represent a record of a successful payment
• The payment page which embeds the eWAYs “Pay now button”.
• Processing page that will request payment status information and submits the record in CDS
• Receipt page that will display the transaction reference — this can be replaced with your business process (e.g. allocate resources, open access, dispatch goods etc).
• Portal Entity Form for submitting a new Payments record.
• An Azure Function which will help us to avoid writing a plugin for Portal.

Payment gateway

In this tutorial, for maximum simplicity and clarity, I’ll be using Australian eWAY payment gateway. It’s quite popular here down under and has good APIs, documentation and support. The similar approach with some modifications would apply for almost any other payment gateway providing similar functionality, including PayPal.

1. Go to the Partner Sign Up page https://go.eway.io/success/partner-registration and create your account and login credentials.
2. Login into the Sandbox environment as per the email that you will receive, url should be https://sandbox.myeway.com.au/Login.aspx
3. In the “My Account \ API Key” section in the “Pay Now Button HTML Snippet” section find the piece of JavaScript code that you will use in the portal and copy it in a safe place. Please note that the code already contains your API key in the “data-publicapikey” parameter which looks like a guid string with an “epk-” prefix.

<script src="https://secure.ewaypayments.com/scripts/eCrypt.js"
   class="eway-paynow-button"          
   data-publicapikey="<your payment gateway API key goes here>"
   data-amount="10000"          
   data-resulturl="<some url>"          
   data-currency="AUD" >      
</script>

We are done here for now.

CDS entity “Payment”

Fields

Go to your PowerApps environment or Dynamics 365 platform and create a new entity “Payment” with the following fields:

1. Primary field: “Reference” (Text)
2. “Amount” (floating-point number for simplicity in this example)
3. “Customer” (Customer)*
4. “Verification” (Text Area, 512 length)

*) We will not be actually using in this tutorial the field Customer, but this is a placeholder to associate payments to actual customer record when they log in or as part of your checkout logic, for example.

The result should look like below. Please note that the prefix “cr591” you see on the screenshot is environment specific and you will see other prefixes for your custom fields and the entity!

Form

On the “Forms” tab of your custom entity create a new form:

1. Type “Main” and name it as you wish
2. On the form editor place controls for “Amount” and “Verification” fields. The “Reference” field is added automatically, so leave it there too.
3. Save and Publish

The result should look like this (again, instead of “Cr591” you will see another prefix, as well as the Owner’s name):

OK, now let’s switch to the portal.

Create a portal (if you don’t have one)

This step is if you are trying this example from scratch in the PowerApps Portal, otherwise, you would have already a portal you are integrating the payments into.

In your Power Platform environment https://make.powerapps.com in the Apps section select “Create an App\Portal (preview)” and specify the name and 3rd level domain for your portal.

Please note as the latter must be unique globally, you will NOT be able to create “payments-demo”, so choose another prefix. In the URLs mentioned further, you will need to replace “payments-demo.powerappsportals.com” with “<your selected name>.powerappsportals.com”.

Click Create and wait a few minutes while your portal and the Portal Management apps are provisioned.

Receipt page

We will start from the end — the receipt page — as we will need this page to refer from other steps.

Entity permission

In order for the further Liquid code to work, you need to set up entity permissions.

In your Power Platform environment https://make.powerapps.com in the Apps section Navigate to your “Portal Management” app (should have been created automatically when the portal was created in the previous step).

Go to the “Security \ Entity Permissions” section in your Portal Management app and add new permission:

1. Name: Payment Permission
2. Entity Name: Payment
3. Scope: Global
4. Privileges: tick them all for this tutorial.
5. Save it
6. Now in the saved entity in the “Web Roles” section use “Add Existing Web Role” and add all the roles: “Anonymous users”, “Authenticated users” and “Administrators”.

Now we should be able to access the entity from the Liquid code.

Web Template

Create a new Web Template “ReceiptWebTemplate” and use the code below with some modifications:

• The first line is a Liquid statement that extracts a Payment entity record from CDS based on the parameter specified in the URL. There is no error handling as we should get to this page only if the entity form successfully submitted the new record and passed it’s id here. If you don’t get the record back, something wrong with the permissions, double-check that you completed the previous step.
• There Reference and Amount values are displayed using another Liquid syntax in {{ }}
• Replace “cr591” with the correct prefixes — please refer to the Payment entity in your CDS environment.

Page Template

Create a Page Template:

• Name: ReceiptPageTemplate
• Type: Web Template
• Web Template: ReceiptWebTemplate

Web Page

Create a Web Page:

• Name: Receipt
• Parent Page: Home
• Partial URL: receipt
• Page Template: ReceiptPageTemplate
• Published state: Published

You can test this page if you create manually a record in Payments entity and navigate to this page: <your portal name>.powerappsportals.com/receipt?payment=<your payment record id>

Create a Payment page

This page will render the ”Pay Now” button and load the payment form from the payment gateway which later will send the customers’ credit card details securely to the gateway.

Web Template

Create a new Web Template “PaymentWebTemplate” and insert the following pieces as explained below.

1. Create the basic page layout:

<div class="wrapper-body">
   <div class="container">
   
      <!-- Error handling section will go here -->      <h2>Make a paymemnt</h2>
      <p>Please make a payment of $100 AUD</p>      <div>
      <!-- Embedded  eWAY Pay Now button will go here -->
      </div>
   </div>
   <div class="push"></div>
</div><!-- Scripts will go here -->

2. Now let’s add the eWAY button snippet you copied earlier — insert it replacing the section “Embedded eWAY Pay Now button will go here”:

<script src=”https://secure.ewaypayments.com/scripts/eCrypt.js"
   class=”eway-paynow-button”
   data-publicapikey=<your public API key key goes here>
   data-amount=”10000"
   data-resulturl=”https://payments-demo.powerappsportals.com/processing"
   data-currency=”AUD” >
</script>

Please note that:

• data-publicapikey should contain your specific key issued by eWAY — part of the snippet code.
• data-resulturl points of the next step of the payment processing. You will need to replace “payments-demo.powerappsportals.com” with your portal url.
• data-amount contains the payment amount in cents of the currency (sorry, pounds and pence!), $100.00 in this example
• data-currency specifies the currency, Australian dollars in this example

3. Let’s add some error handling. Replace the section “Hidden error message block” with the following html:

<div id=”error” style=”display:none”>
   <p>There was an error processing your payment, please try again.</p>
</div>

At the end of the template replace the section ”Scripts will go here” with the following code which will show the section if there was an error processing the payment (on the further steps):

<script>
   var urlParams = new URLSearchParams(window.location.search);
   var error = urlParams.get(‘error’);
   
   // If there was an error — display a message
   if(error)
      $(“#error”).show();</script>

So, the full web page template script should be like the following (except teh modifications listed above):

Page Template

Create a Page Template:

• Name: PaymentPageTemplate
• Type: Web Template
• Web Template: PaymentWebTemplate

Web Page

Create a Web Page:

• Name: Payment
• Parent Page: Home
• Partial URL: payment
• Page Template: PaymentPageTemplate
• Published state: Published

Now navigate to <your portal name>.powerappsportals.com/payment and check that the result looks like below — click the “Pay Now” button.

So, what’s happening here, where does this form come from? This is delivered via the javascript “https://secure.ewaypayments.com/scripts/eCrypt.js”.

If the button doesn’t render, check your browser console if you see any errors there and double-check that you are using the right API key included in double quotes “” in the data-publicapikey parameter.

I’ll leave it here for this week and next week we will return to the second part and implement an Azure Function to validate payment and complete the flow.