Callback

Esta funcionalidade, também conhecido como Webhook, permite que o sistema ou aplicação que gerou uma transação no ControlPay receba uma notificação assim que ela for finalizada, independentemente do resultado: autorizada, negada ou cancelada, o sistema receberá uma notificação de callback.

As informações presentes no callback permitem identificar a transação. Após acatar notificação, o sistema deverá consultar a transação no ControlPay através das APIs listadas na seção "Transacional".

Resposta ao callback pela URL cadastrada

Quando o callback for realizado, o ControlPay analisa o código de status enviado pelo sistema cadastrado. Caso o sistema retorne um status code diferente do range de 200 (ex: 200, 201, etc.), o ControlPay irá realizar nova tentativa do callback após 2 minutos. Se na próxima tentativa também retornar status code diferente do range 200, a próxima retentativa ocorrerá após 4 minutos, e assim consecutivamente depois de 8, 16 e 32 minutos.

Obs.: O sistema deve retornar status code com range 200 apenas para callback recebido com sucesso. Se o status code com range de 200 for retornado, não será mais enviado callback.

Tipos de callback

Gerenciamento de URL de callback

As Automações Comerciais podem gerenciar as URLs de callback, através dos endpoints abaixo.

POST Callback/Insert

Esta API é usada para a criação de callbacks. A URL de callback será criada para o usuário dono da chave de integração utilizada na chamada da API. Ou seja: esta será a URL de callback para todos os terminais daquele CPF/CNPJ.

{ 
  “callbackTipo”: 1,
  “urlCallback”: “https://suaUrlDeCallback.com.br/”
}

• callbackTipo: [int] tipo do callback desejado (venda, consulta, impressão);
• urlCallback: [string] URL de callback a ser cadastrada. Este valor pode ter até 500 caracteres;

Exemplo: Callback/Insert

{ 
  “callbackTipo”: 1,
  “urlCallback”: “https://suaUrlDeCallback.com.br/”
}

{
    "data": "27/02/2026 11:50:15.7139",
    "callback": {
        "callbackTipo": {
            "id": 1,
            "nome": "UrlRetorno"
        },
        "urlCallback": "https://suaUrlDeCallback.com.br/",
        "pessoa": {
            "id": 1234,
            "nome": "NomeDaPessoa",
            "sobrenomeNomeFantasia": "Loja da Esquina"
        }
    }
}

GET Callback/GetRegistered

Esta API é usada para recuperar a URL de callback cadastrada anteriormente.

Exemplo: Callback/GetRegistered

{
    "data": "27/02/2026 11:59:20.5408",
    "callback": {
        "callbackTipo": {
            "id": 1,
            "nome": "UrlRetorno"
        },
        "urlCallback": "https://suaUrlDeCallback.com.br/",
        "pessoa": {
            "id": 1234,
            "nome": "NomeDaPessoa",
            "sobrenomeNomeFantasia": "Loja da Esquina"
        }
    }
}

POST Callback/Update

Esta API é usada para modificar uma URL previamente cadastrada.

{ 
  “callbackTipo”: 1,
  “urlCallback”: “https://suaUrlDeCallback.com.br/”
}

• callbackTipo: [int] tipo do callback desejado (venda, consulta, impressão);
• urlCallback: [string] URL de callback a ser modificada. Este valor pode ter até 500 caracteres;

Exemplo: Callback/Update

{ 
  “callbackTipo”: 1,
  “urlCallback”: “https://suaUrlDeCallbackNova.com.br/”
}

{
    "data": "27/02/2026 12:00:17.1285",
    "callback": {
        "callbackTipo": {
            "id": 1,
            "nome": "UrlRetorno"
        },
        "urlCallback": "https://suaUrlDeCallbackNova.com.br/",
        "pessoa": {
            "id": 1234,
            "nome": "NomeDaPessoa",
            "sobrenomeNomeFantasia": "Loja da Esquina"
        }
    }
}

DELETE Callback/Delete

Esta API é usada para deletar callbacks previamente cadastradas.

{ 
  “callbackTipo”: 1
}

• callbackTipo: [int] tipo do callback desejado (venda, consulta, impressão);

Exemplo: Callback/Delete

{ 
  “callbackTipo”: 1
}

{
    "data": "27/02/2026 12:00:37.4872",
    "callback": {
        "callbackTipo": {
            "id": 1,
            "nome": "UrlRetorno"
        },
        "urlCallback": "https://www.postb.in/1770215647337-6262078641446",
        "pessoa": {
            "id": 1234,
            "nome": "NomeDaPessoa",
            "sobrenomeNomeFantasia": "Loja da Esquina"
        }
    }
}

O ControlPay retornará as informações da chave que foi deletada, apenas para conferência.

O callback em funcionamento

Após o cadastro do callback, quando houver uma venda, ele funcionará de acordo com o comportamento abaixo, sendo enviado pelo ControlPay no endereço descrito (preenchido com as informações correspondentes).

POST Callback - Intenção de venda

Callback para a intenção de venda. Se não houve registro de pedido, o pedidoId e o pedidoReferencia estarão em branco.

Exemplo: Callback de venda

curl --location --request POST 'seusite.com.br/seuservico?cpfCnpj={{CpfCnpj}}&intencaoVendaId={{ControlPayId}}&intencaoVendaReferencia={{SeuId}}&pedidoId={{ControlPayPedidoId}}&pedidoReferencia={{SeuPedidoId}}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: NomeDaAutomacao/1.0' \
--data-raw ''

POST Callback - Intenção impressão

Os status retornáveis são:

Exemplo: Callback de impressão

curl --location --request POST 'seusite.com.br/seuservico?intencaoImpressaoId={{ControlPayId}}&intencaoImpressaoReferencia={{SeuId}}&intencaoImpressaoStatus={{Status}}'