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)
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	Informações do produto para rastreamento (UTMify)
↳ name	Não	String	Nome do produto
offer	Não	Object	Vincula a transação a uma oferta cadastrada na ÁureaPag, habilitando automações
↳ slug	Não	String	Slug da oferta cadastrada no painel. Quando informado, a transação é vinculada à oferta real e automações são disparadas normalmente.
↳ name	Não	String	Nome da oferta. Usado quando `slug` não é informado.
↳ quantity	Não	Number	Quantidade (1–100, inteiro). Padrão: `1`
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.
splits	Não	Array	Lista de splits para distribuição automática do valor líquido. Ver Splits.
↳ email	Sim	String	E-mail cadastrado na ÁureaPag do vendedor que receberá o split
↳ percentage_bps	Sim	Number	Percentual em basis points (1–9000). Ex.: `2000` = 20%. A soma de todos os splits não pode ultrapassar 90% do valor líquido.
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

Sobre o campo offer.slug: o slug está disponível no painel da ÁureaPag, na página de cada oferta. Informá-lo vincula a transação à oferta real do seu catálogo, o que é necessário para que automações de venda sejam disparadas corretamente.

Exemplo de request (PIX)

{
  "external_id": "uuuid7364239uhioubn",
  "payment_method": "pix",
  "amount": 3590,
  "buyer": {
    "name": "João Silva",
    "email": "joao@email.com",
    "document": "10233019111",
    "phone": "5561999134129"
  },
  "product": {
    "name": "Produto Exemplo"
  },
  "offer": {
    "slug": "makita"
  },
  "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
  }
}

Exemplo de request (PIX com splits)

{
  "external_id": "pedido-124",
  "payment_method": "pix",
  "amount": 10000,
  "buyer": {
    "name": "João Silva",
    "email": "joao@email.com"
  },
  "splits": [
    {
      "email": "parceiro@email.com",
      "percentage_bps": 2000
    }
  ]
}

O parceiro receberá 20% do valor líquido da transação. O restante fica com o vendedor principal. Ver detalhes em Splits.

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"
  }
}

404 Not Found – Oferta não encontrada

Quando offer.slug é informado mas não corresponde a nenhuma oferta cadastrada para o vendedor:

{
  "error": {
    "message": "offer_not_found",
    "detail": "Nenhuma oferta encontrada com o slug 'makita' para este seller."
  }
}

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