Criar Pagamentos Combinados com Cartão

Este guia explica como processar transações de pagamento combinadas usando múltiplos métodos de pagamento em uma única compra. Pagamentos combinados permitem que os clientes dividam o valor total em vários cartões, sejam de crédito ou débito, proporcionando maior flexibilidade para compras maiores.

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

Pagamentos combinados são suportados em vários mercados. Para uma referência completa dos métodos de pagamento disponíveis em cada país, consulte a Disponibilidade de Pagamentos Combinados.

Processo de Pagamento Combinado

Esta seção guia você na criação de uma transação de pagamento combinado onde um cliente pode usar vários cartões para concluir uma única compra. O processo envolve a autorização de múltiplos métodos de pagamento simultaneamente e, opcionalmente, sua captura posterior.

O diagrama abaixo ilustra o fluxo completo do pagamento combinado, mostrando como múltiplos cartões são tokenizados e autorizados em uma única solicitação:

Tokenizar os Dados do Cartão (Opcional)

Em vez de enviar os números do cartão originais (raw) em 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 cartões tokenizados:

1. Tokenize cada 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 para cada método de pagamento.

Etapa 1: Autorizar o Pagamento Combinado

Um pagamento combinado começa com a criação de múltiplas autorizações de pagamento em uma única solicitação. Use o endpoint de Combined Payments - Authorize para processar vários métodos de pagamento simultaneamente.

A estrutura do pagamento combinado permite que você especifique um array de métodos de pagamento, cada um com seus próprios detalhes de cartão e valor. A soma de todos os valores de pagamento individuais deve ser igual ao valor total do pedido.

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.

Ao final de uma autorização bem-sucedida, você receberá um payment_id, que é usado para identificar esta transação.

O bloco de código a seguir mostra um exemplo de uma solicitação de pagamento combinado usando dois cartões diferentes:

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/combined \
  --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": 200000,
    "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"
      }
    },
    "payments": [
      {
        "payment_method": "CREDIT",
        "save_card_data": false,
        "transaction_type": "FULL",
        "number_installments": 1,
        "amount": 120000,
        "soft_descriptor": "LOJA*TESTE*COMPRA-123",
        "card": {
          "number": "5155901222260000",
          "expiration_month": "09",
          "expiration_year": "30",
          "cardholder_name": "Card Holder One",
          "security_code": "517"
        }
      },
      {
        "payment_method": "CREDIT",
        "save_card_data": false,
        "transaction_type": "FULL",
        "number_installments": 1,
        "amount": 80000,
        "soft_descriptor": "LOJA*TESTE*COMPRA-123",
        "card": {
          "number": "4012001037141112",
          "expiration_month": "12",
          "expiration_year": "30",
          "cardholder_name": "Card Holder Two",
          "security_code": "123"
        }
      }
    ],
    "additional_data": {
      "device": {
        "ip_address": "192.168.1.1",
        "device_id": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
        "finger_print": "1a2b3c4d5e6f7g8h9i0j"
      }
    }
  }
}'

Exemplo de resposta com todos os pagamentos 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": 200000,
  "currency": "BRL",
  "status": "APPROVED",
  "received_at": "2025-10-31T13:40:47.382Z",
  "payments": [
    {
      "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75-1",
      "amount": 120000,
      "status": "APPROVED",
      "payment_method": "CREDIT",
      "transaction_id": "MCC50205G1020",
      "authorized_at": "2025-10-31T13:40:47.382Z",
      "reason_code": "00",
      "reason_message": "captured",
      "brand": "MASTERCARD",
      "authorization_code": "204050"
    },
    {
      "payment_id": "053de7f9-3725-437b-bdfc-bbf3ed0acb75-2",
      "amount": 80000,
      "status": "APPROVED",
      "payment_method": "CREDIT",
      "transaction_id": "MCC50205G1021",
      "authorized_at": "2025-10-31T13:40:47.582Z",
      "reason_code": "00",
      "reason_message": "captured",
      "brand": "VISA",
      "authorization_code": "204051"
    }
  ]
}

Etapa 2: Verificar o Status do Pagamento (Opcional)

A resposta da autorização do pagamento combinado mostrará o status geral e o status individual de cada método de pagamento.

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.

Próximos Passos

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

• Aprenda a criar Pagamentos Parcelados.
• Leia sobre Pagamentos com 3DS.
• Explore a Tokenização e Cofre para armazenar com segurança os dados do cartão.