Solicitar Transação

Utilize este endpoint para criar transações para vendas de produtos físicos ou digitais.

Ambientes Disponíveis

Produção

https://api.unoip.com.br

Endpoint

• Método: POST
• Endpoint: /transaction
• Autenticação: Bearer token

Request Body

⚠️ Importante: Valores em Centavos

Todos os valores monetários (amount, unitPrice) devem ser enviados em centavos como números inteiros.

Exemplos:

• R$ 10,00 = 1000
• R$ 99,99 = 9999
• R$ 100,50 = 10050

NÃO use: 99.99, 10.00, valores negativos USE: 9999, 1000 (sempre inteiros)

Nome	Tipo	Obrigatório	Descrição	Validações
amount	number	Sim	Valor da transação (inteiro em centavos)	Deve ser inteiro em centavos; mínimo 1 (R$ 0,01) e máximo 10000000 (R$ 100.000,00)
paymentMethod	string (enum) - PIX	Sim	Método de pagamento	Deve ser um enum válido
webhookUrl	string (URL)	Não	URL HTTPS para receber notificações	Deve ser URL válida com https obrigatório; sem fragmento (#); host e TLD obrigatórios; query permitida
externalCode	string	Não	Seu código de referência	Deve ter entre 8 e 255 caracteres
idempotencyKey	string	Não	Identificador único para evitar duplicações	Deve ter entre 8 e 255 caracteres
customer	object	Não	Dados do cliente (ver Sub-Objeto Customer)
seller	object	Não	Dados do vendedor (ver Sub-Objeto Seller)
isInfoProduct	boolean (Default: true)	Não	Flag para produtos digitais ou físicos
address	object	Sim (se isInfoProduct for false)	Endereço do cliente (ver Sub-Objeto Address)
items	object[]	Não	Lista de produtos (ver Sub-Objeto Item)
metadata	object	Não	Metadados
pix	object	Sim (se paymentMethod for PIX)	Dados do PIX (ver Sub-Objeto Pix)

Sub-Objetos

Customer

Campo	Tipo	Obrigatório	Descrição	Validações
ip	string	Não	IP	Deve ser IPv4 ou IPv6 válido
name	string	Sim	Nome	Deve ser alphanumerico internacional
document	string	Sim	Documento	Deve ser CPF ou CNPJ válido
email	object	Sim	E-mail	Deve possuir formato de email válido
landline	object	Não	Telefone fixo	Deve possuir formato de telefone fixo válido
mobilePhone	object	Não	Telefone celular	Deve possuir formato de telefone celular válido
birthdate	object	Não	Data de aniversário	Deve ser ISO date string sem horário

Seller

Campo	Tipo	Obrigatório	Descrição	Validações
name	string	Sim	Nome	Deve ser alphanumerico internacional
document	string	Sim	Documento	Deve ser CPF ou CNPJ válido

Address

Campo	Tipo	Obrigatório	Descrição	Validações
zipCode	string	Sim	CEP do Brasil	Deve possuir formato de CEP válido
complement	string	Não	Informações adicionais	Deve ter entre 2 e 150 caracteres
number	string	Sim	Número da casa	Deve ter entre 1 e 10 caracteres de apenas inteiros
street	string	Sim	Nome da rua	Deve ter entre 2 e 200 caracteres
neighborhood	string	Sim	Nome do bairro	Deve ter entre 2 e 100 caracteres
city	string	Sim	Nome da cidade	Deve ter entre 2 e 100 caracteres
state	string	Sim	Nome ou Sigla do estado	Deve ter entre 2 e 50 caracteres
country	string	Sim	Nome do país	Deve ter entre 2 e 60 caracteres

Item

Campo	Tipo	Obrigatório	Descrição	Validações
title	string	Sim	Título	Deve ter entre 2 e 150 caracteres
description	string	Não	Informações adicionais	Deve ter entre 2 e 255 caracteres
unitPrice	number	Sim	Valor do item (inteiro em centavos)	Deve ser inteiro em centavos; mínimo 1 (R$ 0,01) e máximo 10000000 (R$ 100.000,00)
quantity	number (Default: 1)	Não	Quantidade deste item	Deve ser inteiro; mínimo 1; máximo 100

Pix

Campo	Tipo	Obrigatório	Descrição	Validações
expirationSeconds	number (Default: 1800 (30 minutes))	Não	Tempo para expiração do QRCode do PIX em segundos	Deve ser inteiro; mínimo 60; máximo 86400

Exemplo de Requisição

cURL

curl --request POST \
--url https://api.unoip.com.br/transaction \
--header 'Authorization: Bearer seu-token-jwt' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 500,
    "paymentMethod": "PIX",
    "webhookUrl": "https://sua-api.com/webhooks/transaction",
    "externalCode": "TRANSACTION-123",
    "idempotencyKey": "unique-key-12345",
    "customer": {
      "ip": "123.123.123.123",
      "name": "Customer",
      "document": "123.123.123-12",
      "email": "customer@gmail.com",
      "landline": "(12) 12345-1234",
      "mobilePhone": "(12) 12345-1234"
    },
    "seller": {
      "name": "Seller",
      "document": "123.123.123-12"
    },
    "isInfoProduct": false,
    "address": {
      "zipCode": "54753-800",
      "number": "155",
      "street": "Rua Santa Mariana",
      "neighborhood": "São Pedro",
      "city": "Camaragibe",
      "state": "Pernambuco",
      "country": "Brazil",
      "complement": "Casa Azul"
    },
    "items": [
      {
        "title": "Fone Bluetooth PulseWave X200",
        "unitPrice": 500,
        "quantity": 1,
        "description": "Fone de ouvido sem fio com cancelamento ativo de ruído, bateria de 30h e microfone embutido. Compatível com Android e iOS."
      }
    ],
    "metadata": {
      "moeda": "BRL",
      "autorizacao": "A1B2C3",
      "status": "aprovada"
    },
    "pix": {
      "expirationSeconds": 600
    }
}'

JavaScript

const response = await fetch('https://api.unoip.com.br/transaction', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer seu-token-jwt',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 500,
    paymentMethod: 'PIX',
    webhookUrl: 'https://sua-api.com/webhooks/transaction',
    externalCode: 'TRANSACTION-123',
    idempotencyKey: 'unique-key-12345',
    customer: {
      ip: '123.123.123.123',
      name: 'Customer',
      document: '123.123.123-12',
      email: 'customer@gmail.com',
      landline: '(12) 12345-1234',
      mobilePhone: '(12) 12345-1234',
    },
    seller: {
      name: 'Seller',
      document: '123.123.123-12',
    },
    isInfoProduct: false,
    address: {
      zipCode: '54753-800',
      number: '155',
      street: 'Rua Santa Mariana',
      neighborhood: 'São Pedro',
      city: 'Camaragibe',
      state: 'Pernambuco',
      country: 'Brazil',
    },
    items: [
      {
        title: 'Fone Bluetooth PulseWave X200',
        unitPrice: 500,
        quantity: 1,
        description:
          'Fone de ouvido sem fio com cancelamento ativo de ruído, bateria de 30h e microfone embutido. Compatível com Android e iOS.',
      },
    ],
    metadata: {
      moeda: 'BRL',
      autorizacao: 'A1B2C3',
      status: 'aprovada',
    },
    pix: {
      expirationSeconds: 600,
    },
  })
});
const data = await response.json();

Resposta de Sucesso

Campo	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	Identificador único da transação
externalCode	string	Não	Seu código de referência
amount	number	Sim	Valor da transação (inteiro em centavos)
type	string (enum) - TRANSACTION	Sim
status	string (enum) - PIX_QRCODE_GENERATED	Sim	PIX_QRCODE_GENERATED: QRCode Gerado, aguardando pagamento
pixResponse	object	Sim (se paymentMethod for PIX)	Dados do PIX (ver Sub-Objeto PixResponse)

Sub-Objetos

PixResponse

Campo	Tipo	Obrigatório	Descrição
uri	string	Sim	Copia e cola do QRCode
qrCodeBase64	string	Sim	Imagem do QRCode
expirationDate	string	Sim	Data de expiração do QRCode

Exemplo de Resposta

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "externalCode": "TRANSACTION-123",
  "amount": 500,
  "status": "PIX_QRCODE_GENERATED",
  "pixResponse": {
    "uri": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expirationDate": "2026-03-06T12:49:04.681Z"
  }
}

Possíveis Erros

Código	Descrição	Solução
401	Credenciais inválidas	Verifique suas credenciais
403	Sem permissão/autorização	Contate o suporte
422	Dados inválidos ou faltando	Verifique o formato dos dados
422	Validações	Contate o suporte
429	Muitas requisições	Aguarde e tente novamente
500	Erro interno	Contate o suporte