> 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)