In accounts payable (AP), C3s are the vendor entities that want to send invoices to their customers. They can be individuals or businesses.

In Mercoa, you must create a vendor for each vendor that your customers will be paying invoices to through your platform.

Creating Vendors

Vendors can be created in the dashboard or with the create entity endpoint, and linked to a customer using the link payees endpoint.

They will also automatically be created and linked when a customer adds a new vendor through the React component or embed.

Creating the Vendor Entity

Using the create entity endpoint, create a new entity, and make sure the following fields are set:

1
{
2
  isPayee: true, // This marks the entity as able to receive funds
3
  isPayor: false, // This marks the entity as unable to pay funds
4
  isCustomer: false // This indicates that you don't have a direct relationship with this entity (aka, they're your customer's vendor)
5
}

This will automatically add the vendor to the platform network.

Capturing Vendor Details

If you don’t have the vendor’s details, you can use the generate onboarding link endpoint to create a link that the vendor can use to provide their details. This link will be valid for 24 hours. You can also use the send onboarding email endpoint to send the link to the vendor via email. This link will be valid for 7 days, and will be emailed to the entity email.

You can configure what details are required for the vendor using the dashboard or api.

Adding the Vendor to the Payer as a Counterparty

Once the vendor entity is created, you must link it to the payer.

You can link the vendor to any entity using the link payees endpoint. This will create a relationship between the two entities, and allow the payer to pay the vendor.

For example, if you have a payer Entity with id ent_8545a84e-a45f-41bf-bdf1-33b42a55812c, and a vendor Entity with id ent_21661ac1-a2a8-4465-a6c0-64474ba8181d, you can link them using the following request

1
from mercoa import Mercoa
2
from mercoa.entity_types import (
3
    CounterpartyCustomizationAccount,
4
    CounterpartyCustomizationRequest,
5
    EntityAddPayeesRequest,
6
)
7
8
client = Mercoa(
9
    token="YOUR_TOKEN",
10
)
11
client.entity.counterparty.add_payees(
12
    entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
13
    request=EntityAddPayeesRequest(
14
        payees=["ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"],
15
        customizations=[
16
            CounterpartyCustomizationRequest(
17
                counterparty_id="ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
18
                accounts=[
19
                    CounterpartyCustomizationAccount(
20
                        account_id="85866843",
21
                        postal_code="94105",
22
                        name_on_account="John Doe",
23
                    )
24
                ],
25
            )
26
        ],
27
    ),
28
)

Finding Counterparties

Once you have created and linked vendors to the payer, you can use the get counterparties endpoint to find the vendors linked to the payer.

1
from mercoa import Mercoa
2
3
client = Mercoa(
4
    token="YOUR_TOKEN",
5
)
6
client.entity.counterparty.find_payees(
7
    entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
8
    name="Big Box",
9
    payment_methods=True,
10
    invoice_metrics=True,
11
)

Hiding / Archiving Counterparties

If you don’t want a counterparty to show up for an Entity in the counterparty search, you can hide them using the hide payee from search endpoint.

1
from mercoa import Mercoa
2
from mercoa.entity_types import EntityHidePayeesRequest
3
4
client = Mercoa(
5
    token="YOUR_TOKEN",
6
)
7
client.entity.counterparty.hide_payees(
8
    entity_id="ent_8545a84e-a45f-41bf-bdf1-33b42a55812c",
9
    request=EntityHidePayeesRequest(
10
        payees=["ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"],
11
    ),
12
)

Verifying Vendors

If you’re using Mercoa’s built-in payment rails, your C3 entities will not require a formal KYB verification process. They only need the following information:

Vendor (C3) KYB Requirements

Vendor Portal

The vendor portal provides vendors with a self-service interface to manage their invoices, payment methods, and profile information. This portal allows vendors to:

• View and track their invoices and payment status
• Manage their payment methods (bank accounts, cards, etc.)
• Update their profile and business information
• View vendor credits and balances

Accessing the Vendor Portal

The vendor portal can be accessed at /vendors/portal/{orgId} where {orgId} is your organization ID.

Generating Vendor Portal Links

You can generate secure links for vendors to access their portal using the generate onboarding link endpoint with the redirectToPortal parameter set to true:

1
const portalLink = await mercoa.entity.getOnboardingLink(entityId, {
2
  expiresIn: '30d',
3
  type: 'payee',
4
  redirectToPortal: true
5
});

This creates a secure, time-limited link that vendors can use to access their portal without requiring separate login credentials.

Using the React Component

You can also generate vendor portal links using the <CounterpartyDetails> React component. This component provides a built-in interface for managing vendor information and generating portal access links.

Use the onboardingLinkOptions prop to configure portal link generation:

1
<CounterpartyDetails
2
  entityId="your-entity-id"
3
  counterpartyId="vendor-entity-id"
4
  onboardingLinkOptions={{
5
    expiresIn: '30d',
6
    type: 'payee',
7
    redirectToPortal: true
8
  }}
9
/>

This will display a user-friendly interface that allows you to generate and share vendor portal links directly from your application. For more details on using this component, see the CounterpartyDetails documentation.

Portal Features

Invoice Management

• View all invoices (pending, approved, paid, etc.)
• Track payment status and estimated payment dates
• Download invoice PDFs
• Add comments and communicate with payers

Payment Methods

• Add and manage bank accounts
• Add and manage payment cards
• Set default payment methods
• Verify payment method ownership

Profile Management

• Update business information
• Manage representatives and authorized users
• Upload required documents for KYB verification
• View and update tax information

Vendor Credits

• View available credits from overpayments or returns
• Track credit usage and remaining balances
• Apply credits to outstanding invoices

Integration with AP Workflow

The vendor portal integrates seamlessly with your AP workflow:

1. Onboarding: New vendors can complete their profile setup through the portal
2. Invoice Submission: Vendors can submit invoices directly through the portal (if enabled)
3. Payment Tracking: Vendors can track payment status in real-time
4. Communication: Built-in messaging for invoice-related communications
5. Compliance: Automatic KYB verification and document collection