> ## 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.

# Sessões

> Use sessões para criar carrinhos, links de pagamento e fluxos com um ou múltiplos pagamentos.

O serviço de **Sessões** permite criar pedidos e links de pagamento processados pela Malga. Ele também pode ser combinado com o Malga Checkout para aumentar a segurança da implementação no front-end, usando uma `publicKey` de escopo restrito por sessão.

Existem dois modos principais:

* **Sessão 1:1 (legado):** quando `maxPayments` não é enviado na criação, a sessão segue o fluxo de um único pagamento.
* **Sessão 1:N:** quando `maxPayments` é enviado na criação, a sessão permite múltiplos pagamentos no mesmo link, com limite finito (`1` a `99999`) ou ilimitado (`-1`).

Você pode criar sessões com Pix, boleto, cartão de crédito e demais métodos aceitos pelo endpoint de criação. Para consultar o contrato completo, veja [Criar nova sessão](/api-reference/sessions/criar-nova-sessao).

## Utilizando as sessões

Para utilizar o serviço de Sessões, crie uma sessão definindo itens, valor, métodos de pagamento e, quando necessário, `maxPayments`. Depois, use a `publicKey` retornada na criação para chamar o endpoint de pagamento da sessão com uma chave de escopo restrito.

<Info title="Contexto do fluxo">
  O fluxo conceitual desta seção se aplica a sessões 1:1 e 1:N. Em sessões 1:N,
  cada chamada de pagamento aceita representa uma tentativa individual dentro da
  capacidade configurada em `maxPayments`.
</Info>

### Criando uma sessão

Realize a criação usando `POST /v1/sessions`. A resposta completa retorna a sessão, a `publicKey` de escopo restrito e, quando aplicável, o objeto `multiplePayments` com a disponibilidade agregada do link.

```bash theme={null}
curl --location --request POST 'https://api.malga.io/v1/sessions' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <YOUR_API_KEY>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "amount": 100,
        "name": "Pedido 1",
        "merchantId": "<YOUR_MERCHANT_ID>",
        "dueDate": "2026-02-20T23:59:59.000Z",
        "createLink": true,
        "maxPayments": 5,
        "paymentMethods": [
            {
                "paymentType": "pix",
                "expiresIn": 30
            }
        ],
        "items": [
            {
                "name": "Item",
                "description": "Item do carrinho",
                "unitPrice": 1000,
                "quantity": 1,
                "tangible": false
            }
        ]
    }'

< HTTP/2 200
{
  "id": "c1db83fa-723c-4e1f-9722-bc19d1be6791",
  "name": "Pedido 1",
  "status": "created",
  "isActive": true,
  "clientId": "39d2d314-5412-431a-b34b-74f9f0fbe7e1",
  "orderId": null,
  "amount": 100,
  "currency": "BRL",
  "capture": true,
  "merchantId": "<YOUR_MERCHANT_ID>",
  "dueDate": "2026-02-20T23:59:59.000Z",
  "description": null,
  "statementDescriptor": null,
  "items": [
    {
      "name": "Item 1",
      "description": "Item do carrinho",
      "unitPrice": 1000,
      "quantity": 1,
      "tangible": false
    }
  ],
  "paymentMethods": [
    {
      "paymentType": "pix",
      "expiresIn": 30
    }
  ],
  "paymentLink": "https://link.malga.io/c1db83fa-723c-4e1f-9722-bc19d1be6791",
  "multiplePayments": {
    "allow": true,
    "maxPayments": 5,
    "paymentCount": 0,
    "pendingCount": 0,
    "status": "active"
  },
  "createdAt": "2026-02-20T09:28:45.000Z",
  "updatedAt": "2026-02-20T09:28:45.000Z",
  "publicKey": "8be71cdf-01dc-4b1a-823a-4c58be6e4cf1"
}
```

Veja todos os campos aceitos em [Criar nova sessão](/api-reference/sessions/criar-nova-sessao).

### Pagando uma sessão

Pague uma sessão usando `POST /v1/sessions/{id}/charge`. Use a `publicKey` retornada na criação da sessão no cabeçalho `X-Api-Key`.

Em sessões 1:N, a resposta deste endpoint representa a cobrança criada para uma tentativa de pagamento. Para acompanhar a disponibilidade agregada do link após o pagamento, consulte [Recuperar detalhes de uma sessão](/api-reference/sessions/recuperar-detalhes-de-uma-sessao).

```bash theme={null}
curl --location --request POST 'https://api.malga.io/v1/sessions/{id}/charge' \
    --header 'X-Client-Id: <YOUR_CLIENT_ID>' \
    --header 'X-Api-Key: <PUBLIC_KEY_DA_SESSÃO>' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "paymentMethod": {
            "paymentType": "credit",
            "installments": 1
        },
        "paymentSource": {
            "sourceType": "card",
            "card": {
                "cardNumber": "5261424250184574",
                "cardCvv": "321",
                "cardExpirationDate": "06/2028",
                "cardHolderName": "JOAO DA SILVA"
            }
        }
    }'

< HTTP/2 201
{
   "id": "148d5db0-f1c3-439f-902d-f1f268086e1d",
   "status": "pending",
   "clientId": "39d2d314-5412-431a-b34b-74f9f0fbe7e1",
   "orderId": "b84b7694-d22f-4083-bee7-c1274b16eb4a",
   "customerId": "eb70b146-85fd-4100-8fd4-a4dbb647aed3",
   "amount": 100,
   "originalAmount": 100,
   "currency": "BRL",
   "capture": true,
   "merchantId": "9930c8d9-a7a8-4039-9faf-3715ad87baf8",
   "statementDescriptor": "LOJA JOAO",
   "paymentMethod": {
      "paymentType": "credit",
      "installments": 1
   },
   "paymentSource": {
      "sourceType": "card",
      "cardId": "148d5db0-f1c3-439f-902d-f1f268086e1d"
   },
   "transactionRequests": [
      {
         "id": "78601913-a176-4d71-b7e8-abb6fc49a340",
         "idempotencyKey": "fafe857b176e45d6b12e32fcaf228996",
         "providerId": "2c3b57d8-ee43-4b19-bc8a-949a88c51df1",
         "providerType": "STRIPE",
         "transactionId": "ch_3JYE7MHjGFBGEeiP0lfTD3Ob",
         "amount": 100,
         "authorizationNsu": "1cc8391c-f0d5-4b7a-9fcf-653cea26be13",
         "requestStatus": "success",
         "requestType": "authorization",
         "responseTs": "2633ms",
         "createdAt": "2021-08-12T16:08:39.536Z",
         "updatedAt": "2021-08-12T16:08:42.212Z",
         "providerAuthorization": {
            "networkAuthorizationCode": "00",
            "networkResponseCode": ""
         }
      }
   ],
   "createdAt": "2022-10-25T22:49:06.588Z"
}
```

Veja todos os campos aceitos em [Pagar uma sessão](/api-reference/sessions/pagar-uma-sessao).

## Fluxo 1:N e acompanhamento de status

Em sessões 1:N, o status agregado do link não deve ser inferido apenas pela resposta de uma cobrança individual. Acompanhe a sessão completa por `GET /v1/sessions/{id}` e use o histórico apenas como trilha de eventos.

| Campo                           | Como interpretar                                                                  |
| ------------------------------- | --------------------------------------------------------------------------------- |
| `multiplePayments.allow`        | Indica se a sessão foi criada como 1:N.                                           |
| `multiplePayments.maxPayments`  | Indica o limite configurado. `-1` significa ilimitado e `null` indica sessão 1:1. |
| `multiplePayments.paymentCount` | Quantidade de pagamentos já autorizados no link.                                  |
| `multiplePayments.pendingCount` | Quantidade de pagamentos pendentes de confirmação assíncrona, como Pix em aberto. |
| `multiplePayments.status`       | Disponibilidade conceitual do link para receber uma próxima cobrança.             |

<Info title="Estado agregado x cobrança individual">
  Um pagamento individual não encerra necessariamente uma sessão 1:N. Consulte
  [Recuperar detalhes de uma
  sessão](/api-reference/sessions/recuperar-detalhes-de-uma-sessao) para obter o
  estado agregado atualizado e [Recuperar o histórico da
  sessão](/api-reference/sessions/recuperar-o-historico-da-sessao) para auditar
  eventos.
</Info>

## Integrando o MalgaCheckout com sessões

Para utilizar o Malga Checkout com o serviço de Sessões de uma maneira mais segura, crie uma sessão pelo seu back-end e use a `publicKey` de escopo restrito na aplicação front-end. Assim, você configura o checkout sem expor a `publicKey` de escopo mais amplo usada normalmente.

<Info title="Contexto do fluxo com checkout">
  O fluxo com Malga Checkout vale para sessões 1:1 e 1:N. Em sessões 1:N, a
  mesma sessão pode continuar disponível após uma tentativa aprovada, conforme o
  limite configurado em `maxPayments` e o estado retornado em
  `multiplePayments`.
</Info>

### Usando o MalgaCheckout com sessões

Depois de criar a sessão, use o `id` dela e a `publicKey` retornada para configurar o Malga Checkout. Para manter a integração segura, recomendamos que o front-end tenha acesso apenas à chave pública da sessão.

```html theme={null}
<html lang="pt-BR">
  <head>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0"
    />
    <script
      type="module"
      src="https://unpkg.com/@malga-checkout/core@latest/dist/malga-checkout/malga-checkout.esm.js"
    ></script>
    <title>Malga Checkout Components</title>
  </head>
  <body>
    <main>
      <malga-checkout
        sandbox="false"
        public-key="<PUBLIC_KEY_DA_SESSÃO>"
        client-id="<YOUR_CLIENT_ID>"
        session-id="<ID_DA_SESSÃO>"
      >
      </malga-checkout>
    </main>

    <script>
      const malgaCheckout = document.querySelector("malga-checkout");

      malgaCheckout.addEventListener("paymentSuccess", (data) => {
        // Suas especificações aqui
      });

      malgaCheckout.addEventListener("paymentFailed", (error) => {
        // Suas especificações aqui
      });
    </script>
  </body>
</html>
```