Recebedor (seller)

Para a utilização do Split na cobrança ou em sessões com split, utilizamos o serviço de Sellers para cadastrar recebedores e política de recebimento nos provedores suportados pela Malga. É necessário cadastrar previamente os recebedores associados à sua subconta (merchant) antes de referenciá-los em splitRules — tanto em POST /v1/charges quanto em POST /v1/sessions. Na sessão, a existência dos sellers é validada na criação; na captura da cobrança, o fluxo de transações efetiva o vínculo com o provedor de acordo com o estado do recebedor.

Todo recebedor deve estar vinculado a um merchantId válido. A listagem de sellers sem merchant e o split agnóstico foram descontinuados. Veja os detalhes na release de jun/2026.

Status de recebedor

A criação de um Seller nos provedores ocorre de forma assíncrona, e além disso não é realizada de forma imediata, uma vez que critérios precisam ser analisados, assim como uma transação financeira. Para ser notificado sobre atualizações nesse processo, utilize os webhooks. Os status possíveis para um seller são:

Status	Descrição
pending	Informações recebidas e pendentes de validação no provedor
active	Recebedor ativo para transações e saque dos valores
partial	Apenas parte dos provedores está ativa para o recebedor
inactive	Recebedor não pode transacionar nem sacar valores
blocked	Recebedor bloqueado

Provedores suportados

Veja os provedores que suportam criação de Sellers na nossa tabela de provedores e meios de pagamento suportados.

Exemplo de criação de recebedor

Caso precise realizar um recebedor do tipo pessoa física, utilize a propriedade owner:

curl --location --request POST 'https://api.malga.io/v1/sellers' \
--header 'X-Client-Id: <YOUR_SECRET_KEY>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6",
    "owner": {
        "name": "Seller",
        "email": "seller@email.com",
        "phoneNumber": "85988350264",
        "birthdate": "1995-01-27",
        "document": {
            "type": "cpf",
            "number": "36243319067",
            "country": "BR"
        },
        "address": {
            "street": "Rua Nova Lua",
            "streetNumber": "30",
            "complement": "apto 208 bloco c",
            "zipCode": "61000-320",
            "country": "BR",
            "state": "CE",
            "city": "Maracanaú",
            "district": "AB"
        },
        "businessCategory": "OTHER_SERVICES"
    },
    "mcc": 1,
     "bankAccount": {
        "holderName": "Seller name",
        "holderDocument": "36243319067",
        "bank": "077",
        "branchNumber": "492",
        "branchCheckDigit": "1",
        "accountNumber": "4929",
        "accountCheckDigit": "22",
        "type": "conta_corrente"
    },
    "metadata": {[
      "key": "768093",
      "value": "informação adicional"
    ]},
    "transferPolicy": {
        "transferDay": 5,
        "transferEnabled": true,
        "transferInterval": "weekly",
        "automaticAnticipationEnabled": false,
        "anticipatableVolumePercentage": "",
        "automaticAnticipationType": "",
        "automaticAnticipationDays": "",
        "automaticAnticipation1025Delay": ""
    }
}'

< HTTP/2 201
{
    "id": "19d05a45-0e92-478e-8366-955231bcf3d6",
    "providers": [],
    "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6",
    "clientId": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
    "metadata": null,
    "owner": {
        "id": "1ae4bc8a-f8b2-4050-bc32-a90534a803c1",
        "updatedAt": "2023-07-11T22:06:14.078Z",
        "createdAt": "2023-07-11T22:06:14.078Z",
        "name": "Seller",
        "email": "seller@email.com",
        "phoneNumber": "85988350264",
        "birthdate": "1995-01-27T02:00:00.000Z",
        "address": {
            "country": "BR",
            "id": "ecccaa6c-63ac-4edf-8f5e-897f4cd56f76",
            "updatedAt": "2023-07-11T22:06:14.080Z",
            "createdAt": "2023-07-11T22:06:14.080Z",
            "street": "Rua Nova Lua",
            "streetNumber": "30",
            "complement": "apto 208 bloco c",
            "zipCode": "61000-320",
            "state": "CE",
            "city": "Maracanaú",
            "district": "AB",
        }
        "document": {
            "country": "BR",
            "id": "afcb459f-168c-4b74-a2cc-85b1756cb97f",
            "updatedAt": "2022-12-21T23:10:13.334Z",
            "createdAt": "2022-12-21T23:10:13.334Z",
            "type": "cpf",
            "number": "36243319067"
        }
    },
    "business": null,
    "bankAccount": {
        "id": "924ab8c7-df93-465b-97e3-c211c75a3e6e",
        "updateAT": "2023-02-28T18:00:00.573Z",
        "createdAt": "2023-02-28T18:00:00.573Z",
        "holderName": "Seller name",
        "holderDocument": "36243319067",
        "bank": "077",
        "branchNumber": "492",
        "branchCheckDigit": "1",
        "accountNumber": "4929",
        "accountCheckDigit": "22",
        "type": "conta_corrente"
    },
    "transferPolicy": {
        "id": "6d76b361-a9a8-4e26-865e-d1c790ad5c72",
        "updatedAt": "2023-07-05T18:55:29.809Z",
        "createdAt": "2023-07-05T18:55:29.809Z",
        "transferDay": 5,
        "transferEnabled": true,
        "transferInterval": "weekly",
        "automaticAnticipationEnabled": false,
        "anticipatableVolumePercentage": null,
        "automaticAnticipationType": null,
        "automaticAnticipationDays": null,
        "automaticAnticipation1025Delay": null
    },
    "mcc": 1,
    "status": "active"
}

Identificador do banco: `bank` e `ispb`

A bankAccount aceita dois identificadores da instituição financeira:

bank — código COMPE de 3 dígitos do banco (ex.: 077 para Banco Inter). Consulte a tabela de códigos COMPE dos principais bancos.
ispb — identificador ISPB da instituição no Sistema de Pagamentos Brasileiro, com 8 dígitos numéricos. A relação canônica de ISPBs é publicada pelo Banco Central (BCB).

Regras de uso:

Pelo menos um obrigatório. Na criação (POST /v1/sellers), envie bank, ispb ou ambos — não vale omitir os dois.
ispb tem precedência. Quando os dois forem enviados, o roteamento downstream usa o ispb; o bank permanece aceito como fallback/auxiliar.
Semântica PATCH. Em PATCH /v1/sellers/{id}, omitir a chave preserva o valor persistido; enviar null em um dos identificadores limpa aquele valor. A invariante “ao menos um identificador” é validada considerando o estado mesclado (payload + persistido).
Erro. Se o merge final ficar sem bank e sem ispb, a API responde 400 com error.key = bank_identifier_required.

Exemplo de criação identificando o banco apenas por `ispb`

curl --location --request POST 'https://api.malga.io/v1/sellers' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6",
    "owner": {
        "name": "Seller",
        "email": "seller@email.com",
        "phoneNumber": "85988350264",
        "birthdate": "1995-01-27",
        "document": {
            "type": "cpf",
            "number": "36243319067",
            "country": "BR"
        },
        "address": {
            "street": "Rua Nova Lua",
            "streetNumber": "30",
            "complement": "apto 208 bloco c",
            "zipCode": "61000-320",
            "country": "BR",
            "state": "CE",
            "city": "Maracanaú",
            "district": "AB"
        },
        "businessCategory": "OTHER_SERVICES"
    },
    "mcc": 1,
    "bankAccount": {
        "holderName": "Seller name",
        "holderDocument": "36243319067",
        "ispb": "60746948",
        "branchNumber": "492",
        "branchCheckDigit": "1",
        "accountNumber": "4929",
        "accountCheckDigit": "22",
        "type": "conta_corrente"
    }
}'

Exemplo de PATCH trocando `bank` por `ispb`

A troca é aceita porque o estado mesclado mantém ao menos um identificador (ispb):

curl --location --request PATCH 'https://api.malga.io/v1/sellers/19d05a45-0e92-478e-8366-955231bcf3d6' \
--header 'X-Client-Id: YOUR_CLIENT_ID' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "bankAccount": {
        "bank": null,
        "ispb": "60746948"
    }
}'

Caso precise cadastrar um recebedor do tipo pessoa jurídica, utilize as propriedades owner e business:

curl --location --request POST 'https://api.malga.io/v1/sellers' \
--header 'X-Client-Id: <YOUR_SECRET_KEY>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6",
    "owner": {
        "name": "Seller",
        "email": "seller@email.com",
        "phoneNumber": "85988350264",
        "birthdate": "1995-01-27",
        "document": {
            "type": "cpf",
            "number": "36243319067",
            "country": "BR"
        },
        "address": {
            "street": "Rua Nova Lua",
            "streetNumber": "30",
            "complement": "casa 4",
            "zipCode": "61000-320",
            "country": "BR",
            "state": "CE",
            "city": "Maracanaú",
            "district": "AB"
        },
        "businessCategory": "OTHER_SERVICES"
    },
    "business": {
        "name": "Seller business",
        "corporateReason": "Company social reason",
        "phoneNumber": "85988350264",
        "email": "sellerbusiness@email.com",
        "website": "www.sellerbusiness.com.br",
        "description": "Seller business",
        "facebook": "facebook Seller business",
        "twitter": "twitter Seller business",
        "openingDate": "1995-01-27",
        "address": {
            "street": "Rua Nova Lua",
            "streetNumber": "30",
            "complement": "sala 100",
            "zipCode": "61000-320",
            "country": "BR",
            "state": "CE",
            "city": "Maracanaú",
            "district": "AB"
        },
        "document": {
            "type": "cnpj",
            "number": "94938591000196",
            "country": "BR"
        }
    },
    "mcc": 4040,
    "bankAccount": {
        "holderName": "Seller name",
        "holderDocument": "36243319067",
        "bank": "077",
        "branchNumber": "492",
        "branchCheckDigit": "1",
        "accountNumber": "4929",
        "accountCheckDigit": "22",
        "type": "conta_corrente"
    },
    "transferPolicy": {
        "transferDay": 5,
        "transferEnabled": true,
        "transferInterval": "weekly",
        "automaticAnticipationEnabled": false,
        "anticipatableVolumePercentage": "",
        "automaticAnticipationType": "",
        "automaticAnticipationDays": "",
        "automaticAnticipation1025Delay": ""
    }
}'

< HTTP/2 201
< content-type: application/json; charset=utf-8
{
    "id": "19d05a45-0e92-478e-8366-955231bcf3d6",
    "providers": []
    "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6",
    "clientid": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
    "metadata": null,
    "owner": {
       "id": "8231ba21-3758-4bd7-b664-5b5fdeda37a0",
        "updatedAt": "2023-07-11T23:02:51.581Z",
        "createdAt": "2023-07-11T23:02:51.581Z",
        "name": "Seller",
        "email": "seller@email.com",
        "phoneNumber": "85988350264",
        "birthdate": "1995-01-27T02:00:00.000Z",
         "address": {
            "country": "BR",
            "id": "883631f0-fea0-4682-ae1a-f4ac6349e0d9",
            "updatedAt": "2023-07-11T23:02:51.585Z",
            "createdAt": "2023-07-11T23:02:51.585Z",
            "street": "Rua Nova Lua",
            "streetNumber": "30",
            "complement": "casa 4",
            "zipCode": "61000-320",
            "state": "CE",
            "city": "Maracanaú",
            "district": "AB"
        },
        "document": {
            "country": "BR",
            "id": "32543bbe-42c1-4000-9b68-d01a2735708e",
            "updatedAt": "2023-07-11T23:02:51.588Z",
            "createdAt": "2023-07-11T23:02:51.588Z",
            "type": "cpf",
            "number": "36243319067"
        },
    },
    "business": {
        "id": "607bb56a-974a-4d1d-9f56-cda865dfafbd",
        "updatedAt": "2023-07-11T23:02:51.571Z",
        "createdAt": "2023-07-11T23:02:51.571Z",
        "name": "Seller business",
        "corporateReason": "Company social reason",
        "phoneNumber": "85988350264",
        "email": "seller@email.com",
        "website": "www.sellerbusiness.com.br",
        "description": "Seller business",
        "facebook": "facebook Seller business",
        "twitter": "twitter Seller business",
        "openingDate": "1995-01-27",
         "address": {
            "country": "BR",
            "id": "b681dd2e-ebdb-4fad-8c8b-e703a17825ce",
            "updatedAt": "2023-07-11T23:02:51.574Z",
            "createdAt": "2023-07-11T23:02:51.574Z",
            "street": "Rua Nova Lua",
            "streetNumber": "30",
            "complement": "sala 100",
            "zipCode": "61000-320",
            "state": "CE",
            "city": "Maracanaú",
            "district": "AB"
        },
        "document": {
            "country": "BR",
            "id": "b9380f2c-a657-4f47-a7da-21f3bf08182c",
            "updatedAt": "2023-07-11T23:02:51.578Z",
            "createdAt": "2023-07-11T23:02:51.578Z",
            "type": "cnpj",
            "number": "94938591000196"
        }
    },
    "bankAccount": {
        "id": "f7ac3221-8f69-4276-b88b-34ddbe5ec24a",
        "updatedAt": "2023-07-11T23:02:51.563Z",
        "createdAt": "2023-07-11T23:02:51.563Z",
        "holderName": "Seller name",
        "holderDocument": "36243319067",
        "bank": "077",
        "branchNumber": "492",
        "branchCheckDigit": "1",
        "accountNumber": "4929",
        "accountCheckDigit": "22",
        "type": "conta_corrente"
    },
     "transferPolicy": {
        "id": "a04bca24-f7d1-4cb5-acce-41f12680e5bf",
        "updatedAt": "2023-07-11T23:02:51.567Z",
        "createdAt": "2023-07-11T23:02:51.567Z",
        "transferDay": "5",
        "transferEnabled": true,
        "transferInterval": "weekly",
        "automaticAnticipationEnabled": false,
        "anticipatableVolumePercentage": "",
        "automaticAnticipationType": "",
        "automaticAnticipationDays": "",
        "automaticAnticipation1025Delay": ""
    },
    "mcc": 1,
     "status": "active"
}

Consulte a tabela de códigos COMPE dos principais bancos para preencher bankAccount.bank. Como alternativa, o campo bankAccount.ispb pode ser usado para identificar a instituição financeira pelo código publicado pelo Banco Central (BCB).

Busca de recebedor pelo ID

curl --location --request GET 'https://api.malga.io/v1/sellers/19d05a45-0e92-478e-8366-955231bcf3d6' \
--header 'X-Client-Id: <YOUR_SECRET_KEY>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json'

< HTTP/2 201
{
    "id": "19d05a45-0e92-478e-8366-955231bcf3d6",
    "providers": {
        "providerType": "SANDBOX",
        "externalId": "1966811",
        "externalStatus": "active",
        "externalStatusReason": "ok",
        "status": "pending",
        "createdAt": "2022-12-21T23:10:13.498Z",
        "updatedAt": "2022-12-21T20:10:13.951Z"
    }
    "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6",
    "clientid": "e234eeb3-483d-4df2-87eb-1e2be5cdaccd",
    "metadata": null,
    "owner": {
        "id": "4fece86f-dd81-4115-ac55-efe6a6825a35",
        "updatedAt": "2023-07-11T23:16:10.101Z",
        "createdAt": "2023-07-11T23:16:10.101Z",
        "name": "Seller",
        "email": "seller@email.com",
        "phoneNumber": "85988350264",
        "birthdate": "1995-01-27",
        "address": {
            "country": "BR",
            "id": "547a525b-cf08-4345-b4a5-4fca0f831a62",
            "updatedAt": "2023-07-11T23:16:10.103Z",
            "createdAt": "2023-07-11T23:16:10.103Z",
            "street": "Rua Nova Lua",
            "streetNumber": "30",
            "complement": "casa 4",
            "zipCode": "61000-320",
            "state": "CE",
            "city": "Maracanaú",
            "district": "AB"
        },
        "document": {
            "country": "BR",
            "id": "babc1412-24c2-4c74-9791-3cd8b6926bcb",
            "updatedAt": "2023-07-11T23:16:10.105Z",
            "createdAt": "2023-07-11T23:16:10.105Z",
            "type": "cpf",
            "number": "36243319067"
        },
        "businessCategory": "OTHER_SERVICES"
    },
    "business": {
        "id": "cdbeb363-0729-4271-b116-f4aee5282227",
        "updatedAt": "2023-07-11T23:16:10.094Z",
        "createdAt": "2023-07-11T23:16:10.094Z",
        "name": "Seller business",
        "corporateReason": "Company social reason",
        "phoneNumber": "85988350264",
        "email": "sellerbusiness@email.com",
        "website": "www.sellerbusiness.com.br",
        "description": "Seller business",
        "facebook": "facebook Seller business",
        "twitter": "twitter Seller business",
        "openingDate": "1995-01-27",
        "address": {
           "country": "BR",
            "id": "ee658a16-1b54-43ba-8ee1-1b84e3df5bd0",
            "updatedAt": "2023-07-11T23:16:10.096Z",
            "createdAt": "2023-07-11T23:16:10.096Z",
            "street": "Rua Nova Lua",
            "streetNumber": "30",
            "complement": "sala 100",
            "zipCode": "61000-320",
            "state": "CE",
            "city": "Maracanaú",
            "district": "AB"
        },
        "document": {
            "country": "BR",
            "id": "f5ca5122-4479-44c1-9cad-08216df8c61e",
            "updatedAt": "2023-07-11T23:16:10.099Z",
            "createdAt": "2023-07-11T23:16:10.099Z",
            "type": "cnpj",
            "number": "94938591000196"
        }
    },
    "bankAccount": {
        "id": "a147a4fe-0e07-44e8-a58e-52806d5b72b3",
        "updatedAt": "2023-07-11T23:16:10.089Z",
        "createdAt": "2023-07-11T23:16:10.089Z",
        "holderName": "Seller name",
        "holderDocument": "36243319067",
        "bank": "077",
        "branchNumber": "492",
        "branchCheckDigit": "1",
        "accountNumber": "4929",
        "accountCheckDigit": "22",
        "type": "conta_corrente"
    },
    "transferPolicy": {
        "id": "eb896600-df76-4655-ab3f-8be651659e68",
        "updatedAt": "2023-07-11T23:16:10.092Z",
        "createdAt": "2023-07-11T23:16:10.092Z",
        "transferDay": "5",
        "transferEnabled": true,
        "transferInterval": "weekly",
        "automaticAnticipationEnabled": false,
        "anticipatableVolumePercentage": "",
        "automaticAnticipationType": "",
        "automaticAnticipationDays": "",
        "automaticAnticipation1025Delay": ""
    },
    "mcc": 1,
    "status": "active"
}

Edição de um recebedor

A atualização é parcial: envie apenas os campos que deseja alterar. Campos omitidos permanecem inalterados. Para recebedores do tipo pessoa física, utilize a propriedade owner. Para pessoa jurídica, utilize owner e business conforme necessário.

curl --location --request PATCH 'https://api.malga.io/v1/sellers/b1612460-0fef-447d-9590-97825cf60cf6' \
--header 'X-Client-Id: <YOUR_SECRET_KEY>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantId": "b1612460-0fef-447d-9590-97825cf60cf6",
    "owner": {
        "name": "Seller",
        "email": "seller@email.com",
        "phoneNumber": "85988350264",
        "birthdate": "1995-01-27",
        "document": {
            "type": "cpf",
            "number": "36243319067",
            "country": "BR"
        },
        "address": {
            "street": "Rua Nova Lua",
            "streetNumber": "30",
            "complement": "apto 208 bloco c",
            "zipCode": "61000-320",
            "country": "BR",
            "state": "CE",
            "city": "Maracanaú",
            "district": "AB"
        },
        "businessCategory": "OTHER_SERVICES"
    },
    "mcc": 1,
    "bankAccount": {
        "holderName": "Seller name",
        "holderDocument": "36243319067",
        "bank": "077",
        "branchNumber": "492",
        "branchCheckDigit": "1",
        "accountNumber": "4929",
        "accountCheckDigit": "22",
        "type": "conta_corrente"
    },
    "metadata": {[
      "key": "768093",
      "value": "informação adicional"
    ]},
    "transferPolicy": {
        "transferDay": 5,
        "transferEnabled": true,
        "transferInterval": "weekly",
        "automaticAnticipationEnabled": false,
        "anticipatableVolumePercentage": "",
        "automaticAnticipationType": "",
        "automaticAnticipationDays": "",
        "automaticAnticipation1025Delay": ""
    }
}'

Exclusão de um recebedor

curl --location --request DELETE 'https://api.malga.io/v1/sellers/6fa25050-4813-4209-9faa-4170a75dd8d7' \
--header 'X-Client-Id: <YOUR_SECRET_KEY>' \
--header 'X-Api-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merchantId": "46b433bf-79aa-4cb1-9eaa-cdaea42cb955"
}'

Comece na Malga

Conexões

Guias

Serviços adicionais

Recebedor (seller)

Status de recebedor

Provedores suportados

Exemplo de criação de recebedor

Identificador do banco: `bank` e `ispb`

Exemplo de criação identificando o banco apenas por `ispb`

Exemplo de PATCH trocando `bank` por `ispb`

Busca de recebedor pelo ID

Edição de um recebedor

Exclusão de um recebedor

​Status de recebedor

​Provedores suportados

​Exemplo de criação de recebedor

​Identificador do banco: bank e ispb

​Exemplo de criação identificando o banco apenas por ispb

​Exemplo de PATCH trocando bank por ispb

​Busca de recebedor pelo ID

​Edição de um recebedor

​Exclusão de um recebedor

Status de recebedor

Provedores suportados

Exemplo de criação de recebedor

Identificador do banco: `bank` e `ispb`

Exemplo de criação identificando o banco apenas por `ispb`

Exemplo de PATCH trocando `bank` por `ispb`

Busca de recebedor pelo ID

Edição de um recebedor

Exclusão de um recebedor