> ## 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.
# Criando Links via API
> Aprenda a criar links de pagamento via API, com as funcionalidades disponíveis e como utilizar o serviço de Sessões para criar links de pagamento.
Para criar um Link de Pagamento via API, você deve criar uma sessão com `paymentLink`. A URL retornada na criação e na consulta da sessão é o endereço em que o ambiente de pagamento ficará disponível para você. Veja mais detalhes na [especificação de criação de sessão](/api-reference/sessions/criar-nova-sessao).
Para dividir valores entre recebedores neste fluxo, configure `splitRules` no
**corpo de criação da sessão**. O pagamento do link **não** recebe novo split
no corpo. Veja [Split em sessão ou link de
pagamento](/documentations/split/split-em-sessao-link).
## 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. |
## 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.
```bash Request theme={null}
curl --location 'https://api.malga.io/v1/sessions' \
--header 'X-Client-Id: ' \
--header 'X-Api-Key: ' \
--header 'Content-Type: application/json' \
--data '{
"amount": 1000,
"name": "Loja 1",
"merchantId": "",
"dueDate": "2030-10-25T09:28:45.000Z",
"statementDescriptor": "",
"paymentMethods": [
{
"paymentType": "credit",
"installments": 10
},
{
"paymentType": "pix",
"expiresIn": 10000
},
{
"paymentType": "boleto",
"expiresDate": "2026-01-01"
}
],
"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": [
{
"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
},
{
"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"
}
```
## 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`.
```bash Request theme={null}
curl --location 'https://api.malga.io/v1/sessions' \
--header 'X-Client-Id: ' \
--header 'X-Api-Key: ' \
--header 'Content-Type: application/json' \
--data '{
"amount": 1000,
"name": "Loja 1",
"merchantId": "",
"dueDate": "2030-10-25T09:28:45.000Z",
"statementDescriptor": "",
"paymentMethods": [
{
"paymentType": "credit",
"installments": 10
},
{
"paymentType": "pix",
"expiresIn": 10000
},
{
"paymentType": "boleto",
"expiresDate": "2026-01-01"
}
],
"maxPayments": 36,
"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": [
{
"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
},
{
"name": "Caneca \"Code & Coffee\"",
"description": "Caneca de cerâmica para café, com estampa personalizada.",
"unitPrice": 4500,
"quantity": 1,
"tangible": false,
"categoryId": null
},
{
"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"
}
```
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.
## Processando um pagamento no link
Para registrar um pagamento, use o endpoint de pagamento de sessão. Cada chamada aceita cria uma cobrança individual. Em links 1:N, as chamadas são aceitas até que o limite configurado em `maxPayments` seja atingido.
Veja o contrato completo na [especificação de pagamento de sessão](/api-reference/sessions/pagar-uma-sessao).
```bash Request theme={null}
curl --location 'https://api.malga.io/v1/sessions/{id}/charge' \
--header 'X-Client-Id: ' \
--header 'X-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"
}
}
}'
```
## 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).
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)