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

# Começando em Vendors

O serviço de [**Vendedores**](/api-reference/vendors/criacao-de-um-novo-vendedor) permite que facilitadores de pagamento identifiquem os beneficiários finais de suas transações durante sua execução. Este serviço deve ser utilizado por marketplaces, franquias, aplicativos de delivery, entre outros tipos de negócios que possuem exigência regulatória prevista na circular [Bacen N° 3978 de 23 Janeiro de 2020](https://normativos.bcb.gov.br/Lists/Normativos/Attachments/50905/Circ_3978_v3_P.pdf).

## Facilitador de pagamentos

São entidades que habilitam estabelecimentos comerciais a aceitarem pagamentos eletrônicos em nome de um adquirente.

## Fluxo de transação com vendedor

Para identificar um vendedor/fornecedor em uma transação você deve:

* Possuir o código de facilitador de pagamentos (`paymentFacilitatorId`) fornecido por cada bandeira.
  Obrigatório em alguns provedores, para mais detalhes [verifique a lista de provedores suportados](/documentations/vendors/provedores)

* Criar um vendedor, **[veja mais sobre a criação do vendor](/api-reference/vendors/criacao-de-um-novo-vendedor)**.

* Criar uma nova transação (**[charge](/api-reference/charges/realizar-nova-cobranca)**), informando o atributo `vendor`, informando o `id` do vendedor criado previamente, e o `paymentFacilitatorId` disponibilizado por sua respectiva bandeira.

## Informações sobre o vendedor

| Atributo             | Tipo   | Tamanho  | Obrigatório | Descrição                                                                  |
| -------------------- | ------ | -------- | ----------- | -------------------------------------------------------------------------- |
| referenceId          | string | `<= 15`  | Sim         | Identificador do vendedor no seu sistema. (Número máximo de caracteres 15) |
| identityType         | string | `enum`   | Sim         | Tipo de documento `CPF` ou `CNPJ`                                          |
| identity             | string | `<= 14`  | Sim         | Número do documento formato conforme tipo selecionado                      |
| mcc                  | string | `<= 10`  | Sim         | Código de segmento do lojista no adquirente                                |
| name                 | string | `<= 100` | Sim         | Nome Completo ou Razão Social                                              |
| email                | string | `<= 100` | Não         | Email do vendedor                                                          |
| phoneNumber          | string | `13`     | Não         | Telefone de contato do vendedor                                            |
| website              | string | `<= 100` | Não         | identificação do merchant id a ser utilizado                               |
| address.country      | string | `2`      | Sim         | País onde se localiza o endereço - Padrão ISO 3166-1 alpha-2               |
| address.state        | string | `2`      | Sim         | Estado                                                                     |
| address.city         | string | `<= 20`  | Sim         | Cidade                                                                     |
| address.district     | string | `<= 20`  | Sim         | Bairro                                                                     |
| address.zipCode      | string | `<= 10`  | Sim         | Código postal CEP                                                          |
| address.street       | string | `<= 100` | Sim         | Nome da rua/avenida/travessa                                               |
| address.streetNumber | string | `<= 5`   | Sim         | Número da rua                                                              |
| address.complement   | string | `<= 20`  | Não         | Complemento caso exista                                                    |

## Exemplo de criação de um vendedor

```bash theme={null}
curl --location --request POST \
  --url https://api.malga.io/v1/vendors \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
  --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
  --data '{
  "referenceId": "12345",
  "identityType": "CNPJ",
  "identity": "12345678000199",
  "mcc": "1234",
  "name": "Empresa Exemplo Ltda",
  "email": "contato@empresaexemplo.com",
  "phoneNumber": "5511999999999",
  "website": "https://www.empresaexemplo.com",
  "address": {
    "country": "BR",
    "state": "SP",
    "city": "São Paulo",
    "district": "Centro",
    "zipCode": "01001-000",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Apto 101"
  }
}'

```

```bash theme={null}
< HTTP/2 201

{
  "id": "db56bd6a-10d7-4039-9c68-fc4405a1a3e1",
  "referenceId": "12345",
  "identityType": "CNPJ",
  "identity": "12345678000199",
  "mcc": "1234",
  "name": "Empresa Exemplo Ltda",
  "email": "contato@empresaexemplo.com",
  "phoneNumber": "5511999999999",
  "website": "https://www.empresaexemplo.com",
  "address": {
    "country": "BR",
    "state": "SP",
    "city": "São Paulo",
    "district": "Centro",
    "zipCode": "01001-000",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Apto 101"
  },
  "updatedAt": "2024-06-26T12:34:56Z",
  "createdAt": "2024-06-01T08:00:00Z"
}
```

### Exemplo de cobrança com vendedor

```bash theme={null}
curl -X POST 'https://api.malga.io/v1/charges' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_SECRET_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "merchantId": "7f8870a2-71c9-4ef0-a531-82000e00b7e1",
      "amount": 150,
      "currency": "BRL",
      "statementDescriptor": "Pedido #231 loja joão",
      "capture": false,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 1
      },
      "paymentSource": {
        "sourceType": "card",
        "card": {
          "cardHolderName": "JOAO DA SILVA",
          "cardNumber": "4929564637987814",
          "cardCvv": "320",
          "cardExpirationDate": "06/2028"
        }
      },
      "vendor": {
        "id": "db56bd6a-10d7-4039-9c68-fc4405a1a3e1",
        "paymentFacilitatorId": "123456"
      }
  }'

```

```bash theme={null}
< HTTP/2 201
{
    "id": "3768a9bf-68fd-43e8-b7f6-e7d12ee22139",
    "clientId": "<YOUR_CLIENT_ID>",
    "merchantId": "46b433bf-79aa-4cb1-9eaa-cdaea42cb955",
    "description": null,
    "orderId": null,
    "createdAt": "2023-02-04T19:02:36.769Z",
    "amount": 150,
    "originalAmount": 150,
    "currency": "BRL",
    "statementDescriptor": "Pedido #231 loja joão",
    "capture": false,
    "isDispute": false,
    "status": "authorized",
    "paymentMethod": {
        "installments": 1,
        "paymentType": "credit"
    },
   "paymentSource": {
        "sourceType": "card",
        "cardId": "5afcdeb3-9e56-4dd9-bfee-e6b70c75b200"
    },
    "vendor": {
        "id": "db56bd6a-10d7-4039-9c68-fc4405a1a3e1",
        "paymentFacilitatorId": "123456"
    },
    "transactionRequests": [
        {
            "id": "7adfc4c6-567a-4ce0-a9a3-a08a21beff7f",
            "createdAt": "2023-10-04T19:02:37.106Z",
            "updatedAt": "2023-10-04T19:02:37.205Z",
            "idempotencyKey": "40efd5a0-1010-5c8d-9f75-0cd455553388",
            "providerId": "c6686322-f27b-90b2-a61b-106e7a564087",
            "providerType": "SANDBOX",
            "transactionId": "eb80f69e-de28-5060-8daf-da0fecc3b18f",
            "amount": 150,
            "authorizationCode": "9301661",
            "authorizationNsu": "4244270",
            "requestStatus": "success",
            "requestType": "authorization",
            "responseTs": "62ms",
            "providerAuthorization": {
                "networkAuthorizationCode": "7909027",
                "networkResponseCode": "8168918"
            }
        }
    ],
    "appInfo": null
   }
}
```