curl --request POST \
  --url https://api.malga.io/v1/purchases \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Client-Id: <api-key>' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "amount": 15000,
  "currency": "BRL",
  "capture": true,
  "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8",
  "orderId": "pedido-1001",
  "metadata": {
    "channel": "checkout"
  },
  "splitRules": [
    {
      "sellerId": "11111111-1111-1111-1111-111111111111",
      "percentage": 60,
      "processingFee": true,
      "liable": true
    },
    {
      "sellerId": "22222222-2222-2222-2222-222222222222",
      "percentage": 40,
      "processingFee": false,
      "liable": false
    }
  ],
  "payments": [
    {
      "amount": 10000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 1
      },
      "paymentSource": {
        "sourceType": "card",
        "cardId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "cardCvv": "123"
      }
    },
    {
      "amount": 5000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 3
      },
      "paymentSource": {
        "sourceType": "token",
        "tokenId": "9f8e7d6c-5b4a-3928-1706-5e4d3c2b1a09"
      }
    }
  ]
}
'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8",
  "amount": 15000,
  "currency": "BRL",
  "capture": true,
  "status": "pending",
  "orderId": "pedido-1001",
  "metadata": {
    "channel": "checkout"
  },
  "splitRules": [
    {
      "sellerId": "11111111-1111-1111-1111-111111111111",
      "percentage": 60,
      "processingFee": true,
      "liable": true
    },
    {
      "sellerId": "22222222-2222-2222-2222-222222222222",
      "percentage": 40,
      "processingFee": false,
      "liable": false
    }
  ],
  "payments": [
    {
      "slotIndex": 0,
      "amount": 10000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 1
      },
      "status": "pending",
      "refundedAmount": 0,
      "paymentSource": {
        "sourceType": "card",
        "cardId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
      },
      "splitRules": [
        {
          "sellerId": "11111111-1111-1111-1111-111111111111",
          "percentage": 60,
          "processingFee": true,
          "liable": true
        },
        {
          "sellerId": "22222222-2222-2222-2222-222222222222",
          "percentage": 40,
          "processingFee": false,
          "liable": false
        }
      ]
    },
    {
      "slotIndex": 1,
      "amount": 5000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 3
      },
      "status": "pending",
      "refundedAmount": 0,
      "paymentSource": {
        "sourceType": "token",
        "tokenId": "9f8e7d6c-5b4a-3928-1706-5e4d3c2b1a09"
      },
      "splitRules": [
        {
          "sellerId": "11111111-1111-1111-1111-111111111111",
          "percentage": 60,
          "processingFee": true,
          "liable": true
        },
        {
          "sellerId": "22222222-2222-2222-2222-222222222222",
          "percentage": 40,
          "processingFee": false,
          "liable": false
        }
      ]
    }
  ],
  "createdAt": "2026-07-27T18:00:00Z",
  "updatedAt": "2026-07-27T18:00:00Z",
  "operation": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "authorize",
    "status": "pending"
  }
}

Purchases

Criar uma Venda com múltiplos cartões

Cria uma Venda paga com 2 ou 3 cartões de crédito e responde 202 com status: pending. O processamento é assíncrono: consulte GET /v1/purchases/{id} para acompanhar o desfecho.

O campo capture define o que acontece depois das autorizações:

capture: false: a Venda permanece pending com os cartões pre_authorized. Você captura em POST /v1/purchases/{id}/capture.
capture: true: a Malga captura automaticamente os cartões pré-autorizados. Se todos os cartões já estiverem authorized, a Venda vai direto para paid.

Envie o header X-Idempotency-Key em toda criação. Reenviar a mesma chave com o mesmo corpo devolve 202 com o estado atual da Venda. A mesma chave com corpo diferente, ou uma chave já usada em captura ou cancelamento, devolve 409 com idempotency_key_payload_mismatch.

Informe cada cartão por referência, com cardId ou tokenId. Dados de cartão em claro (PAN) em paymentSource, metadata ou fraudAnalysis devolvem 422 com pan_not_allowed.

POST

purchases

curl --request POST \
  --url https://api.malga.io/v1/purchases \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Client-Id: <api-key>' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "amount": 15000,
  "currency": "BRL",
  "capture": true,
  "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8",
  "orderId": "pedido-1001",
  "metadata": {
    "channel": "checkout"
  },
  "splitRules": [
    {
      "sellerId": "11111111-1111-1111-1111-111111111111",
      "percentage": 60,
      "processingFee": true,
      "liable": true
    },
    {
      "sellerId": "22222222-2222-2222-2222-222222222222",
      "percentage": 40,
      "processingFee": false,
      "liable": false
    }
  ],
  "payments": [
    {
      "amount": 10000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 1
      },
      "paymentSource": {
        "sourceType": "card",
        "cardId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "cardCvv": "123"
      }
    },
    {
      "amount": 5000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 3
      },
      "paymentSource": {
        "sourceType": "token",
        "tokenId": "9f8e7d6c-5b4a-3928-1706-5e4d3c2b1a09"
      }
    }
  ]
}
'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchantId": "3b8c1f2a-4d5e-6f70-8192-a3b4c5d6e7f8",
  "amount": 15000,
  "currency": "BRL",
  "capture": true,
  "status": "pending",
  "orderId": "pedido-1001",
  "metadata": {
    "channel": "checkout"
  },
  "splitRules": [
    {
      "sellerId": "11111111-1111-1111-1111-111111111111",
      "percentage": 60,
      "processingFee": true,
      "liable": true
    },
    {
      "sellerId": "22222222-2222-2222-2222-222222222222",
      "percentage": 40,
      "processingFee": false,
      "liable": false
    }
  ],
  "payments": [
    {
      "slotIndex": 0,
      "amount": 10000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 1
      },
      "status": "pending",
      "refundedAmount": 0,
      "paymentSource": {
        "sourceType": "card",
        "cardId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
      },
      "splitRules": [
        {
          "sellerId": "11111111-1111-1111-1111-111111111111",
          "percentage": 60,
          "processingFee": true,
          "liable": true
        },
        {
          "sellerId": "22222222-2222-2222-2222-222222222222",
          "percentage": 40,
          "processingFee": false,
          "liable": false
        }
      ]
    },
    {
      "slotIndex": 1,
      "amount": 5000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 3
      },
      "status": "pending",
      "refundedAmount": 0,
      "paymentSource": {
        "sourceType": "token",
        "tokenId": "9f8e7d6c-5b4a-3928-1706-5e4d3c2b1a09"
      },
      "splitRules": [
        {
          "sellerId": "11111111-1111-1111-1111-111111111111",
          "percentage": 60,
          "processingFee": true,
          "liable": true
        },
        {
          "sellerId": "22222222-2222-2222-2222-222222222222",
          "percentage": 40,
          "processingFee": false,
          "liable": false
        }
      ]
    }
  ],
  "createdAt": "2026-07-27T18:00:00Z",
  "updatedAt": "2026-07-27T18:00:00Z",
  "operation": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "authorize",
    "status": "pending"
  }
}

Authorizations

X-Client-Id

string

header

required

X-Api-Key

string

header

required

Headers

X-Idempotency-Key

string

required

Chave de idempotência da criação. Ausente, a API devolve 422 com invalid_request

Required string length: 1 - 255

Body

application/json

Dados para criar uma Venda com 2 ou 3 cartões

amount

integer

required

Valor total em centavos. Deve ser igual à soma de payments[].amount

Required range: x >= 200

currency

enum<string>

required

Moeda da Venda. Somente BRL

Available options:

BRL

capture

boolean

required

Define o que acontece depois das autorizações. Vale para todos os cartões da Venda.

false: a Venda permanece pending com os cartões pre_authorized, até você chamar POST /v1/purchases/{id}/capture.
true: a Malga captura automaticamente os cartões pré-autorizados. Se todos já estiverem authorized, a Venda vai direto para paid.

merchantId

string<uuid>

required

Identificador do merchant da Venda

payments

object[]

required

Cartões da Venda, de 2 a 3

Required array length: 2 - 3 elements

Show child attributes

orderId

string

Identificador do pedido no seu sistema

sessionId

string<uuid>

Identificador de uma Session de origem, apenas para rastreio. Não cria vínculo com a Session e permite filtrar a listagem

metadata

object

Pares de chave e valor livres, devolvidos na resposta. Faz parte da comparação de idempotência. Dados de cartão em claro devolvem 422 com pan_not_allowed

splitRules

object[]

Regras de split da Venda. Cada cartão recebe a parcela correspondente em payments[].splitRules

Show child attributes

fraudAnalysis

object

Dados de antifraude da Venda, informados uma única vez. A Malga repete o objeto em cada cobrança da Venda. O campo faz parte da comparação de idempotência e nunca é retornado nas respostas, por conter dados pessoais do comprador. Dados de cartão em claro devolvem 422 com pan_not_allowed.

Show child attributes

Response

Venda aceita com status: pending, ou repetição idempotente (mesma chave e mesmo corpo) com o estado atual da Venda. Na primeira resposta, operation traz type: authorize e status: pending; na repetição, operation pode ser omitido. payments[].card aparece quando a Malga já conhece a bandeira e os últimos quatro dígitos do cartão. pendingReview não é retornado na criação.

Venda paga com 2 ou 3 cartões

string<uuid>

required

Identificador da Venda

merchantId

string<uuid>

required

Identificador do merchant da Venda

amount

integer

required

Valor total da Venda em centavos

Required range: x >= 200

currency

enum<string>

required

Available options:

BRL

capture

boolean

required

Indica o modo de captura informado na criação. false exige captura explícita; true captura automaticamente

status

enum<string>

required

Status da Venda

Available options:

pending,

paid,

failed,

cancelled

payments

object[]

required

Required array length: 2 - 3 elements

Show child attributes

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

pendingReview

object

Sinal de que a Venda precisa de revisão. A Venda permanece pending e você deve interromper o polling automático

Show child attributes

activeOperation

object

Operação pending ou processing em andamento na Venda (a mais recente). Omitido quando não há operação ativa. Nas respostas 202, a operação aceita vem em operation

Show child attributes

orderId

string | null

Identificador do pedido no seu sistema

sessionId

string<uuid> | null

Session de origem informada na criação

metadata

object

Metadados informados na criação. Omitido quando não enviados

splitRules

object[]

Regras de split informadas na criação. Omitido quando não enviadas

Show child attributes

operation

object

Operação assíncrona aceita por esta chamada. Na criação, vem com type: authorize e pode ser omitida numa repetição idempotente

Show child attributes

Visão Geral

Client-token

Cards

Tokens

3DS2 Malga

Charges

Sessions

Purchases

Subscriptions

Customers

Merchants

Providers

Vendors

Sellers

Payouts

Plans

Prepayment

Receipts

Flows

Webhooks

Settings

Criar uma Venda com múltiplos cartões

Authorizations

Headers

Body

Response