> ## 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 pagamento APM

O Localpayment permite cancelar pagamentos APM pendentes por meio da integração da API. Este guia aborda o fluxo de trabalho completo de cancelamento para transações APM usando o método de cancelamento direto, que requer apenas o externalId da transaçã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 de webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

### Requisitos adicionais de cancelamento:

* Função de usuário com permissões de cancelamento (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 em um estado que permita cancelamento.
* O `externalId` da transação de pagamento APM que você deseja cancelar.
* Preencha as informações do beneficiário para reembolsos que exigem dados.

***

## Cancelamento direto para pagamentos APM

Os cancelamentos de pagamentos APM são processados como **Cancelamentos Diretos**, ou seja, você só precisa do `externalId` da transação original e do parâmetro `status` definido como `CANCELLED`. O sistema interrompe imediatamente qualquer processamento adicional do pagamento.

> [!WARNING]
>
> **Importante**
>
> Pagamentos APM só podem ser cancelados enquanto estiverem pendentes ou em andamento. Após a conclusão ou liquidação de um pagamento APM, você deverá processar um reembolso em vez de um cancelamento.

***

## Etapa 1: Cancelar pagamento APM via API

Para cancelar um pagamento APM, envie uma solicitação `PATCH` para o endpoint [Cancel](https://docs.localpayment.com/pt-br/reference/cancel-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 | ✅ |
| `status` | Deve ser definido como `CANCELLED` para iniciar o cancelamento | ✅ |

### Exemplo de solicitação

Abaixo está um exemplo usando `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/transactions/{{externalId}}/status' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "CANCELLED"
  }'
```

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

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Detalhes da confirmação de um pagamento APM cancelado com sucesso:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "1c364061-1f3d-4b94-c270-bf915c22e8f5",
  "internalId": "8a9abd31-31e0-429a-32a6-cca8b9e1e536",
  "status": {
    "code": "900",
    "description": "CANCELLED",
    "detail": "The payin was cancelled"
  }
}
```

### 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 cancelamento (`900` para cancelamento bem-sucedido). | Monitoramento de status. |

### Resposta de erro

Quando uma solicitação de cancelamento 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 |
| - | - | - |
| 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 que permita cancelamento | Verifique o status da transação e certifique-se de que ela ainda está pendente ou em andamento antes de tentar o cancelamento |
| 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. |
| Já concluída | A transação já foi concluída e não pode ser cancelada | Processe um reembolso em vez de um cancelamento para transações concluídas |
| Parâmetro inválido | O parâmetro `status` está ausente ou não está definido como `CANCELLED` | Certifique-se de que o corpo da solicitação contenha `{"status": "CANCELLED"}` exatamente como especificado |

***

## Etapa 3: Rastrear o status do cancelamento

Após iniciar um cancelamento, monitore 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 de status de cancelamento comuns

| Código | Status | Descrição |
| :- | :- | :- |
| `400` | `ERROR` | A solicitação de cancelamento falhou devido a erros de validação ou parâmetros inválidos. |
| `900` | `CANCELLED` | O payin foi cancelado com sucesso. |

> [!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. **Cancelamento bem-sucedido**: Cancele um pagamento APM pendente com um externalId válido.
2. **Transação inválida**: Tente cancelar um externalId inexistente.
3. **Já concluída**: Tente cancelar uma transação concluída.
4. **Validação de permissões**: Teste com usuários que possuem diferentes níveis de permissão.
5. **Parâmetro de status ausente**: Tente o cancelamento sem o campo de status obrigatório.

***

## Próximos passos

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

> [card] [Processar reembolsos](https://docs.localpayment.com/pt-br/docs/refund-apm-payment.md)
>
> Aprenda como processar reembolsos de pagamentos APM concluídos que não podem
> ser cancelados.


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