--- agentTools: projectIndex: https://docs.ninepay.com.br/llms.txt projectSearch: https://docs.ninepay.com.br/agentSearch?query=term1%20term2 --- # Reembolsar um pagamento 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. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "NinePay API", "version": "1.0", "x-logo": { "url": "" }, "termsOfService": "https://bit.ly/cefispay-contrato", "contact": { "name": "NinePay Engineering Team", "email": "ti@ninepay.com.br" }, "description": "# Introdução\nBem vindo a referência da **API NinePay**.\nÉ através desta API que você integra o seu sistema ao nosso.\nNossa API é RESTful, e todas suas respostas são em JSON, no endpoint base:\n```\nhttps://payments.cefis.com.br/api/v1/\n```\n\n## Ambientes\nAlém do ambiente de **produção** temos disponível o ambiente **sandbox**\npara a realização de testes de integração. Toda a comunicação com o ambiente sandbox deve ser feita através da url:\n\n```\nhttps://api.sandbox.cefispay.com.br/api/v1/\n```\n\n## Autenticação\nTodas as requisições que requerem autenticação, deverão informar no header `Authorization` o token de api enviado pela nossa equipe, observando sempre o ambiente desejado e no seguinte formato:\n```\nAuthorization: Bearer \n```\n\n## Headers\nRecomendamos que os cabeçalhos da requisições sejam corretamente adicionados para trabalhar com os tipos de dados enviados e recebidos da API:\n - Todas as requisições devem contem o header `Content-Type: application/json`, a menos que o endpoint específico defina diferente\n - Todas as requisições devem contem o header `Accept: application/json`, a menos que o endpoint específico defina diferente\n\n## Respostas\n- Os recursos vêm dentro de `data`: `GET /customers/{id}` responde `{ \"data\": { ... } }`.\n- As criações respondem **201**. `POST /payments` responde `{ \"customer\", \"payment\", \"invoice_url\" }` (o `invoice_url` só no boleto) e `POST /subscriptions` responde `{ \"customer\", \"subscription\" }`.\n- Valores sempre em centavos (inteiro): R$ 50,00 é `5000`.\n\n## Erros\nTodo erro tem o mesmo formato:\n```json\n{\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Os dados informados são inválidos.\",\n \"errors\": { \"email\": [\"O campo email é obrigatório.\"] },\n \"timestamp\": \"2026-10-22T12:03:54+00:00\",\n \"request_id\": \"64d62d36-e797-45ed-a9d5-c203bde81032\",\n \"documentation_url\": \"https://docs.ninepay.com.br\",\n \"suggestion\": \"Corrija os campos e tente novamente.\"\n}\n```\n`errors` só vem na validação, com uma **lista** de mensagens por campo. `suggestion` vem quando há uma. Guarde o `request_id` para falar com o suporte.\n\n| `code` | HTTP | Quando |\n| --- | --- | --- |\n| `AUTHENTICATION_ERROR` | 401 | Token ausente ou inválido |\n| `FORBIDDEN_ERROR` | 403 | O recurso não é da sua empresa. Em várias rotas, um id que não existe também responde 403, para não revelar quais ids existem |\n| `COMPANYBLOCKED_ERROR` | 403 | A conta está suspensa |\n| `RESOURCE_NOT_FOUND_ERROR` | 404 | O recurso não existe |\n| `ROUTE_NOT_FOUND_ERROR` | 404 | A rota não existe |\n| `METHOD_NOT_ALLOWED_ERROR` | 405 | O método não vale para a rota (ex.: `PUT /customers` sem o id) |\n| `INVALID_STATE_ERROR` | 400 | O recurso não está num estado que permita a ação (ex.: cancelar um pagamento já pago) |\n| `VALIDATION_ERROR` | 422 | Dados inválidos; veja `errors` |\n| `REFUND_NOT_ALLOWED` | 422 | O pagamento não pode ser reembolsado |\n| `TOO_MANY_ATTEMPTS` | 429 | Muitas requisições; respeite o cabeçalho `Retry-After` |\n| `UNEXPECTED_ERROR` | 500 | Erro nosso; se repetir, fale com o suporte com o `request_id` |\n\n## Paginação\nAs listagens recebem `page` (a partir de 1) e `limit` (itens por página: **10** por padrão, de 1 a **100**). A resposta traz `data` (os itens), `links` e `meta` (`current_page`, `last_page`, `per_page`, `total`).\n\n## Datas\n- Datas de calendário (`due_date`, `next_payment`) vão como `AAAA-MM-DD` na requisição.\n- Nas respostas, os campos de data e hora aparecem em dois formatos: ISO 8601 em UTC (`2026-10-27T03:00:00.000000Z`, em `due_date` e `ref_date` do pagamento) e `AAAA-MM-DD HH:MM:SS` no horário de Brasília (`created_at` e `updated_at`). Leia o campo pelo formato dele.\n\n## Identificadores\nCada recurso tem um `id` numérico e um `uuid`. Use o `id` nas rotas autenticadas e o **`uuid`** em tudo que é público (o link de pagamento, o checkout e o PDF do boleto).\n\n# Hash de cartões\nO hash de um cartão é uma versão criptografada de todos os dados do cartão do cliente, essa é a maneira mais segura de enviar os dados do cartão\ndo seu cliente diretamente para a gente. Abaixo vamos detalhar como ele funciona e como obter um hash a partir dos dados inseridos pelo cliente.\nÉ importante ressaltar que esse fluxo deve ser executado no front-end, seja ele web ou mobile, e que os dados do cartão do cliente nunca devem\nser enviados para o backend, já o hash do cartão pode ser enviado para o backend sem problemas.\n\n## Gerando uma encryption key\nA encryption key consiste basicamente em uma chave pública RSA usada para encriptar os dados do cartão, essa chave só pode ser usada uma vez, então\nsempre que precisar encriptar um novo cartão você precisa gerar uma nova encryption key.\n\nPara gerar uma encryption key é necessário fazer uma requisição ``POST`` para a rota ``/encryption_keys`` da API enviando como parâmetro seu\n``merchant_id``. Ela não usa o token da API (nunca o coloque no front-end): o ``merchant_id`` identifica a sua conta, e um\n``merchant_id`` que não existe responde 401.\n\nA requisição deverá ter esse formato:\n```\ncurl -X POST https://payments.cefis.com.br/api/v1/encryption_keys -H 'Content-Type: application/json' -d '{\"merchant_id\":\"SEU_MERCHANT_ID\"}'\n```\n\nComo resposta você receberá um objeto JSON no seguinte formato:\n```\n{\n \"id\": 1111,\n \"public_key\": \"-----BEGIN PUBLIC KEY-----\\n ... \\n-----END PUBLIC KEY-----\\n\",\n \"ip_address\": \"000.000.000.000\",\n \"created_at\": \"2017-07-03\",\n}\n```\n\n## Encriptando os dados do cartão\nPara encriptar os dados do cartão primeiro você precisa formatá-los de forma correta, para isso crie uma string JSON\ncontendo todos os dados do cartão no seguinte formato:\n\n```\n{\"card_number\":\"1111111111111111\",\"card_holder_name\":\"Jose Silva\",\"card_expiration_date\":\"11/2021\",\"card_cvv\":\"111\"}\n```\n\nEm seguida faça a criptografia RSA dessa string utilizando a chave pública (public_key) gerada no passo anterior, com\npadding do tipo PKCS1.\n\nApós criptografar os dados converta a string resultante para base64 e você terá um resultado parecido com esse:\n\n```\nGprWNDlg+MKGgtr6y9wJgz7oOUxGuhhdX3EwydmoOvb+yNDWrjDKktDtWicReOrvSo0u5rsNvCqBFjyoMfaRXn4Qq3KdV8vuuFXubb4FT3OcSSVpu6ddaOjm2tf82+GKjdCy54Lgw4T0m9mWdLPveh/zkYP0+4lhHCFhBKX5EqBdR4918wP5oUV1KpzV4V94ldSA+Cy2n1NUxyUiSnv87H2m+HkdqKDIcX9X8KEtUmorC/EjTPzoeEdpRdj8t3ThcL73mirJvDcYthSdT/ADyaFQ2hMRMkKEVOQjUYMn76vzWyQkqsZ+HVQlxQMOBVHPh5yfrmi1HAVd1jLQuOK8wQ==\n```\n\nO último passo é concatenar o id da sua encryption key (recebido como resposta da requisição anterior) com a string\nem base64 que representa os dados do cartão, da seguinte forma:\n\n``encryption_key_id + \"_\" + base64_encrypted_card``\n\nO resultado será o seu card hash:\n\n```\n1111_GprWNDlg+MKGgtr6y9wJgz7oOUxGuhhdX3EwydmoOvb+yNDWrjDKktDtWicReOrvSo0u5rsNvCqBFjyoMfaRXn4Qq3KdV8vuuFXubb4FT3OcSSVpu6ddaOjm2tf82+GKjdCy54Lgw4T0m9mWdLPveh/zkYP0+4lhHCFhBKX5EqBdR4918wP5oUV1KpzV4V94ldSA+Cy2n1NUxyUiSnv87H2m+HkdqKDIcX9X8KEtUmorC/EjTPzoeEdpRdj8t3ThcL73mirJvDcYthSdT/ADyaFQ2hMRMkKEVOQjUYMn76vzWyQkqsZ+HVQlxQMOBVHPh5yfrmi1HAVd1jLQuOK8wQ==\n```\n\nPronto, agora os dados do cartão do cliente já estão em um formato seguro para serem transportados pela rede, podendo\nagora ser enviados para o seu back-end dar sequência ao fluxo. Vale lembrar que cada card hash pode ser usado apenas\numa vez e além disso tem uma validade máxima de 30 minutos após a geração da encryption key. Caso seja necessário utilizar\no cartão mais de uma vez faça uma requisição para a rota de cartões e salve esse cartão vinculado ao usuário que o detém,\nassim você receberá um ID único que poderá ser usado para realizar mais transações com o mesmo cartão.\n" }, "paths": { "/payment/reversal": { "post": { "summary": "Reembolsar um pagamento", "tags": [ "Pagamentos" ], "description": "Solicita o reembolso (estorno) integral de um pagamento já pago. O valor é devolvido ao cliente pelo mesmo meio em que ele pagou.\n\nUm pagamento só pode ser reembolsado quando:\n- o `status` é `paid`;\n- o `method` é `credit` ou `pix` (boleto e baixa manual não podem ser reembolsados);\n- o prazo não expirou: até 350 dias após o pagamento para `credit` e até 90 dias para `pix`;\n- não existe outro reembolso deste pagamento em andamento;\n- a sua conta tem saldo suficiente para cobrir o valor do pagamento que já foi liberado.\n\nO 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.\n\n**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:\n- `reversed`: a adquirente concluiu o reembolso na hora.\n- `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`.\n\nReembolsos 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.\n\n**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.\n", "requestBody": { "$ref": "#/components/requestBodies/PaymentReversalBody" }, "responses": { "200": { "description": "Reembolso solicitado com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentReversalResponse" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "description": "O pagamento não pertence à sua conta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "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" } } } }, "422": { "description": "O `payment.id` não foi enviado, não é um número inteiro ou não corresponde a um pagamento existente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "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." } } } }, "500": { "description": "O pagamento não pode ser reembolsado ou houve um erro inesperado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "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." } } } } }, "operationId": "refundPayment" } } }, "components": { "securitySchemes": { "Bearer": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Todas as requisições que requerem autenticação devem incluir no cabeçalho `Authorization` o token de API enviado pela nossa equipe. O token deve ser fornecido no seguinte formato:\n```\nAuthorization: Bearer \n```" } }, "schemas": { "ApiError": { "type": "object", "properties": { "code": { "type": "string", "description": "O código do erro. Ex.: `VALIDATION_ERROR`, `FORBIDDEN_ERROR`, `UNEXPECTED_ERROR`." }, "message": { "type": "string", "description": "A mensagem do erro." }, "errors": { "type": "object", "description": "Os erros de cada campo, quando o `code` é `VALIDATION_ERROR`.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "timestamp": { "type": "string", "format": "date-time", "description": "A data e hora do erro, em UTC." }, "request_id": { "type": "string", "description": "Um identificador único gerado para esta resposta de erro." }, "documentation_url": { "type": "string", "description": "O endereço desta documentação." }, "suggestion": { "type": "string", "description": "Uma sugestão de como resolver o erro." } } }, "PaymentReversalResponse": { "type": "object", "properties": { "response": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/PaymentStatus" } } }, "payment": { "$ref": "#/components/schemas/PaymentUpdateResponse" } } } } }, "PaymentUpdateResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "O ID do pagamento." }, "uuid": { "type": "string", "description": "O UUID do pagamento." }, "customer_id": { "type": "string", "description": "O ID do cliente do pagamento." }, "customer": { "type": "object", "description": "O cliente do pagamento." }, "subscription_id": { "type": "string", "description": "O ID da assinatura do pagamento." }, "subscription": { "type": "object", "description": "A assinatura do pagamento." }, "payment_link": { "type": "object", "description": "O link de pagamento." }, "items": { "type": "array", "description": "Os itens do pagamento." }, "allowed_methods": { "type": "array", "description": "Os métodos com que o cliente pode pagar este pagamento.", "items": { "$ref": "#/components/schemas/PaymentMethods" } }, "method": { "$ref": "#/components/schemas/PaymentResponseMethods" }, "card_id": { "type": "string", "description": "O ID do cartão do pagamento." }, "card": { "type": "object", "description": "O cartão do pagamento." }, "digitable_line": { "type": "string", "description": "A linha digitável do boleto. Só é preenchida para o método `billet`." }, "pix_payload": { "type": "string", "description": "O código Pix copia e cola do pagamento. Só é preenchido para o método `pix`." }, "custom_data": { "type": "object", "description": "Os dados personalizados do pagamento." }, "value": { "type": "number", "description": "O valor original do pagamento em centavos, sem multa e juros. Ex.: 5000 para R$50,00." }, "fine": { "type": "number", "description": "A multa do pagamento, em valor percentual. Ex.: 2 para multa de 2% sobre o valor do pagamento vencido." }, "interest": { "type": "number", "description": "O juros do pagamento, em valor percentual ao mês. Ex.: 2 para 2% ao mês." }, "current_value": { "type": "number", "description": "O valor a ser pago hoje, em centavos: `value` somado a `current_fine` e `current_interest`." }, "current_fine": { "type": "number", "description": "O valor da multa aplicada até hoje, em centavos. É 0 enquanto o pagamento não vence." }, "current_interest": { "type": "number", "description": "O valor dos juros acumulados até hoje, em centavos. É 0 enquanto o pagamento não vence." }, "installments": { "type": "number", "description": "O número de parcelas do pagamento. Só se aplica ao método `credit`." }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "retries_number": { "type": "number", "description": "O número de tentativas do pagamento." }, "was_last_retry": { "type": "boolean", "description": "Se foi a última tentativa do pagamento." }, "can_refund": { "type": "boolean", "description": "Se o pagamento pode ser reembolsado agora. Só é `true` quando o `status` é `paid` e o método é `credit` (até 350 dias após o pagamento) ou `pix` (até 90 dias após o pagamento)." }, "refunds": { "type": "array", "description": "Os reembolsos solicitados para o pagamento. Só é retornado no endpoint de obter detalhes do pagamento quando a requisição inclui `with[]=refunds`.", "items": { "$ref": "#/components/schemas/PaymentRefund" } }, "receipts": { "type": "array", "description": "Os recibos do pagamento." }, "receipt_status": { "$ref": "#/components/schemas/ReceiptStatus" }, "due_date": { "type": "string", "format": "date", "description": "A data de vencimento do pagamento." }, "ref_date": { "type": "string", "format": "date", "description": "A data de referência do pagamento." }, "paid_at": { "type": "string", "format": "date-time", "description": "A data e hora em que o pagamento foi pago. É nula enquanto o `status` não é `paid`." }, "company": { "type": "object", "description": "A empresa do pagamento." }, "charge_enabled": { "type": "boolean", "description": "A habilitação da cobrança do pagamento." }, "created_at": { "type": "string", "format": "date-time", "description": "A data e hora em que o pagamento foi criado." }, "updated_at": { "type": "string", "format": "date-time", "description": "A data e hora em que o pagamento foi atualizado." }, "url": { "type": "string", "description": "A URL do pagamento." }, "receipt_url": { "type": "string", "description": "A URL do recibo do pagamento." } } }, "ReceiptStatus": { "type": "integer", "enum": [ 0, 1, 2, 3, 4 ], "description": "- 0: Emissão de recibo não configurada. - 1: Recibo ainda não emitido. - 2: Recibo emitido. - 3: Erro na emissão do recibo. - 4: Emissão do recibo ignorada.\n" }, "PaymentRefund": { "type": "object", "properties": { "id": { "type": "integer", "description": "O ID do reembolso." }, "method": { "type": "string", "description": "O método do pagamento reembolsado: `credit` ou `pix`." }, "value": { "type": "number", "description": "O valor reembolsado, em centavos." }, "status": { "$ref": "#/components/schemas/RefundStatus" }, "created_at": { "type": "string", "format": "date-time", "description": "A data e hora em que o reembolso foi solicitado." }, "updated_at": { "type": "string", "format": "date-time", "description": "A data e hora da última atualização do reembolso." } } }, "RefundStatus": { "type": "string", "enum": [ "new", "processing", "completed", "failed" ], "description": "- new: Reembolso criado, ainda não enviado à adquirente. - processing: Reembolso em processamento na adquirente. - completed: Reembolso concluído; o valor foi devolvido ao cliente. - failed: A adquirente não conseguiu fazer o reembolso.\n" }, "PaymentStatus": { "type": "string", "enum": [ "unpaid", "paid", "unauthorized", "canceled", "reversed" ], "description": "- 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.\n" }, "PaymentResponseMethods": { "type": "string", "enum": [ "credit", "debit", "billet", "pix", "payment_initiation", "manual" ], "description": "- credit: Cartão de crédito. - debit: Cartão de débito. - billet: Boleto. - pix: Pix. - payment_initiation: Iniciação de pagamento via Open Finance. - manual: Baixa manual, registrada pelo endpoint de dar baixa em pagamento.\n" }, "PaymentMethods": { "type": "string", "enum": [ "credit", "billet", "pix" ] } }, "responses": { "401": { "description": "Não autenticado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "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" } } } } }, "requestBodies": { "PaymentReversalBody": { "required": true, "description": "Descreve os dados a serem incluídos no corpo da requisição.\n", "content": { "application/json": { "schema": { "type": "object", "required": [ "payment" ], "properties": { "payment": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "O ID do pagamento a ser reembolsado.", "example": 42 } } } } } } } } } }, "tags": [ { "name": "Pagamentos", "description": "Pagamentos" } ], "x-tagGroups": [ { "name": "API Calls", "tags": [ "Pagamentos", "Clientes", "Planos", "Assinaturas", "Consultas" ] } ], "servers": [ { "url": "https://api.sandbox.cefispay.com.br/api/v1", "description": "Servidor de Testes (sandbox)" } ], "security": [ { "Bearer": [] } ] } ```