transactions

Cria uma nova transação. Suporta os métodos de pagamento pix, card e boleto.

Atenção: Enviar duas requisições com o mesmo external_id para o mesmo vendedor retorna 400 com transaction_already_exists. O external_id deve ser único por vendedor.

Headers

Nome	Obrigatório	Descrição
Authorization	Sim	`Bearer <token>` (token de 40 caracteres)
User-Agent	Sim	Valor fornecido pelo gerente de contas
Content-Type	Sim	`application/json`

Body (JSON)

Nome	Obrigatório	Tipo	Descrição
external_id	Sim	String	Identificador externo (1–255 caracteres; apenas letras, números, hífens e underscores)
payment_method	Sim	String	`"pix"`, `"card"` ou `"boleto"`
amount	Sim	Number	Valor em centavos. Mínimo: 600 (R$ 6,00). Máximo: 300000 (R$ 3.000,00). Inteiro.
buyer	Não	Object	Dados do comprador (recomendado para envio à UTMify)
↳ name	Sim*	String	Nome e sobrenome (3–100 caracteres; apenas letras, espaços, hífens, apóstrofos). *Obrigatório se buyer for enviado.
↳ email	Sim*	String	E-mail válido (máx. 100 caracteres). *Obrigatório se buyer for enviado.
↳ document	Não	String	CPF ou CNPJ, apenas números (11 ou 14 dígitos)
↳ phone	Não	String	Telefone apenas números, 12–13 caracteres (ex.: 55 + DDD + número)
product	Não	Object	Enviado para a UTMify. Deve ser enviado junto com offer, ou ambos omitidos.
↳ id	Sim	String	ID do produto
↳ name	Sim	String	Nome do produto
offer	Não	Object	Enviado para a UTMify. Deve ser enviado junto com product, ou ambos omitidos.
↳ id	Sim	String	ID da oferta
↳ name	Sim	String	Nome da oferta
↳ quantity	Sim	Number	Quantidade (1–100, inteiro)
tracking	Não	Object	Dados de rastreamento/UTM
↳ ref	Não	String \| null	Máx. 255 caracteres
↳ src	Não	String \| null	Máx. 255 caracteres
↳ sck	Não	String \| null	Máx. 255 caracteres
↳ utm_source	Não	String \| null	Máx. 255 caracteres
↳ utm_medium	Não	String \| null	Máx. 255 caracteres
↳ utm_campaign	Não	String \| null	Máx. 255 caracteres
↳ utm_id	Não	String \| null	Máx. 255 caracteres
↳ utm_term	Não	String \| null	Máx. 255 caracteres
↳ utm_content	Não	String \| null	Máx. 255 caracteres
postbackUrl	Não	String	URL válida para webhook de postback (máx. 500 caracteres). Se informada, um webhook é criado/atualizado para o evento transaction-processed.
card	Não	Object	Obrigatório quando payment_method é "card". Dados do cartão.
↳ number	Sim	String	16 dígitos, apenas números
↳ holderName	Sim	String	Nome no cartão (3–100 caracteres)
↳ expirationMonth	Sim	String	Mês 01–12 (2 dígitos)
↳ expirationYear	Sim	String	Ano (4 dígitos, válido)
↳ cvv	Sim	String	3 dígitos

Exemplo de request (PIX)

{
  "external_id": "pedido-123",
  "payment_method": "pix",
  "amount": 3590,
  "buyer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "12345678901",
    "phone": "5511123456789"
  },
  "product": {
    "id": "prod-1",
    "name": "Produto Exemplo"
  },
  "offer": {
    "id": "offer-1",
    "name": "Oferta 1",
    "quantity": 1
  },
  "tracking": {
    "ref": null,
    "src": null,
    "sck": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_id": null,
    "utm_term": null,
    "utm_content": null
  }
}

Resposta de sucesso (201 Created)

Para pix, a resposta inclui o código PIX e o QR Code em base64. Gerar um QR Code a partir de pix.code também funciona.

{
  "data": {
    "id": "390b5525-4629-4463-a32a-e0cd432d939b",
    "status": "pending",
    "payment_method": "pix",
    "pix": {
      "code": "00020126870014br.gov.bcb.pix...",
      "qrcode_base64": "iVBORw0KGgo..."
    },
    "total_amount": 3590,
    "net_amount": 3195.959,
    "created_at": "2025-05-24T17:45:19.084Z"
  }
}

Erros

400 Bad Request – Validação

Corpo quando há erro de validação nos campos:

{
  "error": {
    "message": "Invalid request body.",
    "detail": {
      "payment_method": ["O campo 'payment_method' é obrigatório."],
      "amount": ["O campo 'amount' precisa ser um número."]
    }
  }
}

400 Bad Request – external_id duplicado

Quando já existe uma transação com o mesmo external_id para o mesmo vendedor:

{
  "error": {
    "message": "transaction_already_exists",
    "detail": "Transaction with 'external_id' already exists"
  }
}

401 Unauthorized

Token ausente ou inválido. Ver Autenticação.

403 Forbidden

Conta do vendedor pendente ou rejeitada:

{
  "error": {
    "message": "account_status_blocked",
    "detail": "Não é possível realizar vendas enquanto sua conta estiver pendente ou rejeitada"
  }
}

500 Internal Server Error

Erro ao chamar a adquirente ou erro inesperado:

{
  "error": {
    "message": "Internal server error.",
    "detail": "Um erro inesperado ocorreu. Contate o suporte para mais informações."
  }
}

Criar transação