Step 3: Frontend Integration

Now that you have the JWT token, you can build your frontend with Mercoa’s React components (recommended) or the embedded iFrame.

The React components give you full control over the design and layout of your frontend as well as an all-in-one experience for a quick start, while the embedded iFrame is a simpler drop-in integration for the Mercoa AP inbox.

1// Remember to install the react library: npm install --save @mercoa/react
2// Create a new page called bills.jsx
3
4import { useEffect, useState } from 'react'
5import { MercoaSession } from '@mercoa/react'
6
7const MercoaComponent = () => {
8  const [token, setToken] = useState(null)
9
10  useEffect(() => {
11    // Call Your Token Generator Endpoint
12    fetch('/generateMercoaToken').then(async (resp) => {
13      if (resp.status === 200) {
14        setToken(await resp.text())
15      }
16    })
17  }, [])
18
19  // NOTE: This is the all-in-one experience.
20  // See react.mercoa.com to learn how to use 
21  // our individual React components.
22  return <MercoaSession token={token} />
23}
24
25export default function Bills() {
26  return <MercoaComponent />
27}

Building with React

Mercoa’s React components (documented on react.mercoa.com) enable you to quickly ship and customize your payment platform’s frontend to fit your needs.

To render correctly, all Mercoa-powered frontend elements must be inside a <MercoaSession> component with a valid JWT token. The <MercoaSession> component handles authentication and provides a React Context called MercoaContext to its children, which encodes all the information you need to build your frontend.

To access this information in your frontend, you can drop in and customize Mercoa’s React components or use the useMercoaSession hook to render a completely custom frontend. For most use cases, the React components are the easiest way to get started.

For more details, see the React SDK documentation.

Customizing the Mercoa iFrame with a JWT Token

Mercoa also supports some customization of the embedded iFrame via a JWT token. When you generate a JWT token, you can pass in additional options in the request body:

1{
2  ...
3  "options": {
4    "entity": {
5      "enableMercoaPayments": true // If this is true, the user will run though Mercoa's KYB onboarding and will be able to use our built-in payment rails. If you are using your own payment rails, set this to false.
6    },
7    "invoice": {
8      "lineItems": "REQUIRED",
9      "status": [
10        "DRAFT",
11        "NEW",
12        "APPROVED",
13        "SCHEDULED",
14        "PENDING",
15        "PAID",
16        "CANCELED",
17        "FAILED"
18      ] // This is an array of invoice statuses that will be displayed in the Mercoa AP inbox.
19    },
20    "pages": {
21      "paymentMethods": true, // If this is true, the user will be able to add payment methods in the Mercoa AP inbox.
22      "representatives": true, // If this is true, the user will be able to add business representatives in the Mercoa AP inbox.
23      "notifications": true // If this is true, the user will be able to view notifications in the Mercoa AP inbox.
24    },
25    "vendors": {
26      "disableCreation": false, // If this is true, the user will not be able to create new vendors in the Mercoa AP inbox.
27      "network": "all" // This limits the vendors that will be displayed in the Mercoa AP inbox. Options are "entity" which limits vendors to those created by your customer, "platform" which will show all vendors created by any of your customers, or "all" which shows additional verified vendors created by Mercoa.
28    }
29  }
30}
Built with