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

# Pré-autorização e captura

A pré-autorização é um processo em duas etapas que permite aos comerciantes verificar o método de pagamento de um cliente antes de concluir uma transação. Esse processo retém temporariamente o valor da transação na conta do cliente, sem debitá-lo efetivamente.

Na **primeira etapa**, é feita uma solicitação de pré-autorização, reservando o valor especificado. Isso garante que o cliente tenha fundos suficientes e que o método de pagamento seja válido. No entanto, os fundos não são transferidos para o comerciante nesta fase.

Na **segunda etapa**, a solicitação de captura é executada para finalizar o pagamento. O valor pré-autorizado é então debitado da conta do cliente e creditado ao comerciante.

***

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

***

## Passo 1: Solicitar uma pré-autorização

Para iniciar uma pré-autorização, você precisará enviar uma solicitação `POST` para o endpoint [Criar Payin](https://docs.localpayment.com/reference/payins.md) e definir o header `x-capture` como `true`.

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

A solicitação requer vários objetos-chave:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| `beneficiary` | Dados do destinatário, incluindo informações bancárias. | ✅ |
| `sender` | Informações do remetente para fins de conformidade | ✅ |
| `merchant` | Detalhes do comerciante/empresa | ✅ |
| `paymentMethod` | Configuração do método de pagamento | ✅ |
| `amount` | Valor da transação | ✅ |
| `currency` | Código da moeda da transação | ✅ |
| `country` | Código do país de destino | ✅ |

O `paymentMethod.code` depende do país, da bandeira do cartão e do produto (crédito ou débito). No Peru, ele também depende da moeda. Consulte os [Códigos de métodos de pagamento com cartão](https://docs.localpayment.com/pt-br/docs/card-payment-methods.md) para ver a lista completa.

### 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 POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --header 'x-capture: true' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1000",
        "flow": "DIRECT"
    },
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "country": "ARG",
    "currency": "ARS",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "CUIT",
            "id": "3000091105"
        },
        "email": "mail@company.com",
        "phone": {
            "countryCode": "54",
            "areaCode": "351",
            "number": "1234567"
        }
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "DNI",
            "id": "37993123"
        },
        "email": "john.doe@example.com",
        "phone": {
            "countryCode": "1",
            "areaCode": "11",
            "number": "98189123"
        },
        "bank": {
            "name": "BANCO BBVA ARGENTINA S.A.",
            "code": "017",
            "account": {
                "type": "S",
                "number": "19101196551119123456789"
            }
        }
    },
    "commercialData": {
        "items": [
            {
                "id": "12345",
                "quantity": "1",
                "description": "Test product",
                "title": "Test",
                "unitPrice": "1000"
            }
        ]
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029"
    }
}'
```

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

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Uma resposta bem-sucedida inclui informações detalhadas sobre a transação e identificadores de rastreamento.

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "transactionType": "PayIn",
  "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
  "internalId": "22b29c98-92af-44bd-a164-1863ae2f1bb3",
  "paymentMethod": {
    "type": "CreditCard",
    "code": "1000",
    "flow": "DIRECT"
  },
  "country": "ARG",
  "currency": "ARS",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}",
  "confirmed": {
    "currency": "ARS",
    "amount": 1000,
    "fxQuote": 1,
    "exchangeRateToken": null
  },
  "payment": {
    "installment": null,
    "currency": "ARS",
    "fxQuote": 1,
    "financingFee": 0,
    "amount": 1000
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "ARS",
    "fxSource": 210.8,
    "fxQuote": 1,
    "amount": 13.02,
    "account": "{{accountNumber}}"
  },
  "status": {
    "code": "102",
    "description": "AUTHORIZED",
    "detail": "The payin was authorized"
  },
  "ticket": null,
  "qr": null,
  "beneficiary": null,
  "merchant": {
    "type": "COMPANY",
    "name": "Company"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "id": "37895247",
      "type": "DNI"
    },
    "email": "john.doe@example.com",
    "phone": {
      "countryCode": "1",
      "areaCode": "11",
      "number": "98789632"
    },
    "address": null,
    "birthdate": null,
    "nationality": null
  },
  "intermediaries": [],
  "wireInstructions": null,
  "date": {
    "creationDate": "2024-05-19T19:02:44.018+00:00",
    "processedDate": "2024-05-19T19:02:44.799618",
    "expirationDate": "0001-01-01T00:00:00"
  },
  "card": {
    "bin": "402670",
    "brand": "VISA",
    "country": "RS",
    "name": "John Doe",
    "last4": "3263",
    "expirationYear": 2029,
    "expirationMonth": 9
  },
  "errors": []
}
```

### Campos de resposta principais

| Campo | Descrição | Caso de uso |
| - | - | - |
| `internalId` | Identificador de transação exclusivo da Localpayment | Rastreamento e suporte de transações |
| `externalId` | Seu número de referência | Reconciliação interna |
| `status.code` | Código de status da transação atual | Monitoramento de status |
| `date.creationDate` | Quando a transação foi criada | Registro de auditoria |
| `date.processedDate` | Quando a transação começou a ser processada. | Cálculo do tempo de processamento |

### Resposta de erro

Quando uma solicitação falhar, você receberá informações detalhadas sobre o erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "46014bdc-c3a7-1b15-8dcf-c7050c1c8199",
  "internalId": "caa4e9aa-f634-497c-ba75-7f88b005ca62",
  "status": {
    "code": "801",
    "description": "REJECTED",
    "detail": "Params error"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [paymentMethod] + doesn´t exists for MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.bank.account.[number, type | alias]] + must not be null"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document.type] + is invalid for country MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document] + is invalid for payer type"
    },
    {
      "code": "701",
      "detail": "IncorrectAccountNumber"
    }
  ]
}
```

***

## Etapa 3: Capturar os fundos

Após pré-autorizar uma transação, você deve capturar os fundos para debitar a conta do cliente. Certifique-se de que a solicitação de captura seja para o valor total da pré-autorização. A retenção da pré-autorização sobre os fundos expirará após **7 dias**. Se você não capturar os fundos dentro desse período, eles serão liberados automaticamente para o cartão do cliente.

Para capturar uma pré-autorização, envie uma solicitação `PATCH` para o endpoint [Capturar Payin autorizado](https://docs.localpayment.com/reference/capture-payin.md).

### Exemplo de solicitação

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --location --request PATCH 'https://api.stage.localpayment.com/api/payin/capture/{externalId}' \
--header 'Authorization: Bearer <your_access_token>'
```

### Resposta bem-sucedida

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "40ae5d95-e859-4fc9-b37b-67442392b785",
    "status": {
        "code": "103",
        "description": "APPROVED",
        "detail": "The payin was confirmed but not credited yet"
    }
}
```

***

## Liberar fundos não utilizados

Para garantir uma experiência positiva para o cliente, recomenda-se liberar quaisquer fundos pré-autorizados que não serão utilizados. Ao iniciar a liberação por meio de uma solicitação de API, você evita que seus clientes esperem os 7 dias completos para a liberação automática.

Para liberar fundos não utilizados, envie uma solicitação `PATCH` para o endpoint [Cancelar autorização de Payin](https://docs.localpayment.com/reference/cancel-authorization.md).

### Exemplo de solicitação

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --location --request PATCH 'https://api.stage.localpayment.com/api/payin/capture/{externalId}/status/' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "CANCELLED"
}'
```

### Resposta bem-sucedida

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "externalId": "40bac59a-0381-4cc0-a6a5-33418d84c2e4",
    "internalId": "39eb0371-3f21-488f-a779-913799e51406",
    "status": {
        "code": "905",
        "description": "CANCELLED",
        "detail": "The authorization was cancelled"
    }
}
```

***

## Etapa 4: Rastrear o status da transação

Após iniciar um pagamento pré-autorizado, acompanhe seu andamento por meio 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 comuns

A API Localpayment fornece vários códigos de status para indicar o progresso e o resultado do pagamento na resposta.

| Código | Status | Descrição |
| :- | :- | :- |
| `103` | `APPROVED` | O Payin foi confirmado, mas ainda não foi creditado. |
| `200` | `Completed` | O Payin foi concluído. |
| `701` | `Rejected` | Número de conta bancária inválido. |

> [!NOTE]
>
> **APPROVED não é o status final.** Significa que o pagamento com cartão foi confirmado, mas os fundos ainda não foram creditados no seu saldo. Você pode ver o pagamento, mas não pode sacar os fundos até que o status mude para Completed. Isso costuma levar de 1 a 2 dias, dependendo do provedor.

> [!NOTE]
>
> Para obter informações completas sobre os códigos de status, consulte a documentação de [Status da Transação](https://docs.localpayment.com/reference/payin-status-error-codes.md).

## Testando sua integração

### Cenários de teste

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

1. **Transação concluída com sucesso**: Fluxo padrão de Payin
2. **Erros de validação**: conta bancária inválida, campos ausentes
3. **Atrasos no processamento**: transações que levam tempo para serem processadas.
4. **Transações com falha**: Fundos insuficientes, beneficiários bloqueados
5. **Atualizações de status**: gerenciamento de webhooks e consulta de status.

***

## Próximos passos

Após o processamento da pré-autorização, você poderá precisar realizar ações adicionais, como:

> [card] [Reembolsar a transação](https://docs.localpayment.com/docs/refunds/)
>
> Caso necessário, você pode reembolsar o pagamento ao cliente. Consulte a documentação de Reembolsos para obter detalhes.

> [card] [Gerenciar estornos](https://docs.localpayment.com/docs/chargebacks.md)
>
> Em caso de disputa, você poderá precisar lidar com estornos. Consulte a documentação sobre estornos para obter informações sobre esse processo.

> [card] [Analisar detalhes da transação](https://docs.localpayment.com/reference/get-transaction-status.md)
>
> Recupere informações de transações usando a API Localpayment. Consulte a documentação de Informações de Transação para obter detalhes.


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