curl --request POST \
  --url https://api.malga.io/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Client-Id: <api-key>' \
  --data '
{
  "amount": 100,
  "name": "Loja 1",
  "merchantId": "5bf7cbdf-02b7-489d-bc44-21ff1358d5fa",
  "dueDate": "2022-10-25T09:28:45.000Z",
  "createLink": true,
  "paymentMethods": [
    {
      "paymentType": "pix",
      "expiresIn": 30
    }
  ],
  "items": [
    {
      "name": "Item 1",
      "description": "Item do carrinho",
      "unitPrice": 1000,
      "quantity": 1,
      "tangible": false
    }
  ],
  "splitRules": [
    {
      "sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08",
      "percentage": 100,
      "processingFee": false,
      "chargeEntireFee": false,
      "chargeRemainderFee": false,
      "liable": true,
      "transactionOwner": true,
      "fares": {
        "mdr": 2.5,
        "fee": 30
      }
    }
  ]
}
'

{
  "id": "5bf7cbdf-02b7-489d-bc44-21ff1358d5fa",
  "name": "Nome da sessão",
  "status": "created",
  "isActive": true,
  "captchaEnabled": false,
  "clientId": "5bf7cbdf-02b7-489d-bc44-21ff1358d5fa",
  "orderId": null,
  "amount": 100,
  "currency": "BRL",
  "capture": true,
  "merchantId": "9b4f66f3-d45d-4946-b719-48f43fb90c52",
  "dueDate": "2022-10-25T09:28:45.000Z",
  "description": "Promoção Black Friday",
  "statementDescriptor": "LOJA JOAO",
  "paymentMethods": [
    {
      "paymentType": "credit",
      "installments": 1
    }
  ],
  "items": [
    {
      "id": "2405d3ad-886e-4541-bd2e-8489e6f54dd4",
      "name": "Item 1",
      "description": "Descrição do item",
      "unitPrice": 10000,
      "quantity": 1,
      "tangible": false
    }
  ],
  "createdAt": "2022-10-25T09:28:45.000Z",
  "updatedAt": "2022-10-25T09:28:45.000Z",
  "publicKey": "5bf7cbdf-02b7-489d-bc44-21ff1358d5fa",
  "multiplePayments": {
    "allow": false,
    "maxPayments": null,
    "paymentCount": 0,
    "pendingCount": 0,
    "status": "active"
  },
  "splitRules": [
    {
      "sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08",
      "percentage": 100,
      "processingFee": false,
      "chargeEntireFee": false,
      "chargeRemainderFee": false,
      "liable": true,
      "transactionOwner": true,
      "fares": {
        "mdr": 2.5,
        "fee": 30
      }
    }
  ]
}

Sessions

Criar nova sessão

Cria uma sessão de pagamento. Quando maxPayments é omitido, a sessão segue o fluxo 1:1 legado. Quando maxPayments é enviado, a sessão opera como link 1:N e a resposta completa retorna multiplePayments com a disponibilidade agregada para próximas cobranças.

Restrição pix/boleto em 1:N: métodos pix e boleto não podem ser combinados com maxPayments finito maior que 1. Nesse caso a API retorna 422 com businessCode: "pix_boleto_multiple_payments_not_allowed". maxPayments omitido, null, 1 ou -1 (ilimitado) continua permitido para pix/boleto. O bloqueio não se aplica a cartão de crédito.

POST

sessions

curl --request POST \
  --url https://api.malga.io/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Client-Id: <api-key>' \
  --data '
{
  "amount": 100,
  "name": "Loja 1",
  "merchantId": "5bf7cbdf-02b7-489d-bc44-21ff1358d5fa",
  "dueDate": "2022-10-25T09:28:45.000Z",
  "createLink": true,
  "paymentMethods": [
    {
      "paymentType": "pix",
      "expiresIn": 30
    }
  ],
  "items": [
    {
      "name": "Item 1",
      "description": "Item do carrinho",
      "unitPrice": 1000,
      "quantity": 1,
      "tangible": false
    }
  ],
  "splitRules": [
    {
      "sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08",
      "percentage": 100,
      "processingFee": false,
      "chargeEntireFee": false,
      "chargeRemainderFee": false,
      "liable": true,
      "transactionOwner": true,
      "fares": {
        "mdr": 2.5,
        "fee": 30
      }
    }
  ]
}
'

{
  "id": "5bf7cbdf-02b7-489d-bc44-21ff1358d5fa",
  "name": "Nome da sessão",
  "status": "created",
  "isActive": true,
  "captchaEnabled": false,
  "clientId": "5bf7cbdf-02b7-489d-bc44-21ff1358d5fa",
  "orderId": null,
  "amount": 100,
  "currency": "BRL",
  "capture": true,
  "merchantId": "9b4f66f3-d45d-4946-b719-48f43fb90c52",
  "dueDate": "2022-10-25T09:28:45.000Z",
  "description": "Promoção Black Friday",
  "statementDescriptor": "LOJA JOAO",
  "paymentMethods": [
    {
      "paymentType": "credit",
      "installments": 1
    }
  ],
  "items": [
    {
      "id": "2405d3ad-886e-4541-bd2e-8489e6f54dd4",
      "name": "Item 1",
      "description": "Descrição do item",
      "unitPrice": 10000,
      "quantity": 1,
      "tangible": false
    }
  ],
  "createdAt": "2022-10-25T09:28:45.000Z",
  "updatedAt": "2022-10-25T09:28:45.000Z",
  "publicKey": "5bf7cbdf-02b7-489d-bc44-21ff1358d5fa",
  "multiplePayments": {
    "allow": false,
    "maxPayments": null,
    "paymentCount": 0,
    "pendingCount": 0,
    "status": "active"
  },
  "splitRules": [
    {
      "sellerId": "d98106e8-568a-44c3-94d0-0e0bbd8b7e08",
      "percentage": 100,
      "processingFee": false,
      "chargeEntireFee": false,
      "chargeRemainderFee": false,
      "liable": true,
      "transactionOwner": true,
      "fares": {
        "mdr": 2.5,
        "fee": 30
      }
    }
  ]
}

Authorizations

X-Client-Id

string

header

required

X-Api-Key

string

header

required

Body

application/json

merchantId

string<uuid>

required

Identificação do merchant id a ser utilizado

paymentMethods

required

Métodos de pagamento disponíveis na sessão

Minimum array length: 1

Show child attributes

items

object[]

required

Itens do pedido

Minimum array length: 1

Show child attributes

orderId

string

Identificador único da cobrança do lado do cliente para conciliação futura

amount

integer

Valor da transação em centavos, exemplo 100 para cobrar R$ 1,00

Required range: x >= 0

currency

string

default:BRL

Identificador da moeda para processamento da cobrança, formato ISO 4217.

isActive

boolean

Determina se a sessão está ativa

capture

boolean

Determina se a transação deve ser capturada automaticamente

dueDate

string

Data limite da sessão, em ISO 8601 (com horário, ex.: 2026-01-17T20:00:00Z, ou apenas data, ex.: 2026-02-20). Opcional: quando omitido, a sessão não possui data de vencimento e não entra no job de expiração por dueDate. Quando informado, o dia calendário em America/Sao_Paulo deve ser no mínimo amanhã (a data de hoje e datas passadas são rejeitadas).

name

string

Nome que identifica a sessão

description

string

Descrição da sessão

statementDescriptor

string

Descrição a ser exibida fatura do comprador

Minimum string length: 3

createLink

boolean

Determina se a sessão terá um Link de Pagamento

captchaEnabled

boolean

Habilita verificação por CAPTCHA no Link de Pagamento da sessão.

maxPayments

Configura a sessão como link de múltiplos pagamentos (1:N). Aceita -1 (ilimitado) ou um valor inteiro entre 1 e 99999. 0, valores menores que -1 e valores acima de 99999 são inválidos. Quando omitido, a sessão é tratada como 1:1 (legado).

Restrição pix/boleto: quando paymentMethods contém pix e/ou boleto, maxPayments só é aceito como omitido, null, 1 ou -1 (ilimitado). Valores finitos maiores que 1 retornam 422 com businessCode: "pix_boleto_multiple_payments_not_allowed". Cartão de crédito continua aceito em qualquer valor de maxPayments suportado.

Available options:

-1

providerReferenceKey

string

Chave de referência da sessão no provedor

splitRules

object[]

Regras de split da sessão, persistidas para o pagamento. Não reenviar em POST /v1/sessions/{id}/charge.

Show child attributes

vendor

object

Parâmetros adicionais para transacionar com vendors

Show child attributes

Response

string

Identificação da sessão

name

string

Nome que identifica a sessão

status

enum<string>

Status da sessão

Available options:

created,

paid,

canceled,

voided

isActive

boolean

Determina se a sessão está ativa

clientId

string

Identificador do cliente na Malga

orderId

string

Identificador único da cobrança do lado do cliente para conciliação futura

amount

number

Valor da transação em centavos, exemplo 100 para cobrar R$ 1,00

currency

string

Identificador da moeda para processamento da cobrança, formato ISO 4217.

capture

boolean

Determina se a transação deve ser capturada automaticamente

merchantId

string

Identificação do merchant id a ser utilizado

dueDate

string | null

Data limite da sessão, em ISO 8601. Pode estar ausente (omitempty) quando a sessão foi criada sem data de vencimento.

description

string

Descrição da sessão

statementDescriptor

string

Descrição a ser exibida fatura do comprador

captchaEnabled

boolean

Indica se a sessão usa verificação por CAPTCHA no Link de Pagamento.

items

object[]

Itens do pedido

Show child attributes

paymentLink

string

Link para acessar o Link de Pagamento desta sessão

vendor

object

Parâmetros adicionais para transacionar com vendors

Show child attributes

paymentMethods

Métodos de pagamento disponíveis na sessão

Show child attributes

createdAt

string

Data de criação da sessão

updatedAt

string

Data da atualização da sessão

publicKey

string

Chave de acesso com escopo restrito, usada para pagar a sessão

providerReferenceKey

string

Chave de referência da sessão no provedor

splitRules

object[]

Regras de split persistidas nesta sessão (definidas na criação quando informadas).

Show child attributes

multiplePayments

object

Estado conceitual de disponibilidade do link para receber uma próxima cobrança. Retornado em respostas completas de sessão. Em respostas parciais de atualização ou pagamento, consulte GET /v1/sessions/{id} para obter o estado agregado atualizado.

Show child attributes

Visão Geral

Sub-keys

Cards

Tokens

3DS2 Malga

Charges

Sessions

Purchases

Subscriptions

Customers

Merchants

Providers

Vendors

Sellers

Payouts

Plans

Prepayment

Receipts

Flows

Webhooks

Settings

Criar nova sessão

Authorizations

Body

Response