Sessões

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.

Pix e boleto não são aceitos em links 1:N com limite finito maior que 1. Ao criar uma sessão com paymentMethods contendo pix ou boleto e maxPayments finito > 1, a API responde 422 com businessCode: "pix_boleto_multiple_payments_not_allowed". Para pix/boleto, use maxPayments omitido, 1 ou -1 (ilimitado). Cartão de crédito continua aceito em qualquer valor de maxPayments suportado.A mesma restrição vale na atualização (PATCH /v1/sessions/{id} com isActive: true): elevar maxPayments para um valor finito > 1 em uma sessão pix ou boleto retorna 422 com businessCode: "pix_boleto_multiple_payments_not_allowed". A reativação de uma sessão pix ou boleto 1:1 já paga também é bloqueada com 422 e businessCode: "pix_boleto_one_to_one_reactivation_blocked".

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.

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.

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.

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.

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.

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.

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.

Um pagamento individual não encerra necessariamente uma sessão 1:N. Consulte Recuperar detalhes de uma sessão para obter o estado agregado atualizado e Recuperar o histórico da sessão para auditar eventos.

Histórico da sessão

O endpoint GET /v1/sessions/{id}/history expõe a trilha de auditoria da sessão, com os eventos mais recentes primeiro: criação, alterações de campos, tentativas de pagamento, confirmações assíncronas (Pix e boleto) e expirações por dueDate ou limite 1:N. Cada item da resposta traz action, actions e um objeto diff com o detalhe da mudança. O campo status em cada linha segue a semântica de produto — expirações automáticas podem aparecer como disabled, enquanto cancelamento manual permanece canceled.

Não use o histórico como fonte do estado atual do link. Para multiplePayments e contadores atualizados, use GET /v1/sessions/{id}.

Consulte Recuperar o histórico da sessão para o catálogo completo de ações, exemplos de diff e diagrama do fluxo.

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.

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.

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

Comece na Malga

Conexões

Guias

Serviços adicionais

Utilizando as sessões

Criando uma sessão

Pagando uma sessão

Fluxo 1:N e acompanhamento de status

Histórico da sessão

Integrando o MalgaCheckout com sessões

Usando o MalgaCheckout com sessões

​Utilizando as sessões

​Criando uma sessão

​Pagando uma sessão

​Fluxo 1:N e acompanhamento de status

​Histórico da sessão

​Integrando o MalgaCheckout com sessões

​Usando o MalgaCheckout com sessões

Utilizando as sessões

Criando uma sessão

Pagando uma sessão

Fluxo 1:N e acompanhamento de status

Histórico da sessão

Integrando o MalgaCheckout com sessões

Usando o MalgaCheckout com sessões