Facilitadores

Permite que os parceiros da ELO se identifiquem como facilitadores, associando os dados de seu usuário Merchant a um Payment Service Provider (PSP, ou facilitador). Tornando mais seguras e rastreáveis as transações efetuadas por um Merchant.

Feito para:  Facilitadores

Como funciona

Primeiros passos

  1. Leia Introdução ao GraphQL, com exemplos reais da nossa API.

  2. Crie um usuário no portal do desenvolvedor.

  3. Cadastre sua primeira aplicação.

  4. Utilize o dashboard para acessar suas configurações de acesso.

  5. Para explorar rapidamente as APIs aqui na página de documentação, use o console de GraphQL, na seção de referências. Nele, você pode ver as consultas de exemplo, executá-las e alterá-las.

Primeiros passos na plataforma de Desenvolvedores Elo

Jaydson GomesDesenvolvedor Evangelista

A associação de usuários Merchant ao PSP (Payment Service Provider, ou facilitador) torna possível a Elo e aos facilitadores identificar facilitadores e seus merchants associados.

Para acessar os recursos e informações disponibilizadas na Plataforma de APIs ELO é necessário antes que você cadastre e faça login com um usuário do tipo Merchant, após efetuar o login você receberá um access_token que deve ser utilizado nas chamadas para se identificar.

Os detalhes para cadastrar o usuário podem ser vistos na seção cadastro do portador.

Para realizar a associação é necessário utilizar a mutation associatePSPMerchant demonstrada abaixo: As requisições HTTPS devem possuir em seus cabeçalhos os dados necessários para o acesso ao serviço, neste caso o client_id e access_token:

mutation {
  associatePSPMerchant(
    input: {
      clientMutationId: "123456",
      legalId: "312312321321312",
      name: "Teste PSP",
      legalName: "Teste PSP",
      bankAccount: {
        type: SAVINGS,
        bankId: 104,
        branch: "1234",
        account: "1122334"
      },
      zip: "989832983293829",
      type: PHYSICAL,
      mcc: 5555,
      pvCode: "777",
      paymentTerm: {
        installments: 3,
        credit: 30,
        debit: 30
      }
    }
  )
  {
    clientMutationId,
    legalId
  }
}

Exemplo de Query PSP:

query {
  psp {
    id,
    name,
    legalName,
    description,
    legalIds{
      cnpj{
        number
      }
      cpf{
        number
      }
    }
    url
    merchants {
      edges {
        node {
          merchant {
            id
            name
          }
          mcc
          pvCode
          paymentTerm {
            installments
            credit
            debit
          }
          type
        }
      }
    }
  }
}

Para desassociar os dados de um PSP de um Merchant utilize a mutation a seguir fornecendo client_id e access_token:

mutation {
  dissociatePSPMerchant(
    input: {
      clientMutationId: "3333",
      pspId: 123,
      legalId: "3332221114"
    }
  )
  {
    clientMutationId,
    legalId
  }
}

Para buscar dados do PSP utilize a consulta a seguir fornecendo client_id e access_token:

query{
  psp {
    id,
    name,
    legalName,
    description,
    legalIds{
      cnpj{
        number
      }
      cpf{
        number
      }
    }
    url
    merchants{
      edges{
        node{
          merchant{
            id
            name
          }
          mcc
          pvCode
          paymentTerm{
            installments
            credit
            debit
          }
          type
        }
      }
    }
  }
}



Consulta um facilitador associado ao usuário

Pode retornar null se não existir facilitador na base de dados.

Argumentos:






Associa um comerciante a um facilitador.

Periodicamente os Facilitadores (PSP - Proxy and Payment Service Provider) devem atualizar os comerciantes (estabelecimentos comerciais) e então enviar as transações executadas com createPSPTransaction().

Para remover a associação, utilize dissociatePSPMerchant().

NOTA: por conveniência, associar um comerciante existente irá apenas atualizar os dados no sistema, não retornando erro.

NOTA: Lembre-se que em GraphQL pode-se enviar várias mutações de uma única vez, logo não é necessário executar várias requisições HTTP ao servidor, faça apenas uma e diferencie cada pedido com clientMutationId.

Argumentos:

input: AssociatePSPMerchantInput obrigatório



Desassocia um comerciante de um facilitador.

A associação deve ter sido previamente executada com associatePSPMerchant().

NOTA: as transações reportadas referentes ao comerciante não serão excluídas da base transacional.

NOTA: Lembre-se que em GraphQL pode-se enviar várias mutações de uma única vez, logo não é necessário executar várias requisições HTTP ao servidor, faça apenas uma e diferencie cada pedido com clientMutationId.

Argumentos:

input: DissociatePSPMerchantInput obrigatório






Entrada para Conta Bancária

Campos:

type

:

BankAccountType obrigatório

Se é conta poupança ou corrente


bankId

:

Int obrigatório

Código do Banco, ex: 1 (Banco do Brasil), 237 (Bradesco)


branch

:

String obrigatório

Agência, com dígito verificador.


account

:

String obrigatório

Número da conta, com dígito verificador.



Entrada para Dados de pagamento

Campos:

installments

:

Int

Informar o número de parcelas máximas acordado com o Estabelecimento comercial para pagamento de transações de Crédito parcelado pelo Lojista.


credit

:

Int

Informar prazo acordado com o Estabelecimento comercial para pagamento de transações de Crédito à vista.


debit

:

Int

Informar prazo acordado com o Estabelecimento comercial para pagamento de transações de Débito.



Entrada para mutação associatePSPMerchant().

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.


legalId

:

String obrigatório

Documento Legal (CNPJ ou CPF) que identifica o comerciante.

Apenas dígitos, sem hífen ou pontos.


name

:

String obrigatório

Nome Fantasia do Comerciante


legalName

:

String obrigatório

Razão Social do Comerciante


bankAccount

:

BankAccountInput obrigatório

Conta bancária para pagamento do Comerciante.


zip

:

String

Código postal (opcional).


type

:

PSPPersonType

Indica se o estabelecimento comercial opera como Pessoa Física ou como Pessoa Jurídica.


mcc

:

Int obrigatório

Código ISO18245 da categoria de comerciante (MCC) utilizado no ponto de venda.


pvCode

:

String

Código do Ponto de Venda na base do facilitador.


paymentTerm

:

PaymentTermInput

Dados da forma de pagamento



Entrada para mutação dissociatePSPMerchant().

Compatível com Relay.

Campos:

clientMutationId

:

String

Identificador de cliente opaco, normalmente em formato UUIDv4.

Deve ser usado por clientes para rastrear mutações e respostas, podendo ser usado pelo servidor para perder requisições duplicadas devido a falhas de rede e retransmissões.

Compatível com Relay.


pspId

:

Int obrigatório

Código do Facilitador cadastrado com a Elo.

Em geral será null, utilizando o Facilitador associado ao usuário da API.

Sistemas de gerência de facilitadores, por exemplo sistemas internos da Elo poderão utilizar este parâmetro para atuar sobre um facilitador em específico.

Facilitadores não tem acesso a outro código além do seu próprio, ou seja, devem passar seu próprio código (i.e: omitir o parâmetro).


legalId

:

String obrigatório

Documento Legal (CNPJ ou CPF) que identifica o comerciante.

Apenas dígitos, sem hífen ou pontos.






Toda a possível identificação legal de uma empresa.

Campos:

cnpj

:

CNPJ

cpf

:

CPF


Conexão de comerciante (Merchant) e associação com facilitador (PSP) em conformidade com o Relay.

Campos:

pageInfo

:

PageInfo obrigatório

Cursor opaco para ser usado com queries (consultas) after ou before.


edges

:

list de PSPMerchantAssociationsEdge

Lista de arestas que compõem esta conexão.


totalCount

:

Int

Contagem total de objetos nesta conexão.

Arestas são limitadas a cursores before e after, assim como primeiras e últimas contagens. Assim o tamanho de arestas é possivelmente menor que a conexão como um todo.

totalCount, se não for null, indica o número total de itens na conexão considerando-se o filtro.



Fornecedor de serviço de pagamento.

Há cerca de 150 facilitadores no mercado. Um exemplo de facilitador conhecido hoje é o PagSeguro.

Campos:

id

:

ID obrigatório

name

:

String obrigatório

legalName

:

String obrigatório

description

:

String

legalIds

:

PSPAssociateLegalIds obrigatório

url

:

String

merchants

(


first:

Int

Limita a lista às primeiras entradas, caso provido. Se for null, a listagem é ilimitada. Utilizado em navegação para frente.

after:

String

Inicia após o cursor opaco, se provido. Utilizado em navegação para frente.

last:

Int

Limita a lista às últimas entradas, caso provido. Se for null, a listagem é ilimitada. Utilizado em navegação para trás.

before:

String

Inicia antes do cursor opaco, se provido. Utilizado em navegação para trás.

filter:

MerchantFilterInput

Aplica filtro, se provido.

)

:

PSPMerchantAssociationsConnection

Query (consulta) comerciantes Merchant associados ao PSP e dados da associação (informações bancárias e afins).



Retorno da mutação associatePSPMerchant().

Compatível com Relay.

Campos:

clientMutationId

:

String

legalId

:

String

Em caso de sucesso, retorna o documento legal do comerciante associado.



Retorno da mutação dissociatePSPMerchant().

Compatível com Relay.

Campos:

clientMutationId

:

String

legalId

:

String

Em caso de sucesso, retorna o documento legal do comerciante desassociado.





Estado da Transação feita por Comerciante via Facilitador


Valores possíveis:


PHYSICAL

Física


JURIDICAL

Jurídica