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

# Criando Links via API

> Aprenda a criar links de pagamento via API.

## Criando uma sessão

Para criar um link de pagamento, basta criar uma sessão com todas as configurações necessárias. Em seguida, será gerado automaticamente um paymentLink, retornado tanto na resposta de criação quanto na rota de detalhes do link. Essa URL é o endereço onde o ambiente de pagamento ficará disponível para o cliente.

Para mais informações sobre os parâmetros e configurações disponíveis, consulte a especificação da [API](/api-reference/sessions/criar-nova-sessao.mdx).

<Tip>
  Você pode configurar o `paymentLink` para que ele tenha o seu domínio alterando o `companyUrl` na API de configurações do Link. Saiba mais [**aqui**](/documentations/payment-link/set-up-custom-theme-link).
</Tip>

## Campos principais

Na criação da sessão, os campos abaixo controlam o comportamento do Link de Pagamento

| Campo              | Uso                                                                                                                                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`           | Valor cobrado em cada pagamento do link.                                                                                                                                                                                           |
| `paymentMethods`   | Métodos de pagamento disponíveis para o comprador.                                                                                                                                                                                 |
| `paymentLink`      | URL retornada pela API para compartilhar o link com o comprador.                                                                                                                                                                   |
| `maxPayments`      | Define se o link opera como 1:1 ou 1:N. Quando omitido, o link segue o fluxo 1:1. Quando enviado com um número positivo, limita a quantidade de pagamentos. Quando enviado como `-1`, permite pagamentos sem limite de quantidade. |
| `multiplePayments` | Objeto retornado nas respostas completas de sessão para indicar disponibilidade agregada, quantidade de pagamentos e status do link 1:N.                                                                                           |

<Warning>
  Quando `maxPayments` for maior que 1, apenas Cartão de Crédito pode ser configurado em `paymentMethods`.

  Pix pode ser usado em links sem limite (`maxPayments: -1`), mas Boleto não está disponível em nenhuma configuração de múltiplos pagamentos.

  Links com Pix ou Boleto que atingirem o limite configurado não podem ser reativados por quantidade — a tentativa é bloqueada via API e Dashboard. Reativação por expiração de data não é afetada.
</Warning>

## Criando um link de pagamento único (1:1)

Quando maxPayments é omitido, o link aceita apenas um pagamento. Após o primeiro pagamento bem-sucedido, o link é encerrado automaticamente.

<CodeGroup>
  ```bash Request theme={null}
  curl --location '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 '{
     "amount": 1000,
     "name": "Loja 1",
     "merchantId": "<YOUR_MERCHANT_ID>",
     "dueDate": "2030-10-25T09:28:45.000Z",
     "statementDescriptor": "<YOUR_STATEMENT_DESCRIPTOR>",
     "paymentMethods": [
        {
           "paymentType": "credit",
           "installments": 10
        },
        {
           "paymentType": "pix",
           "expiresIn": 10000
        },
        {
           "paymentType": "boleto",
           "expiresDate": "2026-01-01",
           "instructions": "Não receber após o vencimento. Multa de 2% e juros de 1% ao mês."
        }
     ],
     "items": [
        {
           "name": "Fone de Ouvido Bluetooth TWS-X1",
           "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.",
           "unitPrice": 35000,
           "quantity": 1,
           "tangible": false
        },
        {
           "name": "Caneca \"Code & Coffee\"",
           "description": "Caneca de cerâmica para café, com estampa personalizada.",
           "unitPrice": 4500,
           "quantity": 1,
           "tangible": false
        }
     ]
  }'
  ```

  ```json Response theme={null}
  {
      "id": "1a349417-5f01-45b1-8b49-977af564ff0b",
      "name": "Loja 1",
      "status": "created",
      "isActive": true,
      "clientId": "YOUR_CLIENT_ID",
      "orderId": null,
      "amount": 1000,
      "currency": "BRL",
      "capture": null,
      "merchantId": "YOUR_MERCHANT_ID",
      "dueDate": "2030-10-25T09:28:45.000Z",
      "description": null,
      "statementDescriptor": "YOUR_STATEMENT_DESCRIPTOR",
      "items": [
          {
              "id": "5f9c9d1e-1c17-4c65-9e0e-1a4a1a2b3c4d",
              "name": "Fone de Ouvido Bluetooth TWS-X1",
              "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.",
              "unitPrice": 35000,
              "quantity": 1,
              "tangible": false,
              "categoryId": null
          },
          {
              "id": "b1a9e0d7-2f4c-4d31-9f82-7c1b0e3d5a12",
              "name": "Caneca \"Code & Coffee\"",
              "description": "Caneca de cerâmica para café, com estampa personalizada.",
              "unitPrice": 4500,
              "quantity": 1,
              "tangible": false,
              "categoryId": null
          },
      ],
      "paymentLink": "https://link.malga.io/1a349417-5f01-45b1-8b49-977af564ff0b",
      "paymentMethods": [
          {
              "paymentType": "pix",
              "expiresIn": 10000
          },
          {
              "paymentType": "credit",
              "installments": 10,
              "recurrence": null
          },
          {
              "paymentType": "boleto",
              "expiresDate": "2026-01-01T00:00:00.000Z",
              "instructions": null
          }
      ],
      "createdAt": "2025-11-24T09:18:01.000Z",
      "updatedAt": "2025-11-24T09:18:01.000Z",
      "publicKey": "522cc99e-6ae3-45d2-9cc3-a8ebc4e8cbc3"
  }
  ```
</CodeGroup>

## Criando um link com múltiplos pagamentos (1:N)

Quando `maxPayments` é enviado com um número positivo, o link aceita até aquela quantidade de pagamentos. Quando enviado como `-1`, o link aceita pagamentos sem limite de quantidade, até a data de expiração definida em `dueDate`.

<Warning title="Pix e boleto não suportam limite finito em 1:N">
  Links 1:N com limite finito (`maxPayments > 1`) só aceitam **cartão de
  crédito**. Se `paymentMethods` incluir `pix` ou `boleto` junto de
  `maxPayments` finito maior que `1`, a API retorna `422` com `businessCode:
      "pix_boleto_multiple_payments_not_allowed"`. Para links com pix ou boleto,
  use `maxPayments` omitido (1:1), `1` ou `-1` (ilimitado).

  A mesma restrição vale na atualização (`PATCH /v1/sessions/{id}` com
  `isActive: true`): elevar `maxPayments` para um valor finito `> 1` em um link
  pix ou boleto retorna `422` com `businessCode:
      "pix_boleto_multiple_payments_not_allowed"`. Reativar um link pix/boleto 1:1
  já pago também é bloqueado com `422` e `businessCode:
      "pix_boleto_one_to_one_reactivation_blocked"`.
</Warning>

<CodeGroup>
  ```bash Request theme={null}
  curl --location '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 '{
     "amount": 1000,
     "name": "Loja 1",
     "merchantId": "<YOUR_MERCHANT_ID>",
     "dueDate": "2030-10-25T09:28:45.000Z",
     "statementDescriptor": "<YOUR_STATEMENT_DESCRIPTOR>",
     "paymentMethods": [
        {
           "paymentType": "credit",
           "installments": 10
        },
        {
           "paymentType": "pix",
           "expiresIn": 10000
        }
     ],
     "maxPayments": -1,
     "items": [
        {
           "name": "Fone de Ouvido Bluetooth TWS-X1",
           "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.",
           "unitPrice": 35000,
           "quantity": 1,
           "tangible": false
        },
        {
           "name": "Caneca \"Code & Coffee\"",
           "description": "Caneca de cerâmica para café, com estampa personalizada.",
           "unitPrice": 4500,
           "quantity": 1,
           "tangible": false
        },
        {
           "name": "Kit de Anotações \"Inspire\"",
           "description": "1 caderno A5 pautado (capa dura), 1 bloco de notas adesivas e 2 canetas esferográficas.",
           "unitPrice": 8990,
           "quantity": 1,
           "tangible": false
        }
     ]
  }'
  ```

  ```json Response theme={null}
  {
      "id": "1a349417-5f01-45b1-8b49-977af564ff0b",
      "name": "Loja 1",
      "status": "created",
      "isActive": true,
      "clientId": "YOUR_CLIENT_ID",
      "orderId": null,
      "amount": 1000,
      "currency": "BRL",
      "capture": null,
      "merchantId": "YOUR_MERCHANT_ID",
      "dueDate": "2030-10-25T09:28:45.000Z",
      "description": null,
      "statementDescriptor": "YOUR_STATEMENT_DESCRIPTOR",
      "items": [
          {
              "id": "5f9c9d1e-1c17-4c65-9e0e-1a4a1a2b3c4d",
              "name": "Fone de Ouvido Bluetooth TWS-X1",
              "description": "Fone sem fio com cancelamento de ruído ativo, case de carregamento e 8h de bateria. Cor: Preto Fosco.",
              "unitPrice": 35000,
              "quantity": 1,
              "tangible": false,
              "categoryId": null
          },
          {
              "id": "b1a9e0d7-2f4c-4d31-9f82-7c1b0e3d5a12",
              "name": "Caneca \"Code & Coffee\"",
              "description": "Caneca de cerâmica para café, com estampa personalizada.",
              "unitPrice": 4500,
              "quantity": 1,
              "tangible": false,
              "categoryId": null
          },
          {
              "id": "c8d3e0a1-9b6f-4a25-8e73-42d1f6b2c9e0",
              "name": "Kit de Anotações \"Inspire\"",
              "description": "1 caderno A5 pautado (capa dura), 1 bloco de notas adesivas e 2 canetas esferográficas.",
              "unitPrice": 8990,
              "quantity": 1,
              "tangible": false,
              "categoryId": null
          }
      ],
      "paymentLink": "https://link.malga.io/1a349417-5f01-45b1-8b49-977af564ff0b",
      "paymentMethods": [
          {
              "paymentType": "pix",
              "expiresIn": 10000
          },
          {
              "paymentType": "credit",
              "installments": 10,
              "recurrence": null
          },
          {
              "paymentType": "boleto",
              "expiresDate": "2026-01-01T00:00:00.000Z",
              "instructions": null
          }
      ],
      "multiplePayments": {
          "allow": true,
          "maxPayments": 36,
          "paymentCount": 0,
          "pendingCount": 0,
          "status": "active"
      },
      "createdAt": "2025-11-24T09:18:01.000Z",
      "updatedAt": "2025-11-24T09:18:01.000Z",
      "publicKey": "522cc99e-6ae3-45d2-9cc3-a8ebc4e8cbc3"
  }
  ```
</CodeGroup>

<Info>
  O valor cobrado em cada pagamento é o **amount** da sessão, não a soma dos valores dos items. Os itens são exibidos no checkout apenas como descrição da compra.
</Info>

## Pagando uma sessão

Para pagar um Link de Pagamento, você deve utilizar o endpoint de pagamento de uma sessão. Você pode ler mais detalhes na [**especificação da API**](/api-reference/sessions/pagar-uma-sessao).

Veja o contrato completo na [especificação de pagamento de sessão](/api-reference/sessions/pagar-uma-sessao).

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

## Acompanhando os pagamentos

Após cada pagamento, consulte a sessão para verificar o estado agregado do link. O objeto `multiplePayments` retorna a contagem atualizada de pagamentos realizados e o status atual do link.

Veja o contrato completo na [especificação de consulta de sessão](/api-reference/sessions/recuperar-detalhes-de-uma-sessao).

<Info>
  Deseja utilizar um de nossos serviços como autenticação 3DS2 ou usar o split nos pagamentos de seus links? Consulte as documentações completas:

  * [3DS2](/documentations/payment-link/3ds2)
  * [Split](/documentations/payment-link/split)
</Info>


## Related topics

- [Criando Links via Dashboard](/documentations/payment-link/create-link-using-dashboard.md)
- [3DS2 Agnóstico no Link de Pagamento](/documentations/payment-link/3ds2.md)
- [Webhooks v1.1](/documentations/webhooks/webhook1-1.md)
- [Introdução](/documentations/payment-link/intro.md)