> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/core-concepts/merchants.md).

# Merchants

*Brief explanation: A merchant is a business entity that accepts payments through Plexo. Merchants belong to a client and have payment method configurations and processing settings.*

## What is a Merchant?

In Plexo, a merchant represents a business or organization that processes payments. Merchants belong to a client (the top-level organization that holds API credentials). Each merchant has:

* **Unique Identity**: Merchant ID (provided by Plexo)
* **Payment Configuration**: Configured payment methods and processors
* **Business Information**: Name, legal details, contact information
* **Processing Settings**: Gateway or PayFac mode, 3DS configuration
* **Metadata**: Custom key-value pairs for additional data

{% hint style="info" %}
**Important**: API credentials (clientId and api-key) belong to the **client**, not individual merchants. All merchants under a client share the same API credentials for authentication.
{% endhint %}

## Merchant Hierarchy

```
Client (Organization)
  ├── API Credentials: clientId + api-key
  ├── Merchant 1
  │   ├── Payment Method: VISA (Totalnet)
  │   ├── Payment Method: MASTERCARD (Handy PayFac)
  │   └── Payment Method: PIX (Plexo PayFac)
  └── Merchant 2
      └── Payment Method: VISA (Fiserv)
```

A single client can have one or many merchants. Each merchant has independent:

* Merchant ID (Plexo-provided unique identifier)
* Payment method configurations
* Transaction histories
* Settlement accounts

**Shared across all merchants:**

* API credentials (clientId and api-key)
* Client-level settings and permissions

## Merchant Properties

**Key Fields:**

* `id` - Unique merchant identifier (integer, assigned by Plexo)
* `clientId` - Parent client/organization identifier
* `name` - Merchant business name
* `disabled` - Whether merchant is disabled (true = cannot process payments)
* `profile` - Business profile (legal name, tax ID, address, contact info)
* `paymentMethods` - Configured payment methods array

## Merchant Configuration

### Creating a Merchant

When creating a merchant, you only need to provide:

* **Name**: The merchant's business name (required)

The merchant is created with a Plexo-assigned ID. All other configuration is done after creation.

### Post-Creation Configuration

After a merchant is created, you can configure:

1. **Business Profile Information** (optional)
   * Legal name
   * Tax identification (RUT for Uruguay)
   * Business address
   * Contact details
2. **Payment Methods** (required to process payments)
   * Add payment methods the merchant will accept
   * Configure processor credentials per payment method
   * Set processing mode (Gateway or PayFac)
   * Enable/disable 3DS authentication

### Merchant Status

Merchants have a `disabled` boolean field:

* **disabled = false**: Active, can process payments
* **disabled = true**: Temporarily suspended, cannot process payments

Disabled merchants are retained for audit and reporting purposes. They do not appear in active merchant lists.

## Multiple Merchants

**Why Use Multiple Merchants?**

1. **Separate Business Units**: Different brands or divisions
2. **Geographic Separation**: Different countries or regions
3. **Accounting Separation**: Separate settlement accounts
4. **Risk Isolation**: Separate high-risk from low-risk transactions

## Related Resources

* [API Endpoints](/rest-api/api-reference/api-reference.md)
* [Merchant Management Guide](/rest-api/merchant-configuration/merchant-management.md)
* [Payment Methods Setup Guide](/rest-api/merchant-configuration/payment-methods-setup.md)
* [Gateway vs PayFac Modes](/rest-api/core-concepts/gateway-vs-payfac.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plexo.gitbook.io/rest-api/core-concepts/merchants.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.