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

# Parcelas

Atraia mais clientes permitindo que dividam as compras em pagamentos mensais. Saiba como implementar e gerenciar facilmente planos de parcelamento para aumentar a conversão e o valor médio dos pedidos.

A Localpayment permite que os comerciantes ofereçam planos de parcelamento, para que os clientes dividam suas compras em vários pagamentos mensais. Este guia descreve o processo de criação de planos de parcelamento por meio da API da Localpayment, detalhando os parâmetros obrigatórios, o tratamento das respostas e o gerenciamento de todo o ciclo de vida do parcelamento.

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

***

## Etapa 1: Criar o orçamento do plano de parcelamento

Antes de processar um pagamento parcelado, você precisa gerar um orçamento do plano de parcelamento para apresentar as opções de pagamento ao cliente.

Para solicitar o orçamento de um plano de parcelamento, você precisará enviar uma solicitação `POST` para o endpoint [Gerar orçamento de parcelamento](https://docs.localpayment.com/pt-br/reference/installments.md).

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

| Objeto | Descrição | Obrigatório |
| - | - | - |
| `paymentMethod.code` | Código do método de pagamento. Somente métodos `CreditCard` são compatíveis. | ✅ |
| `amount` | Valor total da transação | ✅ |
| `currency` | Código da moeda da transação | ✅ |
| `country` | País em que o pagamento será processado | ✅ |

> [!NOTE]
>
> As parcelas estão disponíveis somente em moeda local. No Peru, você pode oferecer parcelamento em pagamentos em PEN, mas não em pagamentos em USD.

### Exemplo de solicitação

Abaixo segue 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/installments-plans \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentMethod": {
    "code": "1600"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}"
}
'
```

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

***

## Etapa 2: Lidar com a resposta do orçamento

### Resposta bem-sucedida

Um orçamento de parcelamento bem-sucedido inclui informações detalhadas do plano de pagamento:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "installmentsToken": "bc1a1923-fadc-427b-b014-e43eb4462e81",
  "creationDate": "2025-01-29T23:53:52.7150456+00:00",
  "expirationDate": "2025-01-30T00:03:52.71509+00:00",
  "currency": "MXN",
  "amount": 1000,
  "installments": [
        {
            "installments": 3,
            "installmentAmount": 448.98,
            "totalPaymentAmount": 1346.95,
            "financingFee": 346.95
        },
        {
            "installments": 6,
            "installmentAmount": 275.68, 
            "totalPaymentAmount": 1654.12, 
            "financingFee": 654.12
        }
    ]
}
```

### Campos de resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `installmentsToken` | Token exclusivo que identifica o orçamento de parcelamento | Necessário para processar o plano de parcelamento selecionado. |
| `creationDate` | Carimbo de data e hora em que o orçamento foi gerado. | Acompanhe a validade e o momento do orçamento. |
| `expirationDate` | Carimbo de data e hora em que o orçamento expira. | Garanta que o cliente selecione o plano antes da expiração. |
| `currency` | A moeda da transação. | Exiba o símbolo de moeda correto ao cliente. |
| `installments` | Array com as opções de parcelamento disponíveis. | Apresente ao cliente várias opções de plano de pagamento. |
| `installments.installments` | Número de pagamentos mensais. | Mostre a duração do prazo de pagamento. |
| `installments.installmentAmount` | Valor do pagamento mensal. | Exiba o custo mensal ao cliente. |
| `installments.totalPaymentAmount` | Valor total, incluindo taxas. | Mostre o custo total do financiamento. |
| `installments.financingFee` | Custo total do financiamento. | Exiba as taxas e os juros separadamente. |

### Resposta de erro

Quando a geração do orçamento de parcelamento falha::

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "300",
    "detail": "Instalment Payment Plan is only for types of Credit Card methods"
  }
}
```

### Melhores práticas para apresentação de parcelamentos

* Exiba todos os custos com clareza (taxas de financiamento, valor total)
* Mostre os valores das parcelas mensais em destaque
* Inclua uma comparação entre as diferentes opções de parcelamento
* Explique o processo de pagamento automático das parcelas futuras
* Inclua informações de suporte ao cliente
* Trate a expiração do token com elegância (**janela de 10 minutos**)

***

## Etapa 3: Processar o pagamento parcelado

Depois que o cliente selecionar um plano de parcelamento, processe o pagamento usando o token de parcelamento.

### Exemplo de solicitação

```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' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "mail@company.com"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029",
        "installments": 3,
        "installmentsToken": "bc1a1923-fadc-427b-b014-e43eb4462e81"
    }
}'
```

***

## Etapa 4: Acompanhar o status do parcelamento

Acompanhe o progresso do plano de parcelamento por meio destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real para cada pagamento parcelado e para as mudanças de status do plano.

> [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 monitorar os planos de parcelamento e o desempenho dos pagamentos.

### Códigos de status comuns

A API da Localpayment fornece vários códigos de status para planos de parcelamento e pagamentos.

| Código | Status | Descrição |
| :- | :- | :- |
| `103` | `APPROVED` | O Payin foi confirmado, mas ainda não foi creditado. |
| `200` | `Completed` | O Payin foi concluído. |
| `811` | `Rejected` | O valor solicitado é maior ou menor que os valores máximo/mínimo permitidos. |

> [!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]
>
> **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).

***

## Etapa 5: Gerenciar o ciclo de vida do parcelamento

### Fluxo de pagamento parcelado

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'actorBkg': '#31467c', 'actorBorder': '#0c1a29', 'actorTextColor': '#ffffff', 'actorLineColor': '#0c1a29', 'signalColor': '#0c1a29', 'signalTextColor': '#0c1a29', 'labelBoxBkgColor': '#31467c', 'labelBoxBorderColor': '#0c1a29', 'labelTextColor': '#ffffff', 'loopTextColor': '#0c1a29', 'noteBkgColor': '#ffffff', 'noteBorderColor': '#31467c', 'noteTextColor': '#0c1a29'}}}%%
sequenceDiagram
    participant C as Cliente
    participant M as Lojista
    participant LP as Localpayment
    participant B as Banco
    
    C->>M: Inicia o pagamento com opção de parcelamento
    M->>LP: Solicita cotação de parcelamento
    LP->>M: Retorna installmentsToken e as opções
    M->>C: Apresenta os planos de parcelamento
    C->>M: Seleciona o plano preferido
    M->>LP: Processa o pagamento com installmentsToken
    LP->>B: Autoriza a primeira parcela
    B->>LP: Autorização confirmada
    LP->>M: Confirmação do pagamento
    M->>C: Exibe o resultado do pagamento (aprovado/recusado)
    Note over C: O cliente recebe o status da transação e os detalhes do plano de pagamento
    Note over LP: As parcelas mensais são processadas automaticamente
    LP->>M: Webhook para cada parcela
```

***

## Testando sua integração

### Cenários de teste

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

1. **Parcelamento bem-sucedido**: fluxo completo de pagamento parcelado
2. **Várias opções de plano**: apresente diferentes prazos de parcelamento (2, 3, 6 meses)
3. **Expiração do token**: trate o installmentsToken expirado (janela de 10 minutos)
4. **Atualizações de status**: gerenciamento de webhooks e consulta de status.

***

## Próximos passos

Após implementar o parcelamento, considere estes recursos adicionais::

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

> [card] [Analisar detalhes da transação](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Você pode obter informações detalhadas sobre as transações usando a API Localpayment.


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