Referência da API
Estornar pagamento
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 |
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