In this article, you'll learn how to use North's Browser Post API for accepting payments in a React application. In part 2 of this series, you'll learn how to expand on your application by adding a React shopping cart to it.
You can follow along with this Node.js GitHub repo for the back-end web service and this React repo for the front-end ecommerce storefront.


Benefits of Using the Browser Post API
How do embedded payments work?
- The customer initiates the checkout process.
- The merchant makes an HTTPS request to the EPX key exchange service to obtain a terminal authorization code (TAC) token. The TAC token is an encrypted value that's required to guarantee transaction integrity and successful processing.
- Once the TAC is returned to the merchant website, the payment form page is loaded.
- The customer completes the form on the checkout page using one of multiple payment options, such as a credit card or mobile payment like Apple Pay. The form is configured to post the data directly to EPX's servers.
- The transaction is processed and the customer is taken to the redirect URL, where the transaction results are posted.
Implementing Embedded Payments in React
You'll also need to contact the North integration team for test credentials. When requesting the test credentials, make sure to provide your REDIRECT_URL. This is the URL that specifies which page a user should be redirected to once North processes the transaction. The results of the transaction are also posted on this URL. You will learn how to create the REDIRECT_URL later in this article.
Setting Up the Project
In the next steps, you will create the front-end application and the back-end application. You will then upload these applications to GitHub and deploy them.
Creating the Server
You will create your server using the Express framework. The server will have three routes that will be used to generate a TAC, receive the transaction payment results, and send the results to the front-end application.
Inside the paymentshub-react folder, create a new folder called api. Open the api folder in your terminal, and run the following command to initialize a Node.js project:
Next, open the api/package.json file and replace the scripts key-value pair with the following:
This script is used to start the Node server.
Make sure you also replace the main key-value pair with the following:
Next, run the following command in the terminal to install the required dependencies:
The purpose of each package is explained below.
- cors: enables cross-origin resource sharing.
- dotenv: loads environment variables from a .env file.
- express: creates a Node.js server.
- form-urlencoded: creates x-www-form-urlencoded string data.
- jsdom: traverses the XML tree returned from the North key exchange service and extracts the terminal authorization code.
- node-fetch@2: makes a POST request to the North key exchange service.
- querystring: parses the HTML form data received from the Browser Post API.
Next, create a new file named server.js in the api directory. This will act as the entry point into the Node server. Paste the code below inside the server.js file:
The server.js code contains three routes.
The /getTAC route is used to generate a terminal authorization code by making a POST request to the North sandbox key exchange URL. Make sure that the Content-Type header value for the POST request is set to: application/x-www-form-urlencoded.
The required fields for this POST request are amount, MAC, TRAN_NBR, TRAN_GROUP, and REDIRECT_URL.
- The amount field takes in the value of the total amount that should be deducted from the customer's credit card and should be in x.xx format. This means that the amount field should have two decimal places.
- The REDIRECT_URL field takes in the value of the redirect URL that you will provide to the North integration team during the request for test credentials.
- The MAC field takes in a value that is provided by the integration team.
- The TRAN_NBR field contains the transaction number and can be any numeric number with a maximum length of 10 digits.
- The TRAN_GROUP field is used to validate that the TRAN_CODE submitted during the transaction corresponds to a general category of payment types.
The response value for this request is in XML format. You use the jsdom package to traverse the XML tree and extract the TAC token. The TAC value is then sent to the front-end application as a response in JSON format. You can read more about these fields in the official documentation.
Secondly, the /paymentResult route receives the payment result from the Browser Post API in the form of an HTML form. You use the querystring package to extract the form fields and their values. This data is then stored in a variable called paymentResultData. In a real-world application, you can choose to save the transaction results to a database instead of storing them in a variable. This route then redirects the user to a page on the front-end application where the transaction results are displayed.
Lastly, the /getPaymentResult route receives a GET request from the front-end application and responds with the results of the transaction that are stored in the paymentResultData variable.
Most of the values for these fields are stored in environment variables, which you will set these up during deployment. You can access the full server code in this GitHub repo .
Creating the React App
Once the React app is created, navigate to the client folder and run the following command to install the required dependencies:
The purpose of each package is as follows:
- bootstrap: to style the React app.
- react-bootstrap: to provide Bootstrap 5 components that are built with React.
- react-router-dom: to set up routing in the React app.
Open the src/main.jsx file and replace the existing code with the following:
This sets up the BrowserRouter for the React app.
Next, open src/App.jsx and replace the existing code with the following:
This imports the BootStrap CSS file and various pages that you will create later. It also sets up four routes for the various pages in this app:
- Homepage: to display various products.
- ProductPage: to display the details of a particular product.
- Payment: to display the payment page.
- PaymentResults: to display the transaction results.
First, you will create the components that are used in this application.
Inside the src folder, create a folder called components. In the components folder, create a file called NavBar.jsx and paste in the code below:
This will create a simple navigation bar.
Next, create a file called ProductCard.jsx inside the components folder and add the code below:
The above code creates a reusable card component that you will use to display the details of a product on the homepage.
Now you can go ahead and create the pages. Inside the src folder, create a folder called pages. Make sure you create the files below inside the pages folder.
You will start by creating the Homepage.jsx file. Paste the following code inside this file:
The above code fetches various products from the Fake Store API and uses the ProductCard component to render them on the page.
Next, create a file ProductPage.jsx and paste in the code below:
The above code uses the id of a product, which is passed as a parameter during navigation to fetch the product details from the Fake Store API. It also contains a button that, when clicked, calls the getTAC() function. This function makes a POST request to the /getTAC route on the server and passes the product amount in the request body. It then receives a response, converts it to JSON, and checks whether the response contains the TAC. If the response contains a TAC value, it saves the TAC value and the product price to local storage and navigates the user to the payment page. Otherwise, it informs the user that an error occurred.
Remember to replace <YOUR-DEPLOYED-API-LINK/getTAC> with your actual API link once you deploy the web service.
Next, create a file called Payment.jsx and paste in the code below:
The code above retrieves the TAC and AMOUNT values from local storage and renders an HTML form that prompts the user for their payment details. The Account Number, Expiry Date, and CVV fields are already prefilled with the North card test details.
The form also contains other fields that are needed to make a payment. CUST_NBR, MERCH_NBR, DBA_NBR, and TERMINAL NBR are provided by North's Integration team to use in the sandbox environment. TRAN_CODE identifies the type of transaction you want to process and is related to the TRAN_GROUP field that you used to generate a TAC in the previous step. The most common value for the TRAN_CODE field is "SALE" for ecommerce transactions. The INDUSTRY_TYPE field takes a value of "E" for ecommerce transactions.
The values for most of these fields are stored in environment variables. You will set these up during deployment.
When the above form is submitted, it makes a POST request directly to the EPX server (the sandbox payment URL). This ensures that sensitive customer card details are not accessed by the site owner. The EPX server processes the payment and posts the results to the REDIRECT_URL that you provided to the Integration team.
Lastly, create a file called PaymentResults.jsx and paste in the code below:
This page makes a GET request to the /getPaymentResult endpoint on the server, converts the response to a JSON object, and stores the value in the paymentResult variable. The page renders the payment results by inspecting the AUTH_RESP field. For a credit or debit card payment, if the AUTH_RESP field contains the value "00", it means that the transaction has been approved. This page inspects the AUTH_RESP field, and if the value is equal to "00", it renders a "Payment succeeded" message along with the masked account number and the amount that has been deducted. Otherwise, it renders a "Payment failed" message along with the reason for failure.
You can access the full code for the React app on this GitHub repo .
Deploying the Front-End and the Back-End Applications
Before deploying, create the file named _redirects in the client/public folder and paste in the content below:
This will instruct Netlify to redirect all the routes to the index.html file. Without this, you won't be able to redirect to a specific page or reload a page.
Next, upload both applications' code to GitHub . Make sure each application has its own, separate repository.
Next, you will deploy your Node Express app on Render . Be sure to set 'yarn start' as the Start Command, and that you configure the following environment variables :
- MAC: this is provided by the North Integration team.
- PAYMENT_RESULT_PAGE_LINK: this URL will be for your React app hosted on Netlify, and it will end in /payment/result. you will add this URL later after you've deployed the application; leave it blank for now.
- REDIRECT_URL: this URL will be for the Node Express API hosted on Render, and it will end in /paymentResult. you will also provide this URL to the Integration team during deployment.
- TRAN_GROUP: use SALE.
To deploy the React app, check out the official documentation . You will also need to configure the following environment variables for your React app:
- VITE_CUST_NBR: this is provided by the North Integration team.
- VITE_DBA_NBR: this is provided by the North Integration team.
- VITE_INDUSTRY_TYPE: use E to specify that this transaction belongs to the ecommerce industry. You can learn more about the various values that you can use in this field in the EPX Data Dictionary, located in the Supplemental Resource Files folder.
- VITE_MERCH_NBR: this is provided by the North Integration team.
- VITE_TERMINAL_NBR: this is provided by the North Integration team.
- VITE_TRAN_CODE: use SALE.
Once your React app is deployed, copy the app link and append '/payment/result' to the end. Set this URL as the value for 'PAYMENT_RESULT_PAGE_LINK' in the Node Express API environment variables.
After your initial deployment, if changes are made to the environment variables, another deployment will be required for them to take effect. Changing environment variables may automatically trigger a new deployment, depending on how you've configured your deployment settings.
Once the deployment completes successfully, copy the deployed Node Express API link. You will use it to replace some dummy URLs in the React app.
Open the client/src/pages/ProductPage.jsx file and replace with the link for the deployed Node Express API. Do the same for the client/src/pages/PaymentResults.jsx file. Once you make the changes, push the code to GitHub, which will trigger an automatic redeployment of the React app on Netlify.
The deployed Node Express API URL with /paymentResult appended will also serve as the value of the REDIRECT_URL. Copy it, set the full URL including /paymentResult as the value for the REDIRECT_URL environment variable in Node Express, and provide it to the Integration team to get your test credentials.
Demonstrating the Final App
Click on View Details for the first product, which will display a page with product details.
Click on Purchase Now. This action generates a terminal authorization code and redirects you to the payment page.
The payment page is already prefilled with Visa card test details, so simply click Submit. This action submits the payment information to the EPX servers (the sandbox payment URL) and then redirects you to the payment details page, which shows that the payment succeeded, the amount deducted, and the masked account number.
If you provided the wrong payment details (e.g., an incorrect CVV number), the page should show that the payment failed and the reason why it failed.
Since the app uses test details, it will accept any three- or four-digit CVV number. To trigger the CVV error above, use a value with fewer than three or more than four digits.
Conclusion
In this guide, you've learned about embedded payments and their benefits. You also learned about the Browser Post API and how to use it to implement embedded payments in your React app to offer your users a seamless checkout experience. You can read the Browser Post API docs to learn more about how this API and other tools can meet your business needs.
To learn how to modify your app to add shopping cart functionality in ReactJS, check out Part 2 of this series.
How To Get Started
Contact North's Sales Engineering team to learn more about how the Browser Post API and other tools can meet your business needs.