> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga.
> Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima.
> Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação.
> Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência".
> Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas.
> Sandbox é ambiente de testes e não afeta produção.

# Múltiplos cartões

> Cobre um pedido em 2 ou 3 cartões de crédito em uma única Venda (purchase), com captura automática ou explícita, cancelamento e estorno pela API da Malga.

Com múltiplos cartões, você cobra um mesmo pedido em 2 ou 3 cartões de crédito em uma única operação. A cobrança é representada por uma **Venda** (`purchase`), que reúne o valor total e o valor de cada cartão.

A Malga realiza o papel de hub de pagamentos, porém não realiza a liquidação financeira. Você envia os dados da Venda para o [serviço de Purchases](/api-reference/purchases/criar-nova-venda) e a Malga processa a cobrança de cada cartão com os adquirentes e PSPs.

## Regras da Venda

* A Venda tem de 2 a 3 cartões em `payments`.
* Todos os cartões são de crédito (`paymentType: credit`) e a moeda é `BRL`.
* O valor total (`amount`) deve ser igual à soma dos valores dos cartões. O mínimo é de 200 centavos para a Venda e de 100 centavos para cada cartão.
* Cada cartão é informado por referência, com `cardId` (cartão salvo) ou `tokenId` (token de cartão). Dados de cartão em claro são recusados com `pan_not_allowed`.
* Cada cartão define o próprio número de parcelas em `paymentMethod.installments`.
* A Malga processa os cartões na ordem em que eles aparecem em `payments`, a partir do `slotIndex` 0.

## Fluxo de pagamento

* Crie a Venda em [`POST /v1/purchases`](/api-reference/purchases/criar-nova-venda), enviando o header `X-Idempotency-Key`. A resposta `202` traz `status: pending`, porque o processamento é assíncrono.
* Consulte a Venda em [`GET /v1/purchases/{id}`](/api-reference/purchases/recuperar-detalhes-de-uma-venda) até ela chegar a `paid`, `failed` ou `cancelled`.
* Acompanhe os marcos da Venda em [`GET /v1/purchases/{id}/history`](/api-reference/purchases/recuperar-o-historico-da-venda).

## Pagamento de um link ou de uma Session

Para cobrar por um link de pagamento ou por uma Session, crie a Session com um item `paymentType: "multiple"` em `paymentMethods`. A configuração está em [Criar link de pagamento via API](/documentations/payment-link/create-link-using-api). Depois, pague a Session em [`POST /v1/sessions/{id}/purchase`](/api-reference/sessions/pagar-uma-sessao-com-multiplos-cartoes).

O valor, o merchant, a moeda, o modo de captura e as regras de split vêm da Session. Você informa apenas os cartões em `payments`, de 2 até o `quantity` configurado, e cada cartão respeita o limite de `installments` da Session. A chamada cria uma Venda e segue o mesmo fluxo descrito nesta página.

<Note>
  Uma Session com múltiplos cartões não aceita `paymentType: multiple` em `POST /v1/sessions/{id}/charge`. Use sempre o endpoint `/purchase`.
</Note>

## Captura

O campo `capture` da criação define o que acontece depois das autorizações:

| `capture` | Comportamento |
| - | - |
| `true` | A Malga captura automaticamente os cartões pré-autorizados. Se todos os cartões já estiverem `authorized`, a Venda vai direto para `paid`. |
| `false` | A Venda permanece `pending` com os cartões `pre_authorized`. Você captura em [`POST /v1/purchases/{id}/capture`](/api-reference/purchases/capturar-venda-pre-autorizada), quando quiser. |

<Note>
  A captura explícita só vale para Vendas criadas com `capture: false`. Em uma Venda criada com `capture: true`, a rota de captura devolve `409` com `purchase_invalid_state`.
</Note>

## Status da Venda

| Status | Descrição |
| - | - |
| **pending** | Venda em processamento ou com cartões pré-autorizados aguardando captura |
| **paid** | Venda paga |
| **failed** | Venda não concluída. Consulte `payments[].declineReason` para identificar o motivo |
| **cancelled** | Pré-autorizações da Venda canceladas |

Cada cartão da Venda também tem um status próprio em `payments[].status`: `pending`, `processing`, `undetermined`, `pre_authorized`, `authorized`, `failed`, `voided`, `canceled` ou `charged_back`. O status `authorized` indica cartão capturado.

<Warning>
  Se uma Venda `pending` trouxer o campo `pendingReview`, interrompa o polling automático. O campo indica uma anomalia no processamento (`reconciliation_failed`, `amount_mismatch` ou `claims_exhausted`) e a Venda permanece `pending`.
</Warning>

## Exemplo de cobrança

O exemplo a seguir cria uma Venda de R\$ 150,00 em dois cartões, com captura automática.

```bash cURL theme={null}
curl --request POST 'https://api.malga.io/v1/purchases' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'X-Idempotency-Key: checkout-pedido-1001-attempt-1' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 15000,
    "currency": "BRL",
    "capture": true,
    "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8",
    "orderId": "pedido-1001",
    "payments": [
      {
        "amount": 10000,
        "paymentMethod": { "paymentType": "credit", "installments": 1 },
        "paymentSource": {
          "sourceType": "card",
          "cardId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "cardCvv": "123"
        }
      },
      {
        "amount": 5000,
        "paymentMethod": { "paymentType": "credit", "installments": 3 },
        "paymentSource": {
          "sourceType": "token",
          "tokenId": "9f8e7d6c-5b4a-3928-1706-5e4d3c2b1a09"
        }
      }
    ]
  }'
```

A resposta `202` traz a Venda com `status: pending` e a operação `authorize` em andamento:

```json Resposta 202 theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8",
  "amount": 15000,
  "currency": "BRL",
  "capture": true,
  "status": "pending",
  "orderId": "pedido-1001",
  "payments": [
    {
      "slotIndex": 0,
      "amount": 10000,
      "paymentMethod": { "paymentType": "credit", "installments": 1 },
      "status": "pending",
      "refundedAmount": 0,
      "paymentSource": {
        "sourceType": "card",
        "cardId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
      }
    },
    {
      "slotIndex": 1,
      "amount": 5000,
      "paymentMethod": { "paymentType": "credit", "installments": 3 },
      "status": "pending",
      "refundedAmount": 0,
      "paymentSource": {
        "sourceType": "token",
        "tokenId": "9f8e7d6c-5b4a-3928-1706-5e4d3c2b1a09"
      }
    }
  ],
  "operation": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "authorize",
    "status": "pending"
  },
  "createdAt": "2026-07-27T18:00:00Z",
  "updatedAt": "2026-07-27T18:00:00Z"
}
```

## Notificações por webhook

Em vez de consultar a Venda continuamente, você pode receber os eventos `purchase.*` no seu endpoint: `purchase.created`, `purchase.charge_authorized`, `purchase.pre_authorized`, `purchase.paid`, `purchase.failed`, `purchase.cancelled` e `purchase.void_failed`.

Cadastre o webhook na versão 1.1. Uma versão anterior não recebe eventos de Venda. Use a notificação como gatilho e confirme o estado em `GET /v1/purchases/{id}` antes de liberar o pedido. O formato de cada evento está em [Webhooks v1.1](/documentations/webhooks/webhook1-1#purchase).

## Idempotência

O header `X-Idempotency-Key` é obrigatório na criação, na captura e no cancelamento de uma Venda.

* Reenviar a mesma chave com o mesmo corpo devolve `202` com o estado atual da Venda.
* Reenviar a mesma chave com um corpo diferente, ou com uma chave já usada em outra operação, devolve `409` com `idempotency_key_payload_mismatch`.

## Cancelamento e estorno

Use [`POST /v1/purchases/{id}/void`](/api-reference/purchases/cancelar-ou-estornar-venda) para desfazer uma Venda, com o campo opcional `intent`:

* `cancel`: cancela as pré-autorizações de uma Venda `pending`. A Venda termina `cancelled`.
* `refund`: estorna o valor integral de uma Venda `paid`. A Venda permanece `paid`.

Envie `intent` explicitamente para garantir que um cancelamento nunca vire estorno, caso a Venda seja capturada entre a sua leitura e a chamada.

## Split

A Venda aceita `splitRules` no nível raiz, informado uma única vez para o pedido. A resposta devolve a parcela correspondente a cada cartão em `payments[].splitRules`.


## Related topics

- [Cartão de crédito](/documentations/payment-methods/credit-card.md)
- [Criar uma Venda com múltiplos cartões](/api-reference/purchases/criar-nova-venda.md)
- [Pagar uma sessão com múltiplos cartões](/api-reference/sessions/pagar-uma-sessao-com-multiplos-cartoes.md)
- [Recuperar detalhes de uma Venda](/api-reference/purchases/recuperar-detalhes-de-uma-venda.md)
- [Webhooks v1.1](/documentations/webhooks/webhook1-1.md)
- [Autentique-se com a Malga](/documentations/welcome/authentication.md)