Começando em Vendors

O serviço de Vendedores 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.

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
Criar um vendedor, veja mais sobre a criação do vendor.
Criar uma nova transação (charge), 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

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

< 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

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

< 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
   }
}

Comece na Malga

Conexões

Guias

Serviços adicionais

Começando em Vendors

Facilitador de pagamentos

Fluxo de transação com vendedor

Informações sobre o vendedor

Exemplo de criação de um vendedor

Exemplo de cobrança com vendedor

​Facilitador de pagamentos

​Fluxo de transação com vendedor

​Informações sobre o vendedor

​Exemplo de criação de um vendedor

​Exemplo de cobrança com vendedor

Facilitador de pagamentos

Fluxo de transação com vendedor

Informações sobre o vendedor

Exemplo de criação de um vendedor

Exemplo de cobrança com vendedor