> ## Documentation Index > Fetch the complete documentation index at: https://docs.besimplo.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar reembolso > Cria um reembolso para um pagamento existente. O reembolso será processado de acordo com o método de pagamento: - **Cartão de crédito**: Reembolso síncrono, status final retornado imediatamente. - **PIX**: Reembolso assíncrono, status inicial será "refunding" e atualizado via webhook quando concluído. ## OpenAPI ````yaml /api-reference/openapi.yml post /api/v1/refunds openapi: 3.1.0 info: title: API - Simplo version: 1.0.0 description: API para cobrança e assinaturas para contas Simplo contact: name: Simplo url: https://besimplo.com email: team@besimplo.com servers: - url: https://besimplo.com description: Produção security: - apiKeyAuth: [] tags: - name: Clientes description: Clientes são as pessoas que pagarão pelos produtos da sua conta - name: Produtos description: Produtos representam os bens ou serviços que você vende - name: Preços description: Preços definem quanto cobrar e a frequência de cobrança de um Produto - name: Assinaturas description: Assinaturas conectam clientes aos seus planos para cobrança recorrente - name: Checkout description: >- Sessões de checkout permitem que clientes completem pagamentos e assinaturas através de uma interface web - name: Faturas description: Faturas representam cobranças geradas para clientes - name: Reembolsos description: Reembolsos permitem devolver pagamentos já realizados aos clientes - name: Webhooks description: > Eventos enviados via HTTP POST para a URL configurada na sua conta. Responda com status 2xx rapidamente. Processe o evento de forma assincrona. Use o campo `event.id` para garantir idempotencia. paths: /api/v1/refunds: post: tags: - Reembolsos summary: Criar reembolso description: > Cria um reembolso para um pagamento existente. O reembolso será processado de acordo com o método de pagamento: - **Cartão de crédito**: Reembolso síncrono, status final retornado imediatamente. - **PIX**: Reembolso assíncrono, status inicial será "refunding" e atualizado via webhook quando concluído. operationId: createRefund requestBody: description: Dados do reembolso a ser criado required: true content: application/json: schema: type: object unevaluatedProperties: false required: - refund properties: refund: type: object required: - payment_intent properties: payment_intent: type: string pattern: ^pi_[0-9a-z]{26}$ description: >- ID do payment_intent a ser reembolsado, no formato TypeID com prefixo `pi_`. example: pi_01h455vb4pex5vsknk084sn02q amount: type: integer description: > Valor do reembolso parcial em centavos (R$). Se não informado, será realizado reembolso total. **Nota:** Reembolso parcial será suportado em versão futura. example: 5000 reason: type: string description: | Motivo do reembolso. - `duplicate`: Cobrança duplicada. - `fraudulent`: Cobrança fraudulenta. - `requested_by_customer`: Solicitado pelo cliente. enum: - duplicate - fraudulent - requested_by_customer example: requested_by_customer responses: '200': description: Reembolso processado com sucesso (cartão de crédito) content: application/json: schema: type: object unevaluatedProperties: false required: - id - object - amount - currency - payment_intent - status - live_mode - created properties: id: type: string pattern: ^pi_[0-9a-z]{26}$ readOnly: true description: > ID do reembolso, no formato TypeID com prefixo `pi_`. Corresponde ao ID do `payment_intent` reembolsado (o reembolso compartilha o ID do payment_intent que ele afeta). example: pi_01h455vb4pex5vsknk084sn02q object: type: string description: Tipo do objeto. Sempre 'refund'. enum: - refund example: refund amount: type: integer description: Valor em centavos. R$ 99,90 = 9990. example: 9990 currency: type: string description: Moeda do valor. Sempre 'brl' (Real brasileiro). enum: - brl example: brl payment_intent: type: string pattern: ^pi_[0-9a-z]{26}$ description: >- ID do payment_intent que foi reembolsado, no formato TypeID com prefixo `pi_`. example: pi_01h455vb4pex5vsknk084sn02q status: type: string description: | Status atual do reembolso. - `refunding`: Reembolso em processamento (PIX). - `refunded`: Reembolso concluído com sucesso. enum: - refunding - refunded example: refunded live_mode: type: boolean description: >- Indica ambiente de produção (true) ou sandbox (false). Dados de sandbox são limpos periodicamente. example: true created: type: integer format: int64 readOnly: true description: Timestamp Unix de quando o reembolso foi criado. example: 1704672000 example: id: pi_01h455vb4pex5vsknk084sn02r object: refund amount: 9990 currency: brl payment_intent: pi_01h455vb4pex5vsknk084sn02q status: refunded live_mode: true created: 1704672000 '202': description: Reembolso aceito e em processamento (PIX) content: application/json: schema: type: object unevaluatedProperties: false required: - id - object - amount - currency - payment_intent - status - live_mode - created properties: id: type: string pattern: ^pi_[0-9a-z]{26}$ readOnly: true description: > ID do reembolso, no formato TypeID com prefixo `pi_`. Corresponde ao ID do `payment_intent` reembolsado (o reembolso compartilha o ID do payment_intent que ele afeta). example: pi_01h455vb4pex5vsknk084sn02q object: type: string description: Tipo do objeto. Sempre 'refund'. enum: - refund example: refund amount: type: integer description: Valor em centavos. R$ 99,90 = 9990. example: 9990 currency: type: string description: Moeda do valor. Sempre 'brl' (Real brasileiro). enum: - brl example: brl payment_intent: type: string pattern: ^pi_[0-9a-z]{26}$ description: >- ID do payment_intent que foi reembolsado, no formato TypeID com prefixo `pi_`. example: pi_01h455vb4pex5vsknk084sn02q status: type: string description: | Status atual do reembolso. - `refunding`: Reembolso em processamento (PIX). - `refunded`: Reembolso concluído com sucesso. enum: - refunding - refunded example: refunded live_mode: type: boolean description: >- Indica ambiente de produção (true) ou sandbox (false). Dados de sandbox são limpos periodicamente. example: true created: type: integer format: int64 readOnly: true description: Timestamp Unix de quando o reembolso foi criado. example: 1704672000 example: id: pi_01h455vb4pex5vsknk084sn02r object: refund amount: 9990 currency: brl payment_intent: pi_01h455vb4pex5vsknk084sn02q status: refunding live_mode: true created: 1704672000 '404': description: Recurso não encontrado content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: >- URL que identifica o tipo de erro ocorrido. Útil para tratamento programático de erros. example: https://problems-registry.smartbear.com/validation-error format: uri maxLength: 1024 status: type: integer description: >- Código de status HTTP da resposta. Corresponde ao status code retornado na requisição. example: 400 format: int32 minimum: 100 maximum: 599 title: type: string description: >- Título curto e descritivo do erro. Ideal para exibir em logs ou mensagens de erro genéricas. example: Bad Request maxLength: 1024 detail: type: string description: >- Mensagem detalhada do erro específico para esta requisição. Use esta mensagem para entender o que deu errado. example: O campo email é obrigatório e não foi informado. maxLength: 4096 instance: type: string description: >- Identificador único desta ocorrência de erro. Forneça este valor ao solicitar suporte para facilitar o debug. example: req_abc123def456 maxLength: 1024 code: type: string description: >- Código de erro interno da API. Útil para mapear tipos específicos de erros no seu código. example: VALIDATION_ERROR maxLength: 50 errors: type: array description: >- Lista de erros de validação específicos. Presente quando múltiplos campos falham na validação. maxItems: 1000 items: type: object description: >- Detalhes sobre um erro específico de validação. Ajuda a identificar qual campo e valor causaram o erro. required: - detail properties: detail: type: string description: >- Mensagem específica sobre o erro de validação deste campo. example: O campo email não é um endereço de e-mail válido. maxLength: 4096 pointer: type: string description: >- Caminho JSON para o campo no corpo da requisição que causou o erro. example: /customer/email maxLength: 1024 parameter: type: string description: Nome do parâmetro (query ou path) que causou o erro. example: customer_id maxLength: 1024 header: type: string description: Nome do cabeçalho HTTP que causou o erro. example: Authorization maxLength: 1024 code: type: string description: >- Código adicional para identificar o contexto específico do erro. example: INVALID_FORMAT maxLength: 50 examples: payment_intent_not_found: summary: Pagamento não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: 'No such payment_intent: ''pi_01h455vb4pex5vsknk084sn02q''' code: RESOURCE_MISSING '422': description: Erro de regra de negócio content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: >- URL que identifica o tipo de erro ocorrido. Útil para tratamento programático de erros. example: https://problems-registry.smartbear.com/validation-error format: uri maxLength: 1024 status: type: integer description: >- Código de status HTTP da resposta. Corresponde ao status code retornado na requisição. example: 400 format: int32 minimum: 100 maximum: 599 title: type: string description: >- Título curto e descritivo do erro. Ideal para exibir em logs ou mensagens de erro genéricas. example: Bad Request maxLength: 1024 detail: type: string description: >- Mensagem detalhada do erro específico para esta requisição. Use esta mensagem para entender o que deu errado. example: O campo email é obrigatório e não foi informado. maxLength: 4096 instance: type: string description: >- Identificador único desta ocorrência de erro. Forneça este valor ao solicitar suporte para facilitar o debug. example: req_abc123def456 maxLength: 1024 code: type: string description: >- Código de erro interno da API. Útil para mapear tipos específicos de erros no seu código. example: VALIDATION_ERROR maxLength: 50 errors: type: array description: >- Lista de erros de validação específicos. Presente quando múltiplos campos falham na validação. maxItems: 1000 items: type: object description: >- Detalhes sobre um erro específico de validação. Ajuda a identificar qual campo e valor causaram o erro. required: - detail properties: detail: type: string description: >- Mensagem específica sobre o erro de validação deste campo. example: O campo email não é um endereço de e-mail válido. maxLength: 4096 pointer: type: string description: >- Caminho JSON para o campo no corpo da requisição que causou o erro. example: /customer/email maxLength: 1024 parameter: type: string description: Nome do parâmetro (query ou path) que causou o erro. example: customer_id maxLength: 1024 header: type: string description: Nome do cabeçalho HTTP que causou o erro. example: Authorization maxLength: 1024 code: type: string description: >- Código adicional para identificar o contexto específico do erro. example: INVALID_FORMAT maxLength: 50 examples: already_refunded: summary: Pagamento já reembolsado value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Pagamento já foi estornado code: ALREADY_REFUNDED not_paid: summary: Pagamento não está pago value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Pagamento não está no estado pago code: NOT_PAID zero_amount: summary: Valor zero value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Não é possível reembolsar pagamento com valor zero code: ZERO_AMOUNT no_completed_transaction: summary: Nenhuma transação concluída value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Nenhuma transação concluída encontrada code: NO_COMPLETED_TRANSACTION refund_time_limit_exceeded: summary: Prazo PIX excedido value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Prazo de estorno PIX excedido (90 dias) code: REFUND_TIME_LIMIT_EXCEEDED refund_denied: summary: Reembolso negado pelo emissor value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Estorno negado pelo emissor code: REFUND_DENIED refund_transaction_not_allowed: summary: Transação não permitida value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Reembolso não permitido para esta transação code: REFUND_TRANSACTION_NOT_ALLOWED refund_cancellation_not_allowed: summary: Cancelamento não permitido value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Cancelamento não permitido code: REFUND_CANCELLATION_NOT_ALLOWED refund_failed: summary: Erro genérico no processamento value: type: >- https://problems-registry.smartbear.com/business-rule-violation status: 422 title: Unprocessable Entity detail: Erro no processamento do reembolso code: REFUND_FAILED '503': description: Serviço temporariamente indisponível content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: >- URL que identifica o tipo de erro ocorrido. Útil para tratamento programático de erros. example: https://problems-registry.smartbear.com/validation-error format: uri maxLength: 1024 status: type: integer description: >- Código de status HTTP da resposta. Corresponde ao status code retornado na requisição. example: 400 format: int32 minimum: 100 maximum: 599 title: type: string description: >- Título curto e descritivo do erro. Ideal para exibir em logs ou mensagens de erro genéricas. example: Bad Request maxLength: 1024 detail: type: string description: >- Mensagem detalhada do erro específico para esta requisição. Use esta mensagem para entender o que deu errado. example: O campo email é obrigatório e não foi informado. maxLength: 4096 instance: type: string description: >- Identificador único desta ocorrência de erro. Forneça este valor ao solicitar suporte para facilitar o debug. example: req_abc123def456 maxLength: 1024 code: type: string description: >- Código de erro interno da API. Útil para mapear tipos específicos de erros no seu código. example: VALIDATION_ERROR maxLength: 50 errors: type: array description: >- Lista de erros de validação específicos. Presente quando múltiplos campos falham na validação. maxItems: 1000 items: type: object description: >- Detalhes sobre um erro específico de validação. Ajuda a identificar qual campo e valor causaram o erro. required: - detail properties: detail: type: string description: >- Mensagem específica sobre o erro de validação deste campo. example: O campo email não é um endereço de e-mail válido. maxLength: 4096 pointer: type: string description: >- Caminho JSON para o campo no corpo da requisição que causou o erro. example: /customer/email maxLength: 1024 parameter: type: string description: Nome do parâmetro (query ou path) que causou o erro. example: customer_id maxLength: 1024 header: type: string description: Nome do cabeçalho HTTP que causou o erro. example: Authorization maxLength: 1024 code: type: string description: >- Código adicional para identificar o contexto específico do erro. example: INVALID_FORMAT maxLength: 50 examples: gateway_configuration_error: summary: Erro de configuração value: type: >- https://problems-registry.smartbear.com/service-unavailable status: 503 title: Service Unavailable detail: Erro de configuração do gateway code: GATEWAY_CONFIGURATION_ERROR refund_issuer_unavailable: summary: Emissor indisponível value: type: >- https://problems-registry.smartbear.com/service-unavailable status: 503 title: Service Unavailable detail: Emissor do cartão temporariamente indisponível code: REFUND_ISSUER_UNAVAILABLE refund_system_error: summary: Erro no sistema de reembolso value: type: >- https://problems-registry.smartbear.com/service-unavailable status: 503 title: Service Unavailable detail: Erro no processamento do reembolso code: REFUND_SYSTEM_ERROR security: - apiKeyAuth: [] components: securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: > A chave de API usada para autenticar a requisição e identificar a sua conta. **Exemplo:** `Authorization: ApiKey my-secure-key` ````