> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reembolsar um pagamento com cartão

O Localpayment permite processar reembolsos de pagamentos com cartão, possibilitando a devolução de fundos para os cartões de crédito ou débito dos clientes por meio da integração de API e da interface do Business Portal. Este guia abrange o fluxo de trabalho completo de reembolso para transações com cartão.

## Antes de começar

Certifique-se de ter:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint do webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

### Requisitos adicionais para reembolso:

* Você precisa ter saldo suficiente em sua conta Localpayment para cobrir o valor do reembolso.
* Função de usuário com permissões de reembolso (consulte a documentação de [Funções de Usuário](https://docs.localpayment.com/pt-br/docs/user-roles-and-permissions.md)).
* A transação original deve estar com o status `Completed`.
* O `externalId` da transação de pagamento original.

***

## Guia de Implementação

A Localpayment oferece dois métodos para processar reembolsos de cartão: integração de API para processamento automatizado e Business Portal para operações manuais.

> [card] [Processamento de reembolso via API](https://docs.localpayment.com/pt-br/reference/refund-a-payin.md)
>
> Processe reembolsos programaticamente através da API REST para fluxos de trabalho automatizados e integração com seus sistemas.

> [card] [Processamento de reembolsos no Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-create-manual-refund.md)
>
> Processe reembolsos manualmente através do Business Portal Localpayment com uma interface amigável.

***

## Reembolsos diretos para pagamentos com cartão

Para transações com cartão, os reembolsos são processados como **Reembolsos Diretos**, o que significa que você só precisa do `externalId` da transação original. Não são necessários dados adicionais de beneficiário ou bancários, pois os fundos são devolvidos ao cartão original usado no pagamento.

***

## Etapa 1: Processar reembolso via API

Para reembolsar um pagamento com cartão via API, envie uma solicitação `PATCH` para o endpoint de [Reembolso](https://docs.localpayment.com/pt-br/reference/refund-a-payin.md).

### Parâmetros-chave da solicitação

A solicitação requer vários parâmetros-chave:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| `externalId` | O externalId da transação original. | ✅ |

### Exemplo de solicitação

Abaixo segue um exemplo de uso do `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request PATCH \
  --url 'https://api.stage.localpayment.com/api/payin/{{externalId}}/refund' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --data '{
    "comment": "Refund API Credit Card"
  }'
```

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/refund-a-payin.md) na solicitação.

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Detalhes da confirmação de reembolso processado com sucesso:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "d260ae17-0978-4429-bda1-8dfed9da6c6b",
  "internalId": "53c91969-147e-4273-a659-ee5012ce9c83",
  "status": {
    "code": "902",
    "description": "REFUNDED",
    "detail": "The payin was refunded"
  }
}
```

### Campos de resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `externalId` | Sua referência para a transação original. | Conciliação e rastreamento. |
| `internalId` | Identificador de reembolso exclusivo da Localpayment. | Para fins de suporte e auditoria. |
| `status.code` | Código de status do reembolso (`902` para reembolso bem-sucedido). | Monitoramento de status. |

### Resposta de erro

Quando um pedido de reembolso falha, você receberá as seguintes informações de erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "400",
    "description": "ERROR",
    "detail": "Invalid operation"
  }
}
```

### Cenários de erro comuns

| Erro | Descrição | Solução |
| - | - | - |
| Fundos insuficientes | O saldo da sua conta Localpayment é insuficiente para cobrir o valor do reembolso. | Adicione fundos à sua conta Localpayment ou aguarde a liquidação de pagamentos pendentes. |
| Transação não encontrada | O `externalId` informado não existe ou é inválido | Verifique se o externalId está correto e se a transação existe no seu histórico de transações. |
| Status inválido | A transação original não está em um estado reembolsável (deve estar `Completed`) | Verifique o status da transação e certifique-se de que ela foi processada com sucesso antes de solicitar um reembolso. |
| Permissão negada | Sua função de usuário não possui as permissões de reembolso necessárias. | Contate o administrador da sua conta para conceder as permissões de reembolso adequadas à sua função. |
| Reembolso duplicado | Tentativa de reembolso de uma transação que já foi reembolsada. | Verifique se a transação não foi reembolsada anteriormente consultando o status do reembolso. |
| Valor inválido | Tentativa de reembolso parcial quando apenas reembolsos integrais são permitidos. | Processar reembolso apenas do valor total da transação. |

***

## Reembolsos do Business Portal

Os reembolsos de cartão também podem ser processados ​​através da interface do Business Portal da Localpayment. Este método oferece um fluxo de trabalho visual para gerenciar reembolsos e é particularmente útil para:

* **Reembolsos ocasionais** que não exigem automação por API.
* **Supervisão administrativa** onde são necessários fluxos de trabalho de aprovação.
* **Processamento rápido de reembolsos** sem necessidade de recursos de desenvolvimento.

Para obter instruções detalhadas sobre como processar reembolsos através do Business Portal, incluindo orientações passo a passo e tutoriais da interface, consulte o [Guia de Reembolsos do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-create-manual-refund.md).

> [!WARNING]
>
> **Aprovação necessária**:
>
> Todos os reembolsos iniciados pelo Business Portal da Localpayment exigem aprovação através do fluxo de autorização designado. Certifique-se de ter as permissões de usuário necessárias antes de tentar efetuar reembolsos pelo Business Portal.

***

## Etapa 3: Acompanhe o status do reembolso

Após iniciar um reembolso, acompanhe o seu progresso através destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Códigos comuns de status de reembolso

| Código | Status | Descrição |
| :- | :- | :- |
| `400` | `ERROR` | O pedido de reembolso falhou devido a erros de validação ou parâmetros inválidos. |
| `902` | `REFUNDED` | O Payin foi reembolsado com sucesso. |

> [!NOTE]
>
> **Os reembolsos não são instantâneos para o cliente.** O valor reembolsado pode levar vários dias para aparecer na fatura do cartão do cliente depois que você solicita o reembolso. O prazo exato depende do provedor de pagamentos e do emissor do cartão.

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Testando sua integração

### Cenários de teste

Verifique se sua integração lida com esses cenários:

1. **Reembolso bem-sucedido**: Processe o reembolso com um `externalId` válido e fundos suficientes.
2. **Fundos insuficientes**: Tentativa de reembolso devido ao saldo insuficiente na conta.
3. **Transação inválida**: Tente reembolsar um `externalId` inexistente.
4. **Reembolso duplicado**: Tentativa de reembolsar uma transação que já foi reembolsada.
5. **Validação de permissões**: Teste com usuários que possuem diferentes níveis de permissão.

***

## Próximos passos

> [card] [Ver o estado da transação](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consulte o status atual de transações e reembolsos usando a API de Status da Transação.

> [card] [Configurar webhooks](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure webhooks para receber notificações em tempo real sobre as mudanças de status do reembolso.

> [card] [Analisar funções de usuário](https://docs.localpayment.com/pt-br/docs/user-roles-and-permissions.md)
>
> Gerencie as permissões e funções dos usuários para os recursos de processamento de reembolsos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.