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	Pais 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.number	string	<= 5	Não	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": "[e-mail]",
  "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": "[e-mail]",
  "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
   }
}