Criando Links via API

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.

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.

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.

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.

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.

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
      }
   ]
}'

{
    "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"
}

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.

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

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
      }
   ]
}'

{
    "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"
}

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.

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"
        }
    }
}'

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.

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
Split

Comece na Malga

Conexões

Guias

Serviços adicionais

Criando Links via API

Campos principais

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

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

Processando um pagamento no link

Acompanhando os pagamentos

​Campos principais

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

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

​Processando um pagamento no link

​Acompanhando os pagamentos

Campos principais

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

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

Processando um pagamento no link

Acompanhando os pagamentos