Criando Links 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.

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.

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.

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

Criando uma sessão

Campos principais

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

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

Pagando uma sessão

Acompanhando os pagamentos

​Criando uma sessão

​Campos principais

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

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

​Pagando uma sessão

​Acompanhando os pagamentos

Criando uma sessão

Campos principais

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

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

Pagando uma sessão

Acompanhando os pagamentos