--- agentTools: projectIndex: https://docs.ninepay.com.br/llms.txt projectSearch: https://docs.ninepay.com.br/agentSearch?query=term1%20term2 --- # Dar baixa em pagamento Marca um pagamento como pago. Utilize esta opção para registrar na NinePay um pagamento que foi feito fora do sistema, como por exemplo, um pagamento em dinheiro ou transferência bancária. Após ser marcado como pago, o cliente não receberá mais cobranças referentes a este pagamento. # 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/{id}/write-off": { "post": { "summary": "Dar baixa em pagamento", "tags": [ "Pagamentos" ], "description": "Marca um pagamento como pago. Utilize esta opção para registrar na NinePay um pagamento que foi feito fora do sistema, como por exemplo, um pagamento em dinheiro ou transferência bancária. Após ser marcado como pago, o cliente não receberá mais cobranças referentes a este pagamento.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "O id do pagamento a ser cancelado", "schema": { "type": "integer" } } ], "requestBody": { "$ref": "#/components/requestBodies/PaymentWriteOffBody" }, "responses": { "200": { "description": "Pagamento baixado com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentUpdateResponse" } } } }, "401": { "$ref": "#/components/responses/401" }, "422": { "$ref": "#/components/responses/422" }, "500": { "$ref": "#/components/responses/500" } } } } }, "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```" } }, "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" } } } }, "422": { "description": "Erro na validação dos dados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "code": "VALIDATION_ERROR", "message": "Os dados informados são inválidos.", "errors": { "email": [ "O campo email é obrigatório." ] }, "timestamp": "2026-10-22T12:03:54+00:00", "request_id": "64d62d36-e797-45ed-a9d5-c203bde81032", "documentation_url": "https://docs.ninepay.com.br", "suggestion": "Corrija os campos e tente novamente." } } } }, "500": { "description": "Erro inesperado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "code": "UNEXPECTED_ERROR", "message": "Houve um erro inesperado.", "timestamp": "2026-10-22T12:04:46+00:00", "request_id": "868443d3-38fd-4c92-8ea8-7cccbbce4308", "documentation_url": "https://docs.ninepay.com.br", "suggestion": "Verifique todos os parâmetros da requisição. Se o erro persistir, entre em contato com nossa equipe em ti@ninepay.com.br." } } } } }, "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." } } }, "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" ] } }, "requestBodies": { "PaymentWriteOffBody": { "required": false, "description": "Descreve os dados a serem incluídos no corpo da requisição.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "valueType": { "type": "string", "enum": [ "normal", "zero" ], "description": "- normal: Mantém o valor do pagamento\n- zero: Zera o valor do pagamento (não será somado aos gráficos de faturamento)\n" } } } } } } } }, "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": [] } ] } ```