# Criar Pagamentos Cartão Presente com Parcelamento

Este guia explica como processar transações de pagamento parcelado em um ambiente **Cartão Presente** usando a Getnet Regional API. O parcelamento permite que os clientes em um terminal físico dividam o preço total da compra em valores menores e iguais pagos ao longo do tempo, com a transação protegida pela presença física do cartão.

## Requisitos

Antes de seguir os passos, você precisa:

- **Credenciais da API**: Entre em contato com a equipe de Suporte à Integração para obter seu `client_id` e `client_secret`.
- **Bearer Token**: Gere seu token usando o [endpoint de Autenticação](https://api.pre.globalgetnet.com/authentication/oauth2/access_token).
- **Configuração de Hardware**: Certifique-se de que seu terminal físico (POS/mPOS) esteja registrado e que você tenha um `terminal_number` válido.

> A Getnet fornece uma **Coleção Bruno/Postman** para ajudar você a replicar esses casos de uso específicos de hardware localmente.

## Especificidades do Caso de Uso: Métodos de Verificação de Cartão

As transações Cartão Presente exigem um **Método de Verificação do Portador (CVM)** e um **Modo de Entrada (Entry Mode)** definidos no objeto `card`.

- **Chip + PIN**: Exige que o hardware capture um `pin_block` criptografado e um `ksn` (Key Serial Number).
- **Chip (Sem CVM)**: Usado para transações de baixo valor ou aproximações que não exigem PIN.
- **Tarja Magnética**: O cartão é passado no leitor (swipe) e os dados completos do `track_2` são transmitidos.

## Entendendo o Parcelamento Cartão Presente

No fluxo Cartão Presente, um pagamento parcelado é criado como uma **transação única**. O detalhamento e a liquidação são gerenciados automaticamente pela rede do cartão com base no plano selecionado durante a leitura física do cartão.

### Como funciona a Liquidação (Settlement)

As regras de liquidação de parcelas variam de acordo com a região e a bandeira do cartão. Para um detalhamento completo sobre financiamento pelo estabelecimento vs. emissor e restrições regionais, consulte a Referência de Parcelamento.

## Processo de Pagamento Parcelado

O processo envolve duas etapas principais: solicitar as ofertas de parcelamento disponíveis para o cartão específico inserido no terminal e enviar o pagamento com a opção selecionada.

### Passo 1: Solicitar Ofertas de Parcelamento Disponíveis

Antes de iniciar o pagamento, você deve consultar as ofertas de parcelamento disponíveis para o cartão inserido em seu leitor de hardware usando o [endpoint Get Installments](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/installments/post/dpm/payments-gwproxy/v2/payments/quotes).

A API espera os seguintes detalhes:

| Atributo | Descrição | Obrigatório |
| --- | --- | --- |
| `amount` | Valor total da transação em centavos. | Sim |
| `bin` | Os primeiros 6 ou 9 dígitos da leitura do cartão físico. | Sim |
| `installment_type_filter` | Filtra os resultados por `no_interest` ou `with_interest`. | Não |

**Exemplo de Requisição:**

```bash
curl --request POST \
  --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments/quotes \
  --header 'authorization: Bearer <YOUR_TOKEN>' \
  --header 'content-type: application/json' \
  --data '{
  "amount": 100000,
  "bin": "515590122",
  "installment_type_filter": "no_interest"
}'

```

Extraia o `quote_id` e o `schema` da resposta para usar na requisição de pagamento.

### Passo 2: Criar o Pagamento Cartão Presente com Parcelamento

Uma vez que o cliente seleciona o plano de parcelamento no terminal, use o [endpoint Create - Authorize](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments) para processar o pagamento.

Para fluxos de parcelamento Cartão Presente, você deve definir o `data.payment.payment_method` como **`DIRECT_CREDIT`**.

#### Atributos de Parcelamento Específicos para

Para campos básicos de pagamento, consulte a [Referência da API de Pagamento](https://docs.globalgetnet.com/en/products/online-payments/regional-api/swagger#tag/payments).

| Objeto | Atributo | Descrição | Obrigatório |
| --- | --- | --- | --- |
| `terminal` | `terminal_number` | O ID exclusivo do hardware que lê o cartão. | **Sim** |
| `card` | `entry_mode` | Identifica como o cartão foi lido (`chip`, `magnetic_stripe`, etc.). | **Sim** |
| `card` | `cardholder_verification_method` | Lógica para verificação do portador (`online_pin` ou `no_cvm`). | **Sim (Chip)** |
| `card` | `emv` | A string TLV capturada do chip do cartão. | **Sim (Chip)** |
| `additional_data.installment` | `quote_id` | O identificador exclusivo da resposta da consulta de parcelamento. | **Sim** |
| `additional_data.installment` | `schema` | O esquema de parcelamento específico selecionado. | **Sim** |

#### Exemplo 1: Pagamento Parcelado com Chip + PIN Online

Usado quando o cliente insere o cartão e digita o PIN no terminal físico para pagar parcelado.

```json
{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "RETAIL-ORDER-202",
  "data": {
    "amount": 100000,
    "currency": "CLP",
    "customer_id": "ed2da8dd-1ba9-46e9-8501-f7987dcd9964",
    "payment": {
      "payment_id": "payment_id_venda",
      "payment_method": "DIRECT_CREDIT",
      "transaction_type": "INSTALL_NO_INTEREST",
      "number_installments": 3,
      "soft_descriptor": "MINHA*LOJA",
      "terminal": {
        "terminal_number": "21000334"
      },
      "card": {
        "entry_mode": "chip",
        "cardholder_verification_method": "online_pin",
        "seq_number": "000",
        "pin_block": "A0B6BA8D53C8D3C3",
        "ksn": "BC756011020000400001",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      }
    },
    "additional_data": {
      "installment": {
        "schema": "no_interest",
        "type": "no_interest",
        "quote_id": "4a29251d-41af-41fc-ac74-fa131e215e1b"
      }
    }
  }
}

```

#### Exemplo 2: Pagamento Parcelado com Chip (Sem PIN)

Usado para pagamentos parcelados onde não é necessária a digitação do PIN.

```json
{
  "idempotency_key": "c07372cf-6d11-4980-801f-a365840a0386",
  "data": {
    "amount": 100000,
    "currency": "CLP",
    "payment": {
      "payment_id": "payment_id_no_pin",
      "payment_method": "DIRECT_CREDIT",
      "transaction_type": "INSTALL_NO_INTEREST",
      "number_installments": 3,
      "terminal": {
        "terminal_number": "123456"
      },
      "card": {
        "entry_mode": "chip",
        "cardholder_verification_method": "no_cvm",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      }
    },
    "additional_data": {
      "installment": {
        "schema": "no_interest",
        "type": "no_interest",
        "quote_id": "4a29251d-41af-41fc-ac74-fa131e215e1b"
      }
    }
  }
}

```

### Exemplo de Resposta

Em caso de sucesso, a API retorna o detalhamento do parcelamento calculado.

```json
{
  "status": "APPROVED",
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "installments": {
    "number_installments": 3,
    "installment_value": 33334,
    "total_amount": 100002
  }
}

```

### Passo 3: Verificar Status do Pagamento (Opcional)

Pagamentos parcelados bem-sucedidos retornarão o status `APPROVED`. Você pode verificar o status da transação a qualquer momento usando o [endpoint Get Transaction](https://predocs.globalgetnet.com/dpm/hub-payment-info/v1/payments/info/{payment_id}).

## Próximos Passos

* Saiba como processar [Pagamentos de Passo Único](https://predocs.globalgetnet.com/en/products/online-payments/regional-api).
* Explore [Pré-autorizações em Dois Passos](https://predocs.globalgetnet.com/en/products/online-payments/regional-api).