> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

# Sellers (Franchise)

> Manage franchise merchant identities and provider-specific credentials.

The Sellers API allows franchise merchants to register per-provider seller identities so the correct `merchant_id` is automatically resolved at payment time.

A merchant operating multiple franchise stores can assign different provider credentials (e.g., `CIELO_456` for Cielo, `ADYEN_789` for Adyen) to each store, and the system will pick the right one based on which provider processes the payment.

## Key Concepts

* **Organizational Scope:** A seller is created under a specific `account_code`, but is available organization-wide — any account within the same organization can reference that seller in payment requests.
* **Non-Blocking Resolution:** Franchise resolution never blocks a payment. If no mapping exists or the service is unavailable, the payment proceeds with the default `merchant_id` from the connection.
* **Polymorphic Detail:** The `payment_method` array uses a polymorphic `detail` structure. The shape of the detail object depends on the `payment_method_type` field (`CARD` → `detail.card.provider`, `APPLE_PAY` → `detail.wallet.provider`).
* **Soft Delete:** Deleting a seller soft-deletes the record and all associated payment method data. Past payments are unaffected.

## Authentication

All Sellers API endpoints require the following headers:

| Header               | Required           | Description                   |
| :------------------- | :----------------- | :---------------------------- |
| `public-api-key`     | Yes                | Your Yuno public API key.     |
| `private-secret-key` | Yes                | Your Yuno private secret key. |
| `X-account-code`     | Yes                | The account UUID identifier.  |
| `X-Idempotency-Key`  | Recommended (POST) | Unique UUID for safe retries. |

## Business Rules

1. **Uniqueness:** One seller per `(account_code, merchant_seller_id)`. Within a seller, each `(provider.id, payment_method_type)` must be unique.
2. **Multiple stores:** A merchant can register multiple `merchant_seller_id` values (one per franchise store).
3. **Multiple providers:** Each seller can have `payment_method` entries for multiple providers and payment method types.
4. **Seller reference:** Payments reference sellers via `seller_id` (Yuno UUID) or `merchant_seller_id` (merchant's identifier) — mutually exclusive.
5. **Field overrides:** Seller fields sent in a payment request override stored values for that payment only — not persisted back.
6. **Resolution priority:** Seller mapping takes precedence over the connection's `merchant_id`. If no mapping exists, the original `merchant_id` is used.
7. **Organizational scope:** Seller mappings are available at the organizational level — any account in the organization can use any seller registered under that organization.
8. **"Operates as Franchise" flag:** When enabled on a connection, the integration logic uses the `merchant_id` from the franchise mapping instead of the connection's `merchant_id`.
9. **Soft delete:** Deleting a seller soft-deletes the record and all payment method data. Past payments are unaffected. Future payments fall back to the connection's default `merchant_id`.
10. **Backward compatibility:** When neither seller reference field is present, the feature is fully bypassed.

<CardGroup cols={2}>
  <Card title="The Seller Object" icon="cube" href="/reference/sellers/the-seller-object">
    Understand the structure and attributes of a seller identity.
  </Card>

  <Card title="Using Sellers in Payments" icon="money-bill-transfer" href="/reference/sellers/using-sellers-in-payments">
    Learn how to reference sellers in your payment requests.
  </Card>
</CardGroup>