# 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/authentication). > A Getnet fornece uma [Postman Collection](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-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](https://www.google.com/search?q=/en/articles%3Farticle%3Dcurrency-codes) * [Tipos de documento](https://www.google.com/search?q=/en/articles%3Farticle%3Ddocument-types) * [Impostos e regulamentações locais](https://www.google.com/search?q=/en/articles%3Farticle%3Dtaxes-and-regulations) Você também pode usar [cartões de teste](https://www.google.com/search?q=/en/articles%3Farticle%3Dtest-cards) 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](https://www.google.com/search?q=/en/articles%3Farticle%3Dcurrency-codes) 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dreference-installments-rules-and-availability). ## 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. Você não precisa (e não pode) capturar manualmente cada parcela separadamente. O detalhamento das parcelas e o cronograma de liquidação são gerenciados automaticamente pela rede de cartões e pelo banco adquirente com base no tipo de plano selecionado. 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dreference-installments-rules-and-availability). ## 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: Este guia demonstra o fluxo de pagamento em etapa única (Authorize & Capture). No entanto, pagamentos parcelados também são totalmente suportados no fluxo de duas etapas (Pré-autorizado). Para usar o fluxo Pré-autorizado, siga as instruções no guia de [Pagamento Pré-autorizado](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dcreate-pre-authorized-payment), garantindo que você inclua os campos do objeto `installment` descritos abaixo em sua solicitação de autorização. ### 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/cards/post/dpm/cofre-gw-proxy/v1/tokens/card) 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. Se você enviar `card.number_token`, não precisará incluir a propriedade `card.number` na solicitação. Você pode usar o número do cartão no formato original (raw) ou a versão tokenizada, mas não ambos. Para detalhes completos sobre a tokenização, consulte a documentação de [Tokenização e Cofre](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-tokenization-and-vault). ### 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/installments/POST/dpm/payments-gwproxy/v2/payments/quotes). A API da Getnet espera receber os seguintes detalhes na solicitação: | Atributo | Descrição | Obrigatório | | ------------------------- | ------------------------------------------------------------------------------------------ | -------- | | `amount` | Valor total a ser pago (em centavos). | Sim | | `bin` | Primeiros 6 ou 9 dígitos do cartão (preferencialmente 9; no caso do Uruguai, são exigidos 16 dígitos). | Sim | | `installment_type_filter` | Propriedade opcional para filtrar resultados. Valores possíveis: `no_interest` ou `with_interest`. | Não | Dependendo dos requisitos do seu mercado, você pode enviar o `bin` (Bank Identification Number) do cartão ou, se você já tiver tokenizado o cartão, pode usar `number_token` em vez disso. Ambos fornecem as informações necessárias para a API retornar as opções de parcelamento disponíveis. O bloco de código a seguir mostra um exemplo de solicitação: ```bash 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: ```json { "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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/payments-gwproxy/v2/payments) 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](https://predocs.globalgetnet.com/en/articles?article=taxes-and-regulations) para obter mais informações. A tabela abaixo lista os campos mínimos que você precisa enviar: | Atributo | Descrição | Obrigatório | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------- | | `idempotency_key` | Identificador exclusivo para evitar cobranças duplicadas. | Sim | | `order_id` | ID de referência do lojista usado para conciliação. | Sim | | `request_id` | Identificador de rastreamento para auditorias de idempotência e acompanhamento de suporte. | Recomendado | | `data.amount` | Valor da transação em centavos. | Sim | | `data.currency` | Código da moeda ISO usado na transação. | Sim | | `data.customer` | Detalhes do cliente (nome, e-mail, telefone, documento, endereço de cobrança completo). **Obrigatório em produção para evitar bloqueios do antifraude.** | Sim (Prod) | | `data.payment.payment_method` | Deve ser `CREDIT` ou `DEBIT` para pagamentos parcelados. | Sim | | `data.payment.transaction_type` | Define como a transação é processada. Varia de acordo com o país (veja as seções específicas de cada país). | Sim | | `data.payment.number_installments` | Número de parcelas. | Sim | | `data.payment.card` | Conjunto de dados do cartão (`number`, `brand`, `expiration_month`, `expiration_year`, `security_code`, `cardholder_name`). | Sim | | `data.additional_data.installment` | Objeto de parcelamento contendo `schema`, `type`, e `quote_id` da Etapa 1. | Sim | | `data.additional_data.device` | Informações de fingerprint do dispositivo (`ip_address`, `device_id`, `finger_print`) para análise antifraude. | Sim (Prod) | Os objetos necessários para a validação antifraude devem incluir os seguintes campos: | Objeto / Campo | Descrição | | -------------------------------------- | -------------------------------------------------- | | `customer.first_name` | Primeiro nome do cliente | | `customer.last_name` | Sobrenome do cliente | | `customer.email` | Endereço de e-mail do cliente | | `customer.phone_number` | Número de telefone (formato internacional) | | `customer.document_type` | Tipo de documento (ex., CPF, DNI, etc.) | | `customer.document_number` | Número do documento (sem pontuação) | | `customer.billing_address.street` | Nome da rua | | `customer.billing_address.number` | Número do endereço | | `customer.billing_address.district` | Bairro | | `customer.billing_address.city` | Cidade | | `customer.billing_address.state` | Estado ou província | | `customer.billing_address.country` | Código do país (ISO) | | `customer.billing_address.postal_code` | Código postal ou CEP | | `additional_data.device.ip_address` | Endereço de IP do cliente | | `additional_data.device.device_id` | ID da sessão de fingerprint do dispositivo (UUIDv4) | | `additional_data.device.finger_print` | Hash de fingerprint gerado pelo script antifraude | > 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drisk-security-antifraud) 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: ```bash 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": "john.doe@example.com", "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`: ```json { "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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payment-record-management/get/dpm/hub-payment-info/v1/payments/info/%7Bpayment_id%7D). 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dreference-installments-rules-and-availability). ### 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dcreate-combined-payments). * Leia sobre [Pagamentos com 3DS](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-3ds-authentication-20). * Explore [Pagamentos Pré-autorizados](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dcreate-pre-authorized-payment).