Criar Pagamentos Parcelados

Este guia explica como processar transações de pagamento baseadas em parcelas usando a Global API da Getnet. O parcelamento permite que os clientes dividam o preço total da compra em vários valores menores e iguais, pagos durante um período de tempo acordado, proporcionando maior flexibilidade em vez de exigir o pagamento integral antecipado. A implementação desse método de pagamento depende da disponibilidade de suporte do cartão e das regulamentações regionais.

Requisitos

Antes de seguir os passos, você precisa:

• Criar sua conta entrando em contato com a equipe de Suporte à Integração para obter suas credenciais de API client_id e client_secret.
• Gerar seu token com suas credenciais usando o endpoint de Authentication.

A Getnet fornece uma Postman Collection para ajudá-lo a replicar esses casos de uso localmente. Você também pode testar a API no ambiente sandbox usando a API Reference disponível na documentação.

Especificidades dos Casos de Uso

Ao integrar qualquer solução da Getnet, aplicam-se requisitos específicos do mercado. Certifique-se de revisar os recursos abaixo antes de entrar em produção:

• Códigos de moeda
• Tipos de documento
• Impostos e regulamentações locais

Você também pode usar cartões de teste para simular cenários específicos. Mais informações sobre os requisitos específicos para cada país podem ser encontradas na seção Developer Resources da documentação da Getnet.

Disponibilidade da plataforma

O suporte a parcelamento varia de acordo com o país e a bandeira do cartão. Para uma referência completa de regras de parcelamento, esquemas de cartão disponíveis e tipos de planos por mercado, consulte as Regras e Disponibilidade de Parcelamentos.

Entendendo Como Funcionam os Pagamentos Parcelados

Um pagamento parcelado é criado como uma única transação de pagamento, não como várias autorizações separadas. Quando você cria um pagamento parcelado, você faz uma chamada de API, e a liquidação/captura é tratada automaticamente pela rede de cartões e bancos emissores, de acordo com o tipo de plano de parcelamento.

Como a Liquidação Funciona

Cada país tem diferentes tipos de planos de parcelamento com esquemas e modelos de liquidação específicos. O processo de liquidação varia dependendo do plano selecionado:

• Alguns planos liquidam o valor total para o lojista de uma só vez, com o banco cobrando as parcelas do cliente ao longo do tempo.
• Outros planos liquidam para o lojista em parcelas mensais automaticamente.
• O cliente pode ou não pagar juros, dependendo do tipo de plano.

Para obter informações detalhadas sobre planos de parcelamento, esquemas e modelos de liquidação disponíveis em cada país, consulte as Regras e Disponibilidade de Parcelamentos.

Processo de Pagamento Parcelado

Esta seção o orienta na criação de uma transação de pagamento parcelado. O processo envolve duas etapas principais: solicitar ofertas de parcelamento disponíveis e enviar o pagamento com a opção de parcelamento selecionada.

O diagrama abaixo ilustra o fluxo completo do pagamento parcelado:

Geração de Quote ID

Ao implementar parcelamentos nos mercados da Argentina e Chile, é obrigatório incluir o valor de quote_id nas solicitações de parcelamento da API para que as transações possam ser processadas corretamente. Este campo é usado para calcular taxas de juros, impostos e outros requisitos antes da autorização do pagamento.

Cálculos de taxas de juros

Para este processo, existem duas alternativas para lojistas e parceiros, dependendo das suas necessidades:

• Calculado pelo Usuário: O lojista calcula as taxas de juros externamente e informa a API por meio do campo amount. Nas chamadas de API, o quote_id deve ser gerado como no_interest.
• Calculado pela Getnet: O lojista depende dos cálculos de taxas de juros da Getnet, que incluem informações atualizadas do emissor/governo e, portanto, não precisará calculá-las externamente. Nas chamadas de API, o quote_id deve ser gerado como with_interest.

Tokenizar Dados do Cartão (Opcional)

Em vez de enviar o número do cartão no formato original (raw) na sua solicitação de pagamento, você pode usar a tokenização para aumentar a segurança e reduzir o escopo de conformidade do PCI DSS. Para usar um cartão tokenizado:

1. Tokenize o cartão chamando o endpoint de Card Tokenization com o card_number e o customer_id.
2. Na sua solicitação de pagamento, substitua o campo card.number por card.number_token usando o valor do token recebido do endpoint de tokenização.

Etapa 1: Solicitar Ofertas de Parcelamento Disponíveis

Antes de iniciar um pagamento, você deve consultar as ofertas de parcelamento disponíveis para o cartão selecionado e o valor da transação usando o endpoint de Get Installments.

A API da Getnet espera receber os seguintes detalhes na solicitação:

O bloco de código a seguir mostra um exemplo de solicitação:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/quotes \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --data '{
  "amount": 100000,
  "bin": "515590122",
  "installment_type_filter": "no_interest"
}'

Exemplo de resposta com opções de parcelamento disponíveis:

{
  "quote_id": "4a29251d-41af-41fc-ac74-fa131e215e1b",
  "amount": 100000,
  "currency": "BRL",
  "credits": [
    {
      "number_installments": 1,
      "installment_value": 100000,
      "total_amount": 100000,
      "schema": "no_interest",
      "type": "no_interest"
    },
    {
      "number_installments": 3,
      "installment_value": 33334,
      "total_amount": 100002,
      "schema": "no_interest",
      "type": "no_interest"
    },
    {
      "number_installments": 6,
      "installment_value": 16667,
      "total_amount": 100002,
      "schema": "no_interest",
      "type": "no_interest"
    }
  ]
}

Você precisará extrair as seguintes propriedades da resposta para usar na próxima etapa:

• quote_id - Identificador exclusivo para a cotação do parcelamento
• schema - Código que agrupa os créditos por categoria

Etapa 2: Criar o Pagamento com Parcelas

Assim que o cliente tiver selecionado a sua opção de parcelamento preferida, use o endpoint de Create - Authorize para processar o pagamento.

A API da Getnet espera receber os detalhes do parcelamento dentro do objeto additional_data. Se o objeto installment estiver incluído, o pagamento será feito de acordo com o número de parcelas previamente definido; caso contrário, o pagamento será feito em uma única parcela.

Requisitos específicos do país: Alguns mercados podem exigir campos obrigatórios adicionais. No Uruguai, você deve incluir um array rates e fornecer um regional_regulation_code. O regional_regulation_code é um array em que cada entrada tem um code e um invoice. O invoice aceita até 9 caracteres alfanuméricos. Recomendamos usar apenas números. Revise a referência de Taxes and Regulations para obter mais informações.

A tabela abaixo lista os campos mínimos que você precisa enviar:

Os objetos necessários para a validação antifraude devem incluir os seguintes campos:

Dados do antifraude são obrigatórios para ambientes de produção. Transações sem o fingerprint do dispositivo ou informações do cliente serão automaticamente bloqueadas pelas equipes de antifraude para prevenir fraudes. Consulte a documentação de Antifraude para obter os detalhes completos da implementação.

O bloco de código a seguir mostra um exemplo de solicitação de pagamento com parcelas:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer ' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "request_id": "daac03dc-73db-453f-9bea-b1391669d5d3",
  "order_id": "ORDER-10187383",
  "data": {
    "amount": 100000,
    "currency": "BRL",
    "customer_id": "test",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "12345678900",
      "phone_number": "+5511999999999",
      "billing_address": {
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Apto 101",
        "district": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR",
        "postal_code": "01310-100"
      }
    },
    "payment": {
      "payment_method": "CREDIT",
      "save_card_data": false,
      "transaction_type": "INSTALL_NO_INTEREST",
      "number_installments": 3,
      "soft_descriptor": "LOJA*TESTE*COMPRA-123",
      "dynamic_mcc": 1799,
      "card": {
        "number": "5155901222260000",
        "expiration_month": "09",
        "expiration_year": "30",
        "cardholder_name": "Card Holder",
        "security_code": "517"
      }
    },
    "additional_data": {
      "installment": {
        "schema": "no_interest",
        "type": "no_interest",
        "quote_id": "4a29251d-41af-41fc-ac74-fa131e215e1b"
      },
      "device": {
        "ip_address": "192.168.1.1",
        "device_id": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
        "finger_print": "1a2b3c4d5e6f7g8h9i0j"
      }
    }
  }
}'

Exemplo de resposta com status como APPROVED:

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "seller_id": "e0ed6f00-fdc5-46d6-9557-6a2cac641b09",
  "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75",
  "order_id": "ORDER-10187383",
  "amount": 100000,
  "currency": "BRL",
  "status": "APPROVED",
  "payment_method": "CREDIT",
  "received_at": "2025-10-31T13:40:47.382Z",
  "transaction_id": "MCC50205G1020",
  "original_transaction_id": "MCC50205G1020",
  "authorized_at": "2025-10-31T13:40:47.382Z",
  "reason_code": "00",
  "reason_message": "captured",
  "acquirer": "GETNET",
  "soft_descriptor": "LOJA*TESTE*COMPRA-123",
  "brand": "MASTERCARD",
  "authorization_code": "204050",
  "acquirer_transaction_id": "405030304060404030501060",
  "installments": {
    "number_installments": 3,
    "installment_value": 33334,
    "total_amount": 100002
  }
}

Etapa 3: Verificar o Status do Pagamento (Opcional)

A resposta do Create - Authorize mostrará o status como APPROVED para pagamentos parcelados bem-sucedidos.

Como alguns pagamentos são processados de forma assíncrona, o status pode mudar com o tempo. Para obter o status mais recente de uma transação, use o endpoint de Get Transaction.

Para atualizações em tempo real sem a necessidade de polling, é recomendável usar Webhooks para receber notificações de cada mudança de status.

Requisitos de Parcelamento Específicos do País

Cada mercado possui opções de parcelamento, tipos de plano e requisitos de implementação específicos. Para informações detalhadas sobre regras de parcelamento, planos disponíveis por bandeira de cartão e requisitos específicos de cada país (incluindo valores de campo obrigatórios para o objeto installment), consulte as Regras e Disponibilidade de Parcelamentos.

Próximos Passos

Agora que você criou com sucesso um pagamento com parcelas, você pode explorar mais recursos da Global API da Getnet:

• Aprenda a criar Pagamentos Combinados.
• Leia sobre Pagamentos com 3DS.
• Explore Pagamentos Pré-autorizados.