APIs Recorrência: Transacional

📘
Definições de recorrência
Certifique-se de verificar a página Recorrência com ControlPay sobre as definições de recorrência no ControlPay antes de começar a interagir com as APIs de recorrência.

Recorrência

Abaixo se encontram as APIs para o cadastro e manutenção de recorrências.

POST Cadastrar recorrência

📘
{{Url}}/PagamentoRecorrente/Insert?key={{Key}}
Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.

Para o cadastro de recorrência os seguintes campos devem ser enviados:

Referência: referência do registro de recorrência no sistema integrado. Sugerimos enviar um identificador único a cada registro de recorrência;

Descrição: Breve descrição sobre a recorrência;
Data Início: Data de início da recorrência. O ControlPay utilizará o mesmo dia do mês para as transações dos meses seguintes;
Quantidade: Meses que a recorrência se repetirá;
Valor: Valor de cada transação;
Cliente Id: Identificação do cliente pré-registrado.

No retorno desta chamada virá a URL do formulário do cartão de crédito a ser tokenizado.

HEADERS
Content-Type	application/json
User-Agent	NomeDaAutomacao/1.0

PARAMS
key	{{Key}}

{
    "referencia":"{{referenciaRecorrencia}}",
    "descricao":"{{descricaoRecorrencia}}",
    "dataInicio":"{{dd/mm/aaaa hh:mm}}",
    "quantidade":"4",
    "valor":"50,00",
    "clienteId":"{{ClienteId}}"
}

Exemplo: Cadastrar recorrência

curl --location --request POST 'sandbox.controlpay.com.br/webapi/PagamentoRecorrente/Insert?key={{Key}}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \
--data-raw '{
    "referencia":"{{referenciaRecorrencia}}",
    "descricao":"{{descricaoRecorrencia}}",
    "dataInicio":"{{dd/mm/aaaa hh:mm}}",
    "quantidade":"4",
    "valor":"50,00",
    "clienteId":"{{ClienteId}}"
}'

{
  "data": "17/05/2017 10:28:31.9039",
  "pagamentoRecorrente": {
    "id": 46,
    "referencia": "ref",
    "descricao": "desc",
    "dataInsercao": "17/05/2017 10:28",
    "dataInicio": "01/06/2017",
    "quantidade": 4,
    "valor": 50,
    "valorFormat": "50,00",
    "cartaoPan": null,
    "cartaoToken": null,
    "gate2allToken": "{{Token}}",
    "urlCapturarDadosCartao": "{{urlCaptura}}",
    "cliente": {
      "id": 453,
      "cpfCnpj": "54473525848",
      "nomeRazaoSocial": "Nome",
      "email": "[email protected]",
      "referencia": "Cliente010",
      "pessoa": {
        "id": 7499,
        "nomeRazaoSocial": "Teste multi loja",
        "sobrenomeNomeFantasia": "Teste multi loja"
      }
    }
  }
}

POST Trocar cartão de crédito da recorrência

📘
{{Url}}/PagamentoRecorrente/TrocaDadosCartao?key={{Key}}&pagamentoRecorrenteId={{PagamentoRecorrenteId}}&clienteCartaoId={{ClienteCartaoId}}
Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.
PagamentoRecorrenteId: ID do pagamento recorrente.
ClienteCartaoId: ID do cartão do cliente caso já esteja cadastrado na plataforma.
Opcional: parâmetro "clienteCartaoId" é opcional nas chamadas via site.

API utilizada para trocar o cartão de crédito da recorrência. Um cartão pode ser cancelado, expirado ou não mais apto a realizar transações por algum motivo, portanto, pode-se utilizar esta API para troca do cartão.

HEADERS
Content-Type	application/json
User-Agent	NomeDaAutomacao/1.0

PARAMS
key	{{Key}}
pagamentoRecorrenteId	{{PagamentoRecorrenteId}}

Exemplo: Trocar cartão de crédito recorrência

curl --location --request POST 'sandbox.controlpay.com.br/webapi/PagamentoRecorrente/TrocaDadosCartao?key={{Key}}&pagamentoRecorrenteId={{PagamentoRecorrenteId}}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \
--data-raw ''

POST Excluir recorrência

📘
{{Url}}/PagamentoRecorrente/Excluir?key={{Key}}&pagamentoRecorrenteId={{PagamentoRecorrenteId}}
Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.
PagamentoRecorrenteId: ID do pagamento recorrente.

API utilizada para excluir uma recorrência. Basta identificar pelo id.

HEADERS
Content-Type	application/json
User-Agent	NomeDaAutomacao/1.0

PARAMS
key	{{Key}}
pagamentoRecorrenteId	{{PagamentoRecorrenteId}}

Exemplo: Excluir recorrência

curl --location --request POST 'sandbox.controlpay.com.br/webapi/PagamentoRecorrente/Excluir?key={{Key}}&pagamentoRecorrenteId={{PagamentoRecorrenteId}}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \
--data-raw ''

{
  "data": "17/05/2017 10:36:47.6375",
  "pagamentoRecorrente": {
    "id": 44,
    "referencia": "ref",
    "descricao": "desc",
    "dataInsercao": "17/05/2017 10:24",
    "dataInicio": "01/06/2017",
    "quantidade": 4,
    "valor": 50,
    "valorFormat": "50,00",
    "cartaoPan": null,
    "cartaoToken": null,
    "gate2allToken": "{{Token}}",
    "urlCapturarDadosCartao": "{{urlCaptura}}",
    "cliente": {
      "id": 2,
      "cpfCnpj": "085.106.388-88",
      "nomeRazaoSocial": "Marcio",
      "email": "[email protected]",
      "referencia": "1234",
      "pessoa": {
        "id": 12,
        "nomeRazaoSocial": "Alexandre",
        "sobrenomeNomeFantasia": "Luz"
      }
    }
  }
}

{
  "message": "Exclusão bloqueada, pagamento recorrente [Ref01Cliente01r] com parcelas geradas"
}

POST Consultar Lançamentos

📘
{{Url}}/PagamentoRecorrenteLancamento/GetByFiltros?key={{Key}}
Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.

API utilizada para consultar os lançamentos (transações). Basta enviar algum parâmetro, desde que ao menos um seja enviado.

Lista de Parâmetros para consulta:

Campo	Descrição	Mandatório	Tipo	Observação
pessoaId	Id único do cliente no ControlPay.	Não	Inteiro	Obrigatório caso nenhum outro elemento seja informado. Retorna todas as recorrências cadastradas para o cliente consultado.
clienteId	Referência do cliente (referência externa, registrada no instante do cadastro do cliente).	Não	Texto	Obrigatório caso nenhum outro elemento seja informado. Retorna todas as recorrências cadastradas para o cliente consultado.
pagamentoRecorren teId	Id do pagamento recorrente.	Não	Inteiro	Retorna um ciclo de um pagamento recorrente. Uma listagem de pagamentos efetuados ou agendados será retornada.
pagamentoRecorren teLancamentoId	Lançamento de uma operação específica de um pagamento recorrente	Não	Inteiro	Retorna uma transação específica de uma operação dentro de uma recorrência.
dataAgendamento	Data de resgistro de agendamento de recorrências	Não	Data (mm/dd/aaaa hh:mm)	Retorna todos agendamentos cadastrados na data solicitada.
dataTransacao	Data de registro das transações	Não	Data (mm/dd/aaaa)	Retorna todos os lançamento de transações na data solicitada
dataInicio	Data início de um período a ser consultado	Não	Data (mm/dd/aaaa hh:mm)	Retorna as recorrências a partir da data solicitada
dataFim	Data fim de um período a ser consultado	Não	Data (mm/dd/aaaa hh:mm)	Data (mm/dd/aaaa hh:mm)

HEADERS
Content-Type	application/json
User-Agent	NomeDaAutomacao/1.0

PARAMS
key	{{Key}}

{
    "pessoaId":"{{PessoaId}}"
}

Exemplo: Consultar lançamentos

curl --location --request POST 'sandbox.controlpay.com.br/webapi/PagamentoRecorrenteLancamento/GetByFiltros?key={{Key}}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \
--data-raw '{
    "pessoaId":"{{PessoaId}}"
}'

POST Excluir Lançamento

📘
{{Url}}/PagamentoRecorrenteLancamento/Cancelar?key={{Key}}
Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.

API para deletar parcelas de uma recorrência específica.

HEADERS
Content-type	application/json
User-Agent	NomeDaAutomacao/1.0

PARAMS
key	{{Key}}

{
  pagamentoRecorrenteLancamentoId: "{{ID do lançamento do pagamento recorrente}}",
	senhaTecnica: "{{Senha técnica da Pessoa}}"
}

Como visto acima, esta API necessita do ID do lançamento. Isto pode ser adquirido pesquisando através da API PagamentoRecorrente/GetByFiltros (mostrada mais a frente na documentação).

POST Consultar Recorrências

📘
{{Url}}/PagamentoRecorrente/GetByFiltros?key={{Key}}
Variáveis:
Url: endereço do ambiente atual.
Key: chave de acesso.

API para consultar as recorrências.

Lista de parâmetros da consulta:

Campo	Descrição	Mandatório	Tipo	Observação
clienteId	Id único do cliente no ControlPay	Não	Inteiro	Obrigatório caso nenhum outro elemento seja informado. Retorna todas as recorrências cadastradas para o cliente consultado.
referencia	Referência	Não	Campo do tipo texto	Referência da recorrência que está cadastrada, nesse caso, é recomendado colocar o campo ID da recorrência que você possui no seu sistema para efeito de referência
descricao	Descrição mais detalhada sobre a recorrência	Não	Campo do tipo texto	Descrição mais detalhada do processo que foi envolvido no momento que gerou a transação concorrente. Sugerimos que o vendedor insira essa descrição para referência própria.
valor	Valor da transação recorrente	Não	Campo do tipo numérico	Valor dos lançamentos da recorrência
quantidadeParcelas	Quantidade de vezes que será cobrada a recorrência	Não	Campo do tipo inteiro e numérico	Quantidade de parcelas que será cobrada do cliente mensalmente
dataInsercao	Data que foi inserida a transação recorrente	Não	Campo do tipo data ou numérico com formato de data	Data inserida no ato do cadastro
dataInicial	Data início de um período a ser consultado	Não	Data (mm/dd/aaaa hh:mm)	Retorna as recorrências a partir da data solicitada
dataFinal	Data final de um período a ser consultado	Não	Data (mm/dd/aaaa hh:mm)	Retorna as recorrências até a data solicitada
pagamentoRecorrenteId	ID do pagamento recorrente pesquisado	Não	Inteiro	Retorna a recorrência com o ID desejado

HEADERS
Content-Type	application/json
User-Agent	NomeDaAutomacao/1.0

PARAMS
key	{{Key}}

{
  //pagamentoRecorrenteId: 123,
  //"pessoaId": "2",
  //"clienteId": "2",
  //"referencia": "REF001",
  //"descricao": "teste",
  //"valor": "50,00",
  //"quantidadeParcelas": "3",
  //"dataInsercao": "15/08/2016 00:00",
  //"dataInicio": "16/08/2016",
  "dataInicial": "15/08/2016 00:00",
  "dataFinal": "15/08/2016 23:59"
}

Exemplo: Consultar recorrências

curl --location --request POST 'sandbox.controlpay.com.br/webapi/PagamentoRecorrente/GetByFiltros?key={{Key}}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \
--data-raw '{
		//pagamentoRecorrenteId: 123,
    //"pessoaId": "2",
    //"clienteId": "2",
    //"referencia": "REF001",
    //"descricao": "teste",
    //"valor": "50,00",
    //"quantidadeParcelas": "3",
    //"dataInsercao": "15/08/2016 00:00",
    //"dataInicio": "16/08/2016",
    "dataInicial": "15/08/2016 00:00",
    "dataFinal": "15/08/2016 23:59"
}'

APIs Recorrência: Transacional

📘
Definições de recorrência

Recorrência

POST Cadastrar recorrência

📘
{{Url}}/PagamentoRecorrente/Insert?key={{Key}}

POST Trocar cartão de crédito da recorrência

📘
{{Url}}/PagamentoRecorrente/TrocaDadosCartao?key={{Key}}&pagamentoRecorrenteId={{PagamentoRecorrenteId}}&clienteCartaoId={{ClienteCartaoId}}

POST Excluir recorrência

📘
{{Url}}/PagamentoRecorrente/Excluir?key={{Key}}&pagamentoRecorrenteId={{PagamentoRecorrenteId}}

POST Consultar Lançamentos

📘
{{Url}}/PagamentoRecorrenteLancamento/GetByFiltros?key={{Key}}

POST Excluir Lançamento

📘
{{Url}}/PagamentoRecorrenteLancamento/Cancelar?key={{Key}}

POST Consultar Recorrências

📘
{{Url}}/PagamentoRecorrente/GetByFiltros?key={{Key}}

📘Definições de recorrência

Recorrência

POST Cadastrar recorrência

📘{{Url}}/PagamentoRecorrente/Insert?key={{Key}}

POST Trocar cartão de crédito da recorrência

📘{{Url}}/PagamentoRecorrente/TrocaDadosCartao?key={{Key}}&pagamentoRecorrenteId={{PagamentoRecorrenteId}}&clienteCartaoId={{ClienteCartaoId}}

POST Excluir recorrência

📘{{Url}}/PagamentoRecorrente/Excluir?key={{Key}}&pagamentoRecorrenteId={{PagamentoRecorrenteId}}

POST Consultar Lançamentos

📘{{Url}}/PagamentoRecorrenteLancamento/GetByFiltros?key={{Key}}

POST Excluir Lançamento

📘{{Url}}/PagamentoRecorrenteLancamento/Cancelar?key={{Key}}

POST Consultar Recorrências

📘{{Url}}/PagamentoRecorrente/GetByFiltros?key={{Key}}

📘
Definições de recorrência

📘
{{Url}}/PagamentoRecorrente/Insert?key={{Key}}

📘
{{Url}}/PagamentoRecorrente/TrocaDadosCartao?key={{Key}}&pagamentoRecorrenteId={{PagamentoRecorrenteId}}&clienteCartaoId={{ClienteCartaoId}}

📘
{{Url}}/PagamentoRecorrente/Excluir?key={{Key}}&pagamentoRecorrenteId={{PagamentoRecorrenteId}}

📘
{{Url}}/PagamentoRecorrenteLancamento/GetByFiltros?key={{Key}}

📘
{{Url}}/PagamentoRecorrenteLancamento/Cancelar?key={{Key}}

📘
{{Url}}/PagamentoRecorrente/GetByFiltros?key={{Key}}