IOPAY→Developers→Sellers API
Participantes de plataforma

Sellers API

Cadastre e gerencie sellers, contas bancárias e participantes utilizados em operações de plataforma, marketplace e Split.

ObjetoSeller
UsoMarketplace · Split
AutenticaçãoBearer token
Ciclo do seller Cadastro Conta bancária
Visão geral

Visão geral

A Sellers API é destinada a parceiros autorizados que precisam cadastrar e gerenciar sellers clientes dentro da IOPAY. A integração permite criar sellers pessoa física ou jurídica e utilizar o io_seller_id retornado nas demais operações da API.

Identidade

IO Seller ID.

Cada seller recebe um io_seller_id que deve ser persistido e utilizado nas próximas operações.

Cadastro

Pessoa física ou jurídica.

Existem fluxos específicos para cadastro de sellers individuais e empresas.

Recebimento

Conta bancária vinculada.

Para receber payouts, o seller precisa possuir uma conta bancária de mesma titularidade vinculada.

Ciclo do seller

Fluxo do seller

01 · CadastroCrie o seller.

Envie os dados de pessoa física ou jurídica para a Sellers API.

02 · IdentificaçãoGuarde o IO Seller ID.

Persista o io_seller_id retornado pela IOPAY.

03 · Conta bancáriaTokenize e vincule.

Cadastre uma conta bancária de mesma titularidade e associe o token ao seller.

04 · OperaçãoUtilize o seller.

O seller pode então participar dos fluxos compatíveis da plataforma.

Payout. Sellers sem conta bancária cadastrada podem transacionar, mas não podem receber payout até que uma conta bancária de mesma titularidade seja vinculada.
Endpoints principais

Cadastro

MétodoEndpointUso
POST/v1/sellers/create/individualsCriar seller pessoa física.
POST/v1/sellers/create/businessesCriar seller pessoa jurídica.
PATCH/v1/sellers/update/individuals/:IO_SELLER_IDAtualizar seller pessoa física.
PATCH/v1/sellers/update/businesses/:IO_SELLER_IDAtualizar seller pessoa jurídica.
GET/v1/sellers/mcc_listConsultar MCCs disponíveis.

Criar seller · Pessoa física

POST /v1/sellers/create/individuals
curl --request POST \
  --url https://api.iopay.com.br/api/v1/sellers/create/individuals \
  --header 'Authorization: Bearer seu_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"
    }
  }'
Identificador. Guarde o io_seller_id retornado pela IOPAY. Ele identifica o seller nas operações posteriores.

Criar seller · Pessoa jurídica

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"
  }
}
Conta bancária

Habilitando recebimentos

Para permitir payouts para o seller, primeiro tokenize uma conta bancária e depois associe o token retornado ao seller. A conta bancária deve possuir a mesma titularidade do seller.

01 · ContaInforme os dados bancários.

Envie banco, agência, conta, titularidade e tipo da conta.

02 · TokenTokenize.

A IOPAY transforma os dados bancários em um token seguro.

03 · AssociaçãoVincule ao seller.

Associe o token obtido ao io_seller_id.

04 · PayoutConta disponível.

A conta vinculada poderá ser utilizada nos fluxos de transferência compatíveis.

Tokenizar conta bancária

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 seu_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"
  }'

O campo type aceita checking para conta corrente ou savings para poupança.

Vincular token ao 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 seu_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "io_seller_id": "<IO_SELLER_ID>",
    "token": "<BANK_ACCOUNT_TOKEN>"
  }'
Titularidade. Somente contas bancárias cuja titularidade corresponda ao CPF ou CNPJ do seller podem ser vinculadas.
Operação

Regras operacionais

  • A Sellers API precisa estar liberada e autorizada pela IOPAY para a integração.
  • Utilize autenticação Bearer nas operações protegidas.
  • Persista o io_seller_id retornado no cadastro.
  • Valide o tipo do seller antes de utilizar endpoints específicos para pessoa física ou jurídica.
  • Vincule uma conta bancária de mesma titularidade antes de depender de payouts.
Referência técnica

Collection oficial

Consulte a collection completa da Sellers API no Postman para acessar todos os endpoints, exemplos de requisição e respostas disponíveis.

Abrir collection no Postman ↗