Skip to main content

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.

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.

​
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.
CampoComo interpretar
multiplePayments.allowIndica se a sessão foi criada como 1:N.
multiplePayments.maxPaymentsIndica o limite configurado. -1 significa ilimitado e null indica sessão 1:1.
multiplePayments.paymentCountQuantidade de pagamentos já autorizados no link.
multiplePayments.pendingCountQuantidade de pagamentos pendentes de confirmação assíncrona, como Pix em aberto.
multiplePayments.statusDisponibilidade 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.

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