curl --request POST \
  --url https://api.malga.io/v1/purchases/{id}/void \
  --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 '{}'

{
  "id": "1c6381d1-9fcd-4e9a-a012-93cf0457dcb9",
  "merchantId": "6d5b0464-090b-480b-a4e9-e1a0fb60a495",
  "amount": 15000,
  "currency": "BRL",
  "capture": false,
  "status": "pending",
  "updatedAt": "2026-07-27T18:06:00Z",
  "payments": [
    {
      "slotIndex": 0,
      "amount": 10000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 1
      },
      "status": "pre_authorized",
      "refundedAmount": 0,
      "chargeId": "b1204633-999d-4cb2-9546-f9b3108b23df",
      "paymentSource": {
        "sourceType": "card",
        "cardId": "3fd63170-ffa4-4b33-9d45-c3ab8fe6ce61"
      },
      "card": {
        "brand": "Visa",
        "last4": "4242"
      }
    },
    {
      "slotIndex": 1,
      "amount": 5000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 1
      },
      "status": "pre_authorized",
      "refundedAmount": 0,
      "chargeId": "13cf9d05-e0d7-4927-ae24-f967258c210a",
      "paymentSource": {
        "sourceType": "token",
        "tokenId": "c9783dec-0900-401c-8946-58e1b626f85a"
      },
      "card": {
        "brand": "Mastercard",
        "last4": "4444"
      }
    }
  ],
  "createdAt": "2026-07-27T18:00:00Z",
  "operation": {
    "id": "404c624c-12f8-4b59-a9ad-ab918e68c51b",
    "type": "void",
    "status": "pending"
  }
}

Purchases

Cancelar ou estornar uma Venda

Rota única para desfazer uma Venda, com o campo opcional intent:

cancel: cancela as pré-autorizações de uma Venda pending com todos os cartões pre_authorized. Responde 202 com operation.type: void e a Venda termina cancelled.
refund: estorna o valor integral de uma Venda paid. Responde 202 com operation.type: refund e a Venda permanece paid.

Sem intent (corpo vazio, {} ou intent: ""), a Malga decide pelo estado da Venda: paid estorna e os demais estados cancelam, com as mesmas regras acima. Envie intent explicitamente para garantir que um cancelamento nunca vire estorno caso a Venda seja capturada entre a sua leitura e a chamada.

Campos extras no corpo (como amount) devolvem 400. Sem X-Idempotency-Key, ou com intent fora do enum, a API devolve 422 com invalid_request. Reenviar a mesma chave com o mesmo corpo devolve 202 com o estado atual da Venda.

Casos de 409:

idempotency_key_payload_mismatch: a chave já foi usada com outro corpo ou em outra operação.
purchase_operation_in_progress: já existe uma operação em andamento e você enviou uma chave nova.
purchase_intent_mismatch: cancel em Venda paid, ou refund em Venda com cartões apenas pré-autorizados. Nenhum valor é movimentado.
purchase_invalid_state: estado misto, Venda failed ou cancelled, ou sem saldo estornável.

POST

purchases

{id}

void

curl --request POST \
  --url https://api.malga.io/v1/purchases/{id}/void \
  --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 '{}'

{
  "id": "1c6381d1-9fcd-4e9a-a012-93cf0457dcb9",
  "merchantId": "6d5b0464-090b-480b-a4e9-e1a0fb60a495",
  "amount": 15000,
  "currency": "BRL",
  "capture": false,
  "status": "pending",
  "updatedAt": "2026-07-27T18:06:00Z",
  "payments": [
    {
      "slotIndex": 0,
      "amount": 10000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 1
      },
      "status": "pre_authorized",
      "refundedAmount": 0,
      "chargeId": "b1204633-999d-4cb2-9546-f9b3108b23df",
      "paymentSource": {
        "sourceType": "card",
        "cardId": "3fd63170-ffa4-4b33-9d45-c3ab8fe6ce61"
      },
      "card": {
        "brand": "Visa",
        "last4": "4242"
      }
    },
    {
      "slotIndex": 1,
      "amount": 5000,
      "paymentMethod": {
        "paymentType": "credit",
        "installments": 1
      },
      "status": "pre_authorized",
      "refundedAmount": 0,
      "chargeId": "13cf9d05-e0d7-4927-ae24-f967258c210a",
      "paymentSource": {
        "sourceType": "token",
        "tokenId": "c9783dec-0900-401c-8946-58e1b626f85a"
      },
      "card": {
        "brand": "Mastercard",
        "last4": "4444"
      }
    }
  ],
  "createdAt": "2026-07-27T18:00:00Z",
  "operation": {
    "id": "404c624c-12f8-4b59-a9ad-ab918e68c51b",
    "type": "void",
    "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 do cancelamento ou do estorno

Required string length: 1 - 255

Path Parameters

string<uuid>

required

Identificador da Venda

Body

application/json

Corpo opcional do cancelamento ou do estorno

intent

enum<string>

Intenção da chamada. Ausente ou vazia, a Malga decide pelo estado da Venda.

cancel: cancela as pré-autorizações de uma Venda pending. A Venda termina cancelled.
refund: estorna o valor integral de uma Venda paid. A Venda permanece paid.

Available options:

cancel,

refund

Response

Cancelamento ou estorno aceito. Numa repetição idempotente, a operação pode já estar processing

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

customerId

string<uuid>

Customer informado na criação. Omitido quando a Venda não tem customer

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

Sub-keys

Cards

Tokens

3DS2 Malga

Charges

Sessions

Purchases

Subscriptions

Customers

Merchants

Providers

Vendors

Sellers

Payouts

Plans

Prepayment

Receipts

Flows

Webhooks

Settings

Cancelar ou estornar uma Venda

Authorizations

Headers

Path Parameters

Body

Response