# 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](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
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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dreference-combined-payments-and-availability).
## 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](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 para cada método de pagamento.
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 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: 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/combined-payments/post/dpm/payments-gwproxy/v2/payments/combined) 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:
| 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 total da transação em centavos (deve ser igual à soma de todos os pagamentos). | 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.payments[]` | Array de objetos de pagamento, cada um contendo os detalhes do método de pagamento. | Sim |
| `data.payments[].payment_method` | Deve ser `CREDIT` ou `DEBIT` para cada pagamento. | Sim |
| `data.payments[].transaction_type` | Define como a transação é processada (`FULL`, `INSTALL_NO_INTEREST`, `INSTALL_WITH_INTEREST`). | Sim |
| `data.payments[].number_installments` | Número de parcelas (use `1` para um único pagamento). | Sim |
| `data.payments[].amount` | Valor para este método de pagamento específico em centavos. | Sim |
| `data.payments[].card` | Conjunto de dados do cartão (`number`, `brand`, `expiration_month`, `expiration_year`, `security_code`, `cardholder_name`). | 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.
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:
```bash
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": "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"
}
},
"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`:
```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": 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](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.
### 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dcreate-payments-with-installments).
* Leia sobre [Pagamentos com 3DS](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-3ds-authentication-20).
* Explore a [Tokenização e Cofre](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dapi-ref-tokenization-and-vault) para armazenar com segurança os dados do cartão.