Referência da API

Headers

Nome	Tipo	Obrigatório	Descrição
Authorization	string	✅	Token JWT no formato Bearer {token}
Content-Type	string	✅	Deve ser application/json

Criar Transação PIX (PIX IN)

Request Body

Campos Principais

Nome	Tipo	Obrigatório	Valor Padrão	Descrição
amount	number	✅	-	Valor da transação (inteiro em centavos)
paymentMethod	string (enum)	✅	-	Deve ser "PIX"
webhookUrl	string (URL)	❌	-	URL HTTPS para receber notificações
externalCode	string	❌	-	Seu código de referência
idempotencyKey	string	❌	-	Identificador único para evitar duplicações num curto período.
metadata	object	❌	-	Dados adicionais em formato JSON
isInfoProduct	boolean	❌	true	true para produto digital, false para físico
customer	object	❌	-	Dados do cliente
seller	object	❌	-	Dados do vendedor
address	object	❌	-	Dados do endereço do cliente
items	array	❌	-	Lista de produtos
pix	array	❌	object	Dados do PIX

Cliente (customer)

Nome	Tipo	Obrigatório	Descrição
ip	string	❌	IP do cliente (IPv4 ou IPv6)
name	string	✅	Nome completo
email	string	✅	E-mail válido
document	string	✅	CPF ou CNPJ
mobilePhone	string	❌	Celular (formato BR)
landline	string	❌	Telefone Fixo (formato BR)

Vendedor (seller)

Nome	Tipo	Obrigatório	Descrição
name	string	✅	Nome completo
document	string	✅	CPF ou CNPJ

Endereço (address)

Obrigatório quando isInfoProduct é false (para produtos físicos).

Nome	Tipo	Obrigatório	Descrição
zipCode	string	✅	CEP (formato BR)
street	string	✅	Logradouro
number	string	✅	Número
complement	string	❌	Complemento
neighborhood	string	✅	Bairro
city	string	✅	Cidade
state	string	✅	Estado
country	string	✅	País

Itens (items[])

Nome	Tipo	Obrigatório	Descrição
title	string	✅	Nome do produto
description	string	❌	Descrição detalhada
unitPrice	number	✅	Preço unitário (inteiro em centavos)
quantity	integer	✅	Quantidade

Configuração PIX (pix)

Nome	Tipo	Obrigatório	Valor Padrão	Descrição
expirationSeconds	integer	✅	1800	Tempo de expiração (60-86400)

Exemplo de Requisição

cURL

curl --location 'https://transaction.cartwave.com.br/transaction' \
--header 'Authorization: Bearer seu-token-jwt' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 1199,
    "paymentMethod": "PIX",
    "webhookUrl": "https://sua-api.com",
    "externalCode": "PEDIDO-123",
    "idempotencyKey": "PEDIDO-123",
    "customer": {
        "ip": "192.168.1.1",
        "name": "cliente",
        "email": "cliente@gmail.com",
        "document": "745.267.558-42",
        "landline": "(11) 3736-6847",
        "mobilePhone": "(11) 99321-4081",
    },
    "seller": {
        "name": "vendedor",
        "document": "914.636.318-12"
    },
    "isInfoProduct": false,
    "address": {
        "zipCode": "04177-110",
        "street": "Rua John Copley",
        "number": "654",
        "complement": "Apto 42",
        "neighborhood": "Parque Bristol",
        "city": "São Paulo",
        "state": "SP",
        "country": "Brasil"
    },
    "items": [
        {
            "title": "Produto Exemplo",
            "description": "Descrição detalhada do produto",
            "unitPrice": 1199,
            "quantity": 1
        }
    ],
    "metadata": {
        "origem": "app",
        "campanha": "black_friday"
    },
    "pix": {
        "expirationSeconds": 3600
    }
}'

JavaScript

const response = await fetch('https://transaction.cartwave.com.br/transaction', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer seu-token-jwt',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 1199,
    paymentMethod: 'PIX',
    // ... resto do payload
  })
});

Response

Campos de Resposta

Nome	Tipo	Descrição
id	string (UUID)	Identificador único da transação
externalCode	string	Seu código de referência
amount	number	Valor da transação (inteiro em centavos)
status	string (enum)	Status da transação
pix.uri	string	Código PIX copia e cola
pix.qrCodeBase64	string	QR Code em base64
pix.expirationDate	string (ISO 8601)	Data/hora de expiração

Status Possíveis

Status	Descrição
PENDING	Transação criada, em processamento
PIX_QRCODE_GENERATED	QR Code gerado, aguardando pagamento
PAID	Pagamento confirmado
INFRACTION	Estorno ou Infração do pagamento

Exemplo de Resposta

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "externalCode": "PEDIDO-123",
  "amount": 1199,
  "status": "PIX_QRCODE_GENERATED",
  "pix": {
    "uri": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expirationDate": "2025-10-31T14:18:03.090Z"
  }
}

Códigos de Erro

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

Validações Importantes

1. Documentos

   • CPF: 11 dígitos
   • CNPJ: 14 dígitos

2. Valores

   • Positivos
   • Inteiros
   • Em Centavos
   • Mínimo: configuração do tenant
   • Máximo: configuração do tenant

3. Webhook

   • URL HTTPS válida
   • Domínio público acessível
   • Resposta 2xx esperada

4. Endereço

   • CEP: 8 dígitos
   • Obrigatório para produtos físicos

5. PIX

   • Expiração: 60s a 86400s (24h)
   • QR Code único por transação

Solicitar Saque PIX (PIX OUT)

Request Body

Campos Principais

Nome	Tipo	Obrigatório	Descrição
amount	number	✅	Valor do saque (inteiro em centavos)
pixKey	string	✅	Chave PIX de destino
pixKeyType	string (enum)	✅	Tipo da chave: CPF, CNPJ, EMAIL, PHONE, EVP
webhookUrl	string (URL)	❌	URL HTTPS para receber notificações
externalCode	string	❌	Seu código de referência
idempotencyKey	string	❌	Identificador único para evitar duplicações

Exemplo de Requisição

cURL

curl --location 'https://transaction.cartwavehub.com.br/withdraw' \
--header 'Authorization: Bearer seu-token-jwt' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 10000,
    "pixKey": "12345678910",
    "pixKeyType": "CPF",
    "webhookUrl": "https://sua-api.com/webhooks/withdraw",
    "externalCode": "SAQUE-123",
    "idempotencyKey": "unique-key-12345"
}'

JavaScript

const response = await fetch('https://transaction.cartwavehub.com.br/withdraw', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer seu-token-jwt',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10000,
    pixKey: "12345678910",
    pixKeyType: "CPF",
    webhookUrl: "https://sua-api.com/webhooks/withdraw",
    externalCode: "SAQUE-123"
  })
});
const data = await response.json();

Resposta de Sucesso (201)

Campo	Tipo	Descrição
id	string (UUID)	Identificador único do saque
externalCode	string	Seu código de referência
amount	number	Valor do saque (inteiro em centavos)
status	string (enum)	Status do saque

Status Possíveis

Status	Descrição
PENDING	Saque criado, aguardando processamento
PROCESSING	Saque em processamento
COMPLETED	Saque processado com sucesso
FAILED	Erro no processamento
CANCELLED	Saque cancelado

Exemplo de Resposta

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "externalCode": "SAQUE-123",
  "amount": 10000,
  "status": "PENDING"
}

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 validações	Verifique o formato dos dados
429	Muitas requisições	Aguarde e tente novamente
500	Erro interno	Contate o suporte

Validações Importantes

1. Valores

   • Positivos
   • Inteiros
   • Em Centavos
   • Mínimo: R$ 1,00 (100 centavos)

2. Chaves PIX

   • CPF: 11 dígitos
   • CNPJ: 14 dígitos
   • EMAIL: formato válido
   • PHONE: formato brasileiro (+5511999999999)
   • EVP: UUID válido

3. Saldo

   • Verificação automática de saldo disponível
   • Taxas são deduzidas automaticamente

📚 Próximos Passos

PIX IN (Recebimentos)

1. Criar Transação PIX
2. Detalhes da Transação
3. Configurar Webhooks PIX IN

PIX OUT (Pagamentos)

1. Solicitar Saque PIX
2. Configurar Webhooks PIX OUT
3. Lista de Erros