IOPAY→Developers→Sellers API
Platform participants

Sellers API

Register and manage sellers, bank accounts and participants used in platform, marketplace and Split operations.

ObjectSeller
UseMarketplace · Split
AuthenticationBearer token
Seller lifecycle Registration Bank account
Overview

Overview

The Sellers API is intended for authorized partners who need to register and manage client sellers within IOPAY. The integration lets you create individual or business sellers and use the returned io_seller_id in the other API operations.

Identity

IO Seller ID.

Each seller receives an io_seller_id that must be persisted and used in the next operations.

Registration

Individual or business.

There are specific flows for registering individual sellers and companies.

Receipts

Linked bank account.

To receive payouts, the seller must have a linked bank account in the same holder's name.

Seller lifecycle

Seller flow

01 · RegistrationCreate the seller.

Send the individual or business data to the Sellers API.

02 · IdentificationStore the IO Seller ID.

Persist the io_seller_id returned by IOPAY.

03 · Bank accountTokenize and link.

Register a bank account in the same holder's name and associate the token with the seller.

04 · OperationsUse the seller.

The seller can then take part in the platform's compatible flows.

Payout. Sellers without a registered bank account can transact, but cannot receive payouts until a bank account in the same holder's name is linked.
Main endpoints

Registration

MethodEndpointUse
POST/v1/sellers/create/individualsCreate individual seller.
POST/v1/sellers/create/businessesCreate business seller.
PATCH/v1/sellers/update/individuals/:IO_SELLER_IDUpdate individual seller.
PATCH/v1/sellers/update/businesses/:IO_SELLER_IDUpdate business seller.
GET/v1/sellers/mcc_listGet available MCCs.

Create seller · Individual

POST /v1/sellers/create/individuals
curl --request POST \
  --url https://api.iopay.com.br/api/v1/sellers/create/individuals \
  --header 'Authorization: Bearer your_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "send_welcome_email": true,
    "mcc": 5499,
    "first_name": "André",
    "last_name": "Silva",
    "email": "[email protected]",
    "revenue": 4500,
    "phone_number": "(11)999999999",
    "cpf": "12345678909",
    "birthdate": "2000-01-01",
    "statement_descriptor": "LOJA ANDRE",
    "address": {
      "line1": "Av Paulista",
      "line2": "1000",
      "line3": "Sala 10",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01310100",
      "country_code": "BR"
    }
  }'
Identifier. Store the io_seller_id returned by IOPAY. It identifies the seller in later operations.

Create seller · Business

POST /v1/sellers/create/businesses
{
  "mcc": 5499,
  "statement_descriptor": "LOJA EXEMPLO",
  "revenue": 250000,
  "business": {
    "name": "Empresa Exemplo LTDA",
    "email": "[email protected]",
    "phone_number": "(11)999999999",
    "cnpj": "12345678000190",
    "opening_date": "2020-01-01",
    "website": "https://exemplo.com.br"
  },
  "owner": {
    "first_name": "André",
    "last_name": "Silva",
    "email": "[email protected]",
    "phone_number": "(11)999999999",
    "cpf": "12345678909",
    "birthdate": "1990-01-01"
  },
  "business_address": {
    "line1": "Av Paulista",
    "line2": "1000",
    "line3": "Sala 10",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zip_code": "01310-100",
    "country_code": "BR"
  },
  "owner_address": {
    "line1": "Rua Exemplo",
    "line2": "100",
    "line3": "Apto 10",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "zip_code": "01000-000",
    "country_code": "BR"
  }
}
Bank account

Enabling receipts

To allow payouts to the seller, first tokenize a bank account and then associate the returned token with the seller. The bank account must be in the same holder's name as the seller.

01 · AccountEnter the bank details.

Send bank, branch, account, holder and account type.

02 · TokenTokenize.

IOPAY turns the bank details into a secure token.

03 · AssociationLink it to the seller.

Associate the obtained token with the io_seller_id.

04 · PayoutAccount available.

The linked account can be used in compatible transfer flows.

Tokenize bank account

POST /v1/sellers/bank_accounts/tokenize/:IO_SELLER_ID/:ID_DEV
curl --request POST \
  --url https://api.iopay.com.br/api/v1/sellers/bank_accounts/tokenize/:IO_SELLER_ID/:ID_DEV \
  --header 'Authorization: Bearer your_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "holder_name": "ANDRE SILVA",
    "bank_code": "341",
    "routing_number": "0700",
    "account_number": "81929922",
    "ein": null,
    "taxpayer_id": "12345678909",
    "type": "checking"
  }'

The type field accepts checking for a checking account or savings for a savings account.

Link token to seller

POST /v1/sellers/bank_accounts/associate_bank_account/:ID_DEV
curl --request POST \
  --url https://api.iopay.com.br/api/v1/sellers/bank_accounts/associate_bank_account/:ID_DEV \
  --header 'Authorization: Bearer your_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "io_seller_id": "<IO_SELLER_ID>",
    "token": "<BANK_ACCOUNT_TOKEN>"
  }'
Account holder. Only bank accounts whose holder matches the seller's CPF or CNPJ can be linked.
Operation

Operating rules

  • The Sellers API must be enabled and authorized by IOPAY for the integration.
  • Use Bearer authentication in protected operations.
  • Persist the io_seller_id returned at registration.
  • Validate the seller type before using endpoints specific to individuals or businesses.
  • Link a bank account in the same holder's name before relying on payouts.
Technical reference

Official collection

See the full Sellers API collection in Postman to access all endpoints, request examples and available responses.

Open collection in Postman ↗