> ## 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.

# Cancelar um Payout

Às vezes é necessário interromper um payout após o início do processamento; este guia aborda os procedimentos de cancelamento.

Se você precisar cancelar um payout devido a um erro ou a uma mudança nos requisitos, é possível fazê-lo desde que o payout esteja em um dos seguintes status: **Pending Authorization**, **Received**, **On Hold** ou **Locked**.

Você pode cancelar pagamentos através do [Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-review-payout.md) ou programaticamente via API.

## Pré-requisitos

Antes de cancelar um payout, certifique-se de ter:

* Uma **transação de payout ativa** com status: `PendingAuth`, `Received`, `OnHold` ou `Locked`
* Credenciais de API válidas com as permissões adequadas
* O identificador da transação (`externalId`)

> [!WARNING]
>
> **Importante**
>
> Quando um payout passa para o status **Processing** ou **Completed**, ele não pode ser cancelado pela API. Entre em contato com o suporte para obter ajuda com transações já processadas.

***

## Endpoint da API

Para cancelar um payout, envie uma solicitação `PATCH` para o endpoint [Cancelar um Payout](https://docs.localpayment.com/pt-br/reference/void-a-payout.md).

### Solicitação de Cancelamento de Payout

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
PATCH https://api.stage.localpayment.com/api/payout/cancel
```

### Autenticação

Inclua seu token de acesso nos cabeçalhos da solicitação:

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
Authorization: Bearer <your_access_token>
```

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

| Parâmetro | Tipo | Descrição | Obrigatório |
| - | - | - | - |
| `externalId` | string | Identificador único da transação no seu sistema | ✅ |

### Exemplo de solicitação

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request PATCH \
     --url https://api.stage.localpayment.com/api/payout/cancel \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "externalId": "a971b7ee-fe47-4112-81fc-484f8e5c64d7"
     }'
```

***

## Tratamento de Respostas

### Resposta bem-sucedida

Quando o cancelamento é bem-sucedido, você receberá uma resposta com o status atualizado:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "a971b7ee-fe47-4112-81fc-484f8e5c64d7",
  "internalId": "3d36811d-1c02-41ea-a576-68df62c4603a",
  "status": {
    "code": "900",
    "description": "Cancelled",
    "detail": "The payout was cancelled successfully"
  }
}
```

#### Campos de resposta principais

| Campo | Tipo | Descrição |
| - | - | - |
| `externalId` | string | Identificador da transação no seu sistema |
| `internalId` | string | ID interno da transação da Localpayment |
| `status.code` | string | Código de status (900 = Cancelled) |
| `status.description` | string | Descrição do status legível por humanos |
| `status.detail` | string | Detalhes adicionais sobre o cancelamento |

### Respostas de erro

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "Status": 404,
  "Message": "This transaction does not exist.",
  "TraceId": "dae2d1cb-7e9e-48a5-8530-980f38b31712"
}
```

***

## Melhores práticas de implementação

* Sempre valide o status da transação antes de tentar o cancelamento
* Use HTTPS em todas as solicitações da API
* Armazene os tokens de acesso de forma segura e faça a rotação deles regularmente
* Implemente um tratamento de erros adequado e uma lógica de nova tentativa
* Registre em log todas as tentativas de cancelamento para fins de auditoria

***

## Testando sua implementação

Antes de implantar em produção, teste sua lógica de cancelamento minuciosamente:

1. **Teste com transações válidas** em status que permitem cancelamento
2. **Teste com transações inválidas** para tratar erros de forma adequada
3. **Teste falhas de autenticação** e expiração de token
4. **Verifique o tratamento de webhooks**, se implementado
5. **Teste a limitação de taxa** e a lógica de nova tentativa

***

## Recursos e próximos passos

Maximize o sucesso da sua integração com estes recursos essenciais

> [card] [Integração de Webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure notificações em tempo real para atualizações do status das transações.

> [card] [Relatórios do Business Portal](https://docs.localpayment.com/pt-br/docs/balance-report.md)
>
> Acesse análises detalhadas, ferramentas de geração de relatórios e recursos de conciliação.

> [card] [Monitoramento de transações](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes)
>
> Aprenda a consultar o status das transações e a implementar um rastreamento abrangente.

> [card] [Referência da API](https://docs.localpayment.com/pt-br/reference/exchange-bulk.md)
>
> Documentação completa dos endpoints com exemplos interativos.

> [!NOTE]
>
> **Dica profissional**
>
> Sempre teste seu fluxo de trabalho em nosso ambiente de sandbox antes de implantá-lo em produção. Isso garante que o tratamento de erros, o processamento de webhooks e o rastreamento de status funcionem corretamente em todos os cenários.

***

> [!NOTE]
>
> **Precisa de ajuda?**
>
> Entre em contato com nossa [equipe de suporte](mailto:support@localpayment.com) caso encontre algum problema ou precise de ajuda com a integração.


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