Getting Started

Step 1: API Keys and Concepts

Creating your Mercoa Instance

To create your Mercoa instance, please book a call with our team here. We’ll help you get set up and answer any questions you may have.

Getting your API Keys

You can find your API key and Organization ID in the Mercoa Dashboard.

Do not expose this key on the front-end, it is for back-end use only.

Mercoa Architecture

Mercoa architecture overview

One of our goals at Mercoa is to provide a seamless and whitelabeled experience for your users. As part of the experience, Mercoa does not force users to create a new account or login to a different system.

Instead, Mercoa uses JWT tokens that you generate to transparently authenticate the user session on the frontend.

Steps to generate a token:

  1. User logs into your platform
  2. Find the Mercoa Entity that corresponds to that user’s business.
  3. Optional: Sync individual users and their roles. This is required for Approvals.
  4. Generate a JWT and pass it to the frontend.
  5. Use the JWT with our frontend SDK, React Components, or embeded iFrame.

Creating a Payer Entity

A payer entity is a person or business that pays bills on your platform or app.

When creating your first payer, we recommend using the Mercoa Dashboard.

You can also create a payer using the Mercoa API.

1from mercoa import (
2 AccountType,
3 Address,
4 BusinessProfileRequest,
5 BusinessType,
6 Ein,
7 EntityRequest,
8 PhoneNumber,
9 ProfileRequest,
10 TaxId,
11)
12from mercoa.client import Mercoa
13client = Mercoa(
14 token="YOUR_API_KEY",
15)
16client.entity.create(
17 request=EntityRequest(
18 is_customer=True,
19 is_payor=True,
20 is_payee=False,
21 account_type=AccountType.BUSINESS,
22 profile=ProfileRequest(
23 business=BusinessProfileRequest(
24 email="customer@acme.com",
25 legal_business_name="Acme Inc.",
26 website="http://www.acme.com",
27 business_type=BusinessType.LLC,
28 phone=PhoneNumber(
29 country_code="1",
30 number="4155551234",
31 ),
32 address=Address(
33 address_line_1="123 Main St",
34 city="San Francisco",
35 state_or_province="CA",
36 postal_code="94105",
37 country="US",
38 ),
39 tax_id=TaxId(
40 ein=Ein(
41 number="12-3456789",
42 ),
43 ),
44 ),
45 ),
46 ),
47)

You can create a payer with just a name and email address. Mercoa can automatically collect the rest of the payer’s information with our Payer Onboarding flow.

Once you’ve created your payer, you will have an entityId that you can use to create a token for the payer.

Entity IDs always start with ent_ followed by a UUID.