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

A API espera os seguintes detalhes:

Exemplo de Requisição:

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

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.

{
  "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.

{
  "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.

{
  "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.

Próximos Passos

• Saiba como processar Pagamentos de Passo Único.
• Explore Pré-autorizações em Dois Passos.