Cash In

Criar Transação PIX

POST/v1/transactions

Cria uma nova transação de pagamento via PIX. Retorna o payload do QR Code para ser apresentado ao cliente.

Definição do Body

Interface TypeScripttypescript

interface CreateTransactionRequest {
  external_id?: string;        // Sua referência interna (opcional)
  total_amount: number;        // Valor em BRL (ex: 100.50)
  payment_method: "PIX";       // Apenas PIX disponível
  webhook_url?: string;        // URL para receber atualizações de status
  items: TransactionItem[];    // Itens da transação
  ip?: string;                 // IP do cliente (opcional)
  customer: Customer;          // Dados do cliente
}

interface TransactionItem {
  id: string;
  title: string;
  description?: string;
  price: number;
  quantity: number;
  is_physical: boolean;        // true = produto físico, false = digital
}

interface Customer {
  name: string;
  email: string;
  phone: string;
  document_type: "CPF" | "CNPJ";
  document: string;            // Apenas dígitos
  utm_source?: string;         // Origem do tráfego (ex: facebook, google)
  utm_medium?: string;         // Mídia (ex: cpc, organic, email)
  utm_campaign?: string;       // Nome da campanha
  utm_content?: string;        // Identificação do anúncio/criativo
  utm_term?: string;           // Termo/palavra-chave
  click_id?: string;           // ID do clique (ex: fbclid, gclid)
  click_type?: string;         // Tipo do clique (ex: fbclid, gclid)
}

Parâmetros Principais

Campo	Tipo	Descrição
`external_id`	`string`	Sua referência interna para a transação. Use para cruzar com seus próprios registros.
`total_amount`obrigatório	`number`	Valor total da transação em BRL (ex: 100.50). Deve ser positivo.
`payment_method`obrigatório	`"PIX"`	Método de pagamento. Atualmente apenas PIX é suportado.
`webhook_url`	`string`	URL que receberá notificações POST quando o status da transação mudar.
`items`obrigatório	`TransactionItem[]`	Array com os itens da transação.
`ip`	`string`	Endereço IP do cliente.
`customer`obrigatório	`Customer`	Dados completos do cliente pagador.

TransactionItem

Campo	Tipo	Descrição
`id`obrigatório	`string`	Identificador do item
`title`obrigatório	`string`	Nome do produto ou serviço
`description`	`string`	Descrição adicional do item
`price`obrigatório	`number`	Preço unitário em BRL
`quantity`obrigatório	`number`	Quantidade
`is_physical`obrigatório	`boolean`	true para produto físico, false para digital/serviço

Customer

Campo	Tipo	Descrição
`name`obrigatório	`string`	Nome completo do cliente
`email`obrigatório	`string`	Email do cliente
`phone`obrigatório	`string`	Telefone do cliente (apenas dígitos)
`document_type`obrigatório	`"CPF" \| "CNPJ"`	Tipo do documento
`document`obrigatório	`string`	Número do documento (apenas dígitos)
`utm_source`	`string`	Origem do tráfego que gerou a conversão (ex: facebook, google)
`utm_medium`	`string`	Mídia utilizada (ex: cpc, organic, email)
`utm_campaign`	`string`	Nome da campanha de marketing
`utm_content`	`string`	Identificação do anúncio ou criativo específico
`utm_term`	`string`	Termo ou palavra-chave associada ao clique
`click_id`	`string`	Identificador único do clique (ex: fbclid, gclid)
`click_type`	`string`	Tipo/origem do identificador de clique (ex: fbclid, gclid)

Como usar o payload PIX

O campo pix.payload contém o código PIX (copia e cola) que deve ser apresentado ao cliente para pagamento. Use este valor para gerar um QR Code ou permitir que o cliente copie diretamente.

Erros Possíveis

400Parâmetros obrigatórios ausentes ou com formato inválido

401API Secret ausente ou inválido

500Erro interno ao processar a transação

POSThttps://api.genesys.finance/v1/transactions

Headers

api-secret: seu_api_secret_aqui
Content-Type: application/json

Request Body (JSON)

{
  "external_id": "pedido_12345",
  "total_amount": 100.50,
  "payment_method": "PIX",
  "webhook_url": "https://sua-api.com/webhooks/transactions",
  "items": [
    {
      "id": "item_001",
      "title": "Assinatura Premium",
      "price": 100.50,
      "quantity": 1,
      "is_physical": false
    }
  ],
  "customer": {
    "name": "João Silva",
    "email": "joao.silva@exemplo.com",
    "phone": "11999999999",
    "document_type": "CPF",
    "document": "12345678901",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "utm_campaign": "black_friday",
    "utm_content": "anuncio_01",
    "utm_term": "tenis_corrida",
    "click_id": "abc123xyz",
    "click_type": "fbclid"
  }
}

cURL

curl -X POST "https://api.genesys.finance/v1/transactions" \
  -H "api-secret: seu_api_secret_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "total_amount": 100.50,
    "payment_method": "PIX",
    "customer": {
      "name": "João Silva",
      "email": "joao@exemplo.com",
      "phone": "11999999999",
      "document_type": "CPF",
      "document": "12345678901",
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "black_friday",
      "utm_content": "anuncio_01",
      "utm_term": "tenis_corrida",
      "click_id": "abc123xyz",
      "click_type": "fbclid"
    },
    "items": [
      {
        "id": "item_001",
        "title": "Assinatura Premium",
        "price": 100.50,
        "quantity": 1,
        "is_physical": false
      }
    ]
  }'

Response 200

{
  "id": "c22dc7e1-8b10-4580-9dc4-ebf78ceca475",
  "external_id": "pedido_12345",
  "status": "PENDING",
  "total_value": 100.50,
  "payment_method": "PIX",
  "pix": {
    "payload": "00020126580014br.gov.bcb.pix..."
  },
  "hasError": false
}