Referência da API
Solicitar estorno
Solicita o estorno de um pagamento aprovado. Use os dados de autorização recebidos no webhook pagamento.aprovado.
POST
/v1/refundsResposta inicial
202 AcceptedResposta inicialJSON
1{2 "referencia": "0f8fad5b-d9cb-469f-a165-70867728950e",3 "status": "processando",4 "mensagem": "Estorno enviado ao SmartPOS.",5 "smartposId": "POS001",6 "targets": [7 {8 "smartposId": "POS001",9 "status": "enviado"10 }11 ]12}Campos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| referencia | string | Mesma referência enviada na requisição. Use para consultar, conciliar e deduplicar a operação.obrigatório |
| status | string | Estado inicial da operação. Não representa aprovação, recusa ou conclusão final.obrigatório |
| mensagem | string | Mensagem resumida sobre o aceite, envio ou fila inicial da operação.obrigatório |
| smartposId | string | SmartPOS direcionado pela operação, quando a rota retorna esse campo no nível principal. |
| targets | array | SmartPOS que receberam ou deveriam receber a solicitação inicial.obrigatório |
| targets[].smartposId | string | Identificador público do SmartPOS de destino.obrigatório |
| targets[].status | string | Resultado inicial de publicação para aquele SmartPOS.obrigatório |
Responda antes de processar
Salve o evento e retorne HTTP 2xx rapidamente dentro de 1 ou 2 segundos no máximo. A conclusão da venda ou pedido, conciliação ou emissão fiscal devem rodar depois, fora do request do webhook.
Evento recebido
Use o campo tipo para decidir o estado da operação no seu sistema.
Webhookestorno.aprovado
1{2 "id": "evt_01JZ9W2TG2J7QKQ64DXA8YE5S9",3 "tipo": "estorno.aprovado",4 "criadoEm": "2026-05-28T14:40:00Z",5 "dados": {6 "referencia": "0f8fad5b-d9cb-469f-a165-70867728950e",7 "documentoCliente": "12345678000195",8 "valorCentavos": 14990,9 "valorFormatado": "149.90",10 "smartposId": "POS001",11 "status": "estornado",12 "pagamentoOriginal": {13 "codigoAutorizacao": "J214KAN5OTM4I58FN5J59EK3NGIAMKSI",14 "numeroTransacao": "533450",15 "dadosFinalizacao": "533450|J214KAN5OTM4I58FN5J59EK3NGIAMKSI|J214KAN5OTM4I58FN5J59EK3NGIAMKSI",16 "tipoPagamento": "credito"17 },18 "resultadoSmartPOS": {19 "executado": true,20 "codigoStatus": "0",21 "mensagemOperador": "Estorno concluído"22 }23 }24}Eventos
| Campo | Tipo | Descrição |
|---|---|---|
| estorno.aprovado | event | Estorno aprovado. |
| estorno.falhou | event | Estorno não concluído por falha operacional. |
Decisão operacional
| Campo | Tipo | Descrição |
|---|---|---|
| estorno.aprovado | decisão | Marque o estorno como concluído e vincule ao pagamento original. |
| estorno.falhou | decisão | Mantenha o pagamento original e registre a falha para conferência operacional. |
Propriedades do evento
| Campo | Tipo | Descrição |
|---|---|---|
| id | string | Identificador único do evento. Use para idempotência, inclusive em reenvio manual.obrigatório |
| tipo | string | Evento interpretado pelo ConnectTEF. Este é o campo principal para decidir o que fazer no sistema comercial.obrigatório |
| criadoEm | string ISO 8601 | Data e hora em que o ConnectTEF gerou o evento.obrigatório |
| dados.referencia | string | Referência enviada no request de estorno.obrigatório |
| dados.documentoCliente | string | CPF ou CNPJ do cliente ConnectTEF vinculado ao estorno.obrigatório |
| dados.valorCentavos | integer | Valor estornado em centavos. |
| dados.valorFormatado | string | Valor estornado em formato decimal com ponto. |
| dados.smartposId | string | Identificador público do SmartPOS que executou o estorno. |
| dados.status | string | Status normalizado complementar ao tipo.obrigatório |
| dados.pagamentoOriginal | object | Dados do pagamento original retornados quando o estorno nasceu pelo contrato público. |
| dados.resultadoSmartPOS.executado | boolean | Indica se o SmartPOS executou a operação antes de retornar o resultado. |
| dados.resultadoSmartPOS.codigoStatus | string | Código bruto do SmartPOS, mantido para diagnóstico e conferência. |
| dados.resultadoSmartPOS.mensagemOperador | string | Mensagem operacional retornada pelo SmartPOS para exibição ou log. |
erro.jsonJSON
1{2 "erro": {3 "codigo": "API_KEY_INVALIDA",4 "mensagem": "API key invalida ou inativa.",5 "acao": "Confira se a chave foi copiada do portal do parceiro e se está ativa."6 }7}| HTTP | Código | Quando acontece | Como corrigir |
|---|---|---|---|
| 400 | CAMPO_OBRIGATORIO | Algum campo obrigatório do estorno está ausente ou vazio. | Revise referencia, documentoCliente, smartposId, valorCentavos e pagamentoOriginal.*. |
| 400 | CAMPO_INVALIDO | Algum campo foi enviado com tipo, tamanho ou formato inválido. | Revise o campo indicado em erro.campo antes de reenviar. |
| 400 | DOCUMENTO_CLIENTE_INVALIDO | documentoCliente não é CPF/CNPJ válido ou o cliente não foi encontrado. | Confira o cadastro do cliente e envie o documento preferencialmente somente com números. |
| 400 | VALOR_INVALIDO | valorCentavos não é inteiro positivo dentro do limite aceito. | Envie valorCentavos em centavos, sem casas decimais. |
| 401 | API_KEY_INVALIDA | A chave não existe, foi rotacionada ou está inativa. | Use a chave ativa gerada no portal do parceiro. |
| 403 | CLIENTE_NAO_AUTORIZADO | A API key não autoriza operação para o cliente informado. | Confira se o cliente pertence ao parceiro da chave utilizada. |
| 404 | SMARTPOS_NAO_ENCONTRADO | smartposId não pertence ao cliente informado ou não está vinculado. | Confirme o SmartPOS usado no pagamento original. |
| 409 | REFERENCIA_DUPLICADA | A referência do estorno já foi usada em uma tentativa operacional anterior. | Se é uma nova tentativa de estorno, gere uma nova referência. |
| 500 | ERRO_INTERNO | A API encontrou uma falha inesperada ao processar a solicitação. | Registre status, referência e corpo da resposta antes de acionar o suporte. |
Atenção
O estorno depende dos dados retornados no pagamento aprovado. Guarde esses campos no seu sistema antes de precisar estornar.
Seção ativa: Requisição