Skip to main content
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:
HeaderRequiredDescription
public-api-keyYesYour Yuno public API key.
private-secret-keyYesYour Yuno private secret key.
X-account-codeYesThe account UUID identifier.
X-Idempotency-KeyRecommended (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.

The Seller Object

Understand the structure and attributes of a seller identity.

Using Sellers in Payments

Learn how to reference sellers in your payment requests.