Reembolsar um pagamento

POSThttps://api.sandbox.cefispay.com.br/api/v1/payment/reversal

RECIPES

Estornar um pagamentoAbrir recipe

Solicita o reembolso (estorno) integral de um pagamento já pago. O valor é devolvido ao cliente pelo mesmo meio em que ele pagou.

Um pagamento só pode ser reembolsado quando:

o status é paid;
o method é credit ou pix (boleto e baixa manual não podem ser reembolsados);
o prazo não expirou: até 350 dias após o pagamento para credit e até 90 dias para pix;
não existe outro reembolso deste pagamento em andamento;
a sua conta tem saldo suficiente para cobrir o valor do pagamento que já foi liberado.

O campo can_refund do pagamento indica se ele atende a essas condições, com exceção do saldo e de um reembolso em andamento. Consulte-o antes de chamar este endpoint.

Resultado: uma resposta 200 quer dizer que o reembolso foi solicitado à adquirente, não que ele foi concluído. Confira o status do pagamento na resposta:

reversed: a adquirente concluiu o reembolso na hora.
paid: o reembolso ficou em processamento ou foi recusado pela adquirente. Para saber qual dos dois, consulte o pagamento no endpoint de obter detalhes do pagamento com with[]=refunds e veja o status do reembolso mais recente em refunds.

Reembolsos em processamento são consultados na adquirente a cada 5 minutos. Quando um deles é concluído, o status do pagamento passa a ser reversed e o evento de pagamento atualizado é disparado. Um reembolso com status failed não é tentado de novo; você pode solicitar um novo reembolso por este endpoint.

Atenção: quando o pagamento não pode ser reembolsado, a API responde com o status HTTP 500 e o código UNEXPECTED_ERROR, sem detalhar o motivo em produção. Verifique as condições acima antes de tentar novamente.

Parâmetros do body

obrigatórioapplication/json

Descreve os dados a serem incluídos no corpo da requisição.

paymentobjectobrigatório
payment object
- idintegerobrigatório
  O ID do pagamento a ser reembolsado.

Respostas

200Reembolso solicitado com sucesso

Corpo da resposta

application/json

responseobject
response object
- dataobject
  data object
  - statusstring
    
    unpaid: Em aberto, aguardando pagamento. - paid: Pago. - unauthorized: Recusado. A tentativa de cobrança no cartão não foi autorizada; o pagamento continua em aberto e pode ser pago novamente. - canceled: Cancelado. - reversed: Estornado.
    
    Valores permitidos:unpaidpaidunauthorizedcanceledreversed
- paymentobjectPaymentUpdateResponse
  payment object
  Ver schema PaymentUpdateResponse

Exemplo

{
  "response": {
    "data": {
      "status": "unpaid"
    },
    "payment": {
      "id": "string",
      "uuid": "string",
      "customer_id": "string",
      "customer": {},
      "subscription_id": "string",
      "subscription": {},
      "payment_link": {},
      "items": [
        "string"
      ],
      "allowed_methods": [
        "credit"
      ],
      "method": "credit",
      "card_id": "string",
      "card": {},
      "digitable_line": "string",
      "pix_payload": "string",
      "custom_data": {},
      "value": 0,
      "fine": 0,
      "interest": 0,
      "current_value": 0,
      "current_fine": 0,
      "current_interest": 0,
      "installments": 0,
      "status": "unpaid",
      "retries_number": 0,
      "was_last_retry": true,
      "can_refund": true,
      "refunds": [
        {
          "id": 0,
          "method": "string",
          "value": 0,
          "status": "new",
          "created_at": "2024-01-01T00:00:00Z",
          "updated_at": "2024-01-01T00:00:00Z"
        }
      ],
      "receipts": [
        "string"
      ],
      "receipt_status": 0,
      "due_date": "2024-01-01",
      "ref_date": "2024-01-01",
      "paid_at": "2024-01-01T00:00:00Z",
      "company": {},
      "charge_enabled": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "url": "string",
      "receipt_url": "string"
    }
  }
}

401Não autenticado

Corpo da resposta

application/json

codestring
O código do erro. Ex.: VALIDATION_ERROR, FORBIDDEN_ERROR, UNEXPECTED_ERROR.
messagestring
A mensagem do erro.
errorsobject
Os erros de cada campo, quando o code é VALIDATION_ERROR.
timestampstringdate-time
A data e hora do erro, em UTC.
request_idstring
Um identificador único gerado para esta resposta de erro.
documentation_urlstring
O endereço desta documentação.
suggestionstring
Uma sugestão de como resolver o erro.

Exemplo

{
  "code": "AUTHENTICATION_ERROR",
  "message": "Não autenticado.",
  "timestamp": "2026-10-22T12:03:44+00:00",
  "request_id": "f2a7e962-6083-4525-816e-f14d4a602e0a",
  "documentation_url": "https://docs.ninepay.com.br"
}

403O pagamento não pertence à sua conta

Corpo da resposta

application/json

codestring
O código do erro. Ex.: VALIDATION_ERROR, FORBIDDEN_ERROR, UNEXPECTED_ERROR.
messagestring
A mensagem do erro.
errorsobject
Os erros de cada campo, quando o code é VALIDATION_ERROR.
timestampstringdate-time
A data e hora do erro, em UTC.
request_idstring
Um identificador único gerado para esta resposta de erro.
documentation_urlstring
O endereço desta documentação.
suggestionstring
Uma sugestão de como resolver o erro.

Exemplo

{
  "code": "FORBIDDEN_ERROR",
  "message": "You do not have permission to perform this action.",
  "timestamp": "2026-09-28T13:00:00+00:00",
  "request_id": "9f3c2a1e-7b4d-4c1a-9e2f-0a1b2c3d4e5f",
  "documentation_url": "https://docs.ninepay.com.br"
}

422Unprocessable Entity

O payment.id não foi enviado, não é um número inteiro ou não corresponde a um pagamento existente

Corpo da resposta

application/json

codestring
O código do erro. Ex.: VALIDATION_ERROR, FORBIDDEN_ERROR, UNEXPECTED_ERROR.
messagestring
A mensagem do erro.
errorsobject
Os erros de cada campo, quando o code é VALIDATION_ERROR.
timestampstringdate-time
A data e hora do erro, em UTC.
request_idstring
Um identificador único gerado para esta resposta de erro.
documentation_urlstring
O endereço desta documentação.
suggestionstring
Uma sugestão de como resolver o erro.

Exemplo

{
  "code": "VALIDATION_ERROR",
  "message": "The given data was invalid.",
  "errors": {
    "payment.id": [
      "Payment not found."
    ]
  },
  "timestamp": "2026-09-28T13:00:00+00:00",
  "request_id": "9f3c2a1e-7b4d-4c1a-9e2f-0a1b2c3d4e5f",
  "documentation_url": "https://docs.ninepay.com.br",
  "suggestion": "Fix the fields and try again."
}

500O pagamento não pode ser reembolsado ou houve um erro inesperado

Corpo da resposta

application/json

codestring
O código do erro. Ex.: VALIDATION_ERROR, FORBIDDEN_ERROR, UNEXPECTED_ERROR.
messagestring
A mensagem do erro.
errorsobject
Os erros de cada campo, quando o code é VALIDATION_ERROR.
timestampstringdate-time
A data e hora do erro, em UTC.
request_idstring
Um identificador único gerado para esta resposta de erro.
documentation_urlstring
O endereço desta documentação.
suggestionstring
Uma sugestão de como resolver o erro.

Exemplo

{
  "code": "UNEXPECTED_ERROR",
  "message": "There was an unexpected error.",
  "timestamp": "2026-09-28T13:00:00+00:00",
  "request_id": "9f3c2a1e-7b4d-4c1a-9e2f-0a1b2c3d4e5f",
  "documentation_url": "https://docs.ninepay.com.br",
  "suggestion": "Check all request parameters. If the error persists, contact our team in ti@ninepay.com.br."
}

RECIPES

Parâmetros do body

Respostas

Credenciais

Resposta