Criar transação
Referência API
Criar transação
Criar uma nova transação financeira para monitoramento e análise — na API de monitoramento de transações gu1 para fraude e AML, com exemplos para create.
POST
Criar transação
Visão geral
Cria uma nova transação. ComexecuteRules: true (padrão), o motor de regras roda de forma síncrona e a resposta inclui rulesExecutionSummary completo quando as regras terminam na mesma request.
Sem enviar asyncRules (padrão false), o comportamento permanece o mesmo — integrações existentes não mudam.
Endpoint
Autenticação
Requer uma API key válida no header Authorization:Parâmetros de query
boolean
default:"false"
Com
true e executeRules diferente de false, a transação é criada na hora e a avaliação de regras é enfileirada em background. A resposta HTTP retorna antes das regras terminarem. O query param tem precedência sobre o mesmo campo no body JSON.Valores truthy aceitos: true, 1, "true", "1", "yes".Não se aplica a endpoints batch — apenas POST /transactions (criação unitária).Corpo da requisição
Campos obrigatórios
string
required
Seu identificador único para esta transação no seu sistema
string
required
Tipo da transação. Opções:
PAYMENT- PagamentoTRANSFER- TransferênciaWITHDRAWAL- SaqueDEPOSIT- DepósitoREFUND- ReembolsoCHARGEBACK- ChargebackREVERSAL- EstornoFEE- TaxaADJUSTMENT- AjusteOTHER- Outro
number
required
Valor (deve ser zero ou positivo)
string
required
Código da moeda (3-4 caracteres, ex.: “USD”, “EUR”, “BRL”)
number
Taxa de câmbio opcional, usada somente quando a conversão automática para a moeda base da organização não está disponível (erro do provedor, timeout ou par não suportado). Se omitir este campo, o comportamento permanece o mesmo — o Gueno consulta o serviço de moedas como hoje.Semântica: unidades da moeda base por 1 unidade de
currency. Valor normalizado na moeda base da org: valorNormalizado = amount × exchangeRate.Ignorada quando a conversão automática tem sucesso (prevalece a taxa do provedor).Necessária quando a conversão automática não está disponível para moedas não conversíveis (ver abaixo). Ver Conversão de moeda.Campos opcionais
string
default:"CREATED"
Status. Opções:
CREATED, PROCESSING, SUSPENDED, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFULstring
Método de pagamento. Opções:
CARD, ACH, PIX, TED, BOLETO, WALLET, SWIFT, IBAN, CBU, CVU, DEBIN, GENERIC_BANK_ACCOUNT, MPESA, UPI, CHECK, ECHECK, CASH, QR_CODE, ONLINE_PAYMENT, WITHDRAWAL_ORDERstring
Descrição ou notas
string
Categoria da transação
string
Data/hora ISO 8601 do fato (padrão: momento da criação). Gravado em UTC. Use
Z ou offset ±HH:MM no string, ou datetime sem offset junto com timeZone (horário local nesse fuso).boolean
default:"true"
Se o motor de regras deve rodar. Com
false, pula regras por completo (sync e async).boolean
default:"false"
Mesma semântica do query
asyncRules. Para ingestão em alto volume: persistir a transação rápido e revisar alertas depois no gu1. Requer executeRules: true (padrão). Ignorado se executeRules for false.object
Ajuste opcional da execução de regras após a criação (sync ou async). Não desativa ações
createAlert nem a consolidação de investigações.Com
notifications: false, o gu1 não envia notificações in-app da avaliação de regras (matriz de risco / mudanças de status). Alertas e investigações seguem o fluxo normal.Legacy KYT POST /legacy/kyt/verifyTransaction: mesmo objeto no body Gu2 como configRulesExecution; se omitido, Paytime prod recebe notifications: false por padrão (igual a POST /transactions).boolean
default:"false"
Com
false (padrão): o Gu1 ainda auto-vincula quando há match. Se não, a TX ainda é criada (sem vínculo). Um UUID *EntityId inexistente é limpo (sem 404). Também ?linkEntityStrict=true.Com true: refs não resolvidas → 400 INVALID_ENTITY_REFERENCES e não cria.boolean
default:"false"
Alias legado de
linkEntityStrict: true. Prefira linkEntityStrict.Matrizes de risco (opcional)
string | string[]
Compatível com clientes antigos: um UUID ou um array de UUIDs de matrizes da organização. Se enviar lista não vazia, apenas regras ativas ligadas a essas matrizes são avaliadas (sem misturar com regras “soltas” só por triggers). Omita
riskMatrixId e riskMatrixIds para manter o comportamento histórico por triggers.string[]
Preferido para várias matrizes: lista ordenada de UUIDs. Tem precedência sobre
riskMatrixId quando informado e não vazio.Origem (entidade)
Como a origem é vinculada no gu1 (em ordem; para no primeiro sucesso):
(
- ID da entidade — com
originEntityId, a transação usa essa entidade (deve existir na org). - ID externo — sem
originEntityId, comoriginExternalId, se houver pessoa/empresa com o mesmoexternalId, a transação vincula automaticamente. - Terceiro fallback: documento / tax ID (raiz) — ainda sem vínculo, com
originTaxIdno raiz do corpo, o API procura pessoa/empresa cujotaxIdcoincida após normalizar (apenas letras e números, ignorando pontuação; comparação em maiúsculas no match).
originEntityId e, se você não enviou, pode preencher name e country a partir da entidade.Denormalização canônica (origem vinculada): quando a origem está vinculada a pessoa/empresa — você enviou originEntityId, ou o auto-link resolveu por originExternalId / originTaxId — o gu1 sincroniza as colunas denormalizadas a partir da entidade antes do insert:Se a entidade não tem
taxId ou externalId, a coluna correspondente na transação fica null, mesmo que você tenha enviado valores no body.Nota para integradores: você pode enviar qualquer combinação de identificadores para vincular (precedência: originEntityId → originExternalId → originTaxId). Após o vínculo, originTaxId / originExternalId persistidos refletem a entidade no gu1, não necessariamente o que digitou. Isso alinha regras transacionais com eventos de usuário.Sem match, a transação é criada mesmo assim, com os campos enviados, sem vínculo.(
originDetails.taxId ajuda no grafo mas não vincula entidade; use originTaxId na raiz para vincular por documento.)string
UUID da entidade de origem no gu1
string
Seu ID externo da entidade de origem. Segundo critério de vínculo sem
originEntityId. Após vincular, o valor gravado é entities.external_id (valor do cliente não é mantido se diferir).string
CPF/CNPJ ou outro tax ID de origem no raiz da requisição. Terceiro critério após
originEntityId e originExternalId. Comparação com entity.taxId de forma normalizada. Se achar, preenche vínculo, nome e país. Após vincular, gravado como entities.tax_id. Opcional, máx. 50 caracteres.string
Nome da origem
string
Código de país ISO 2 da origem (ex.: “US”, “BR”, “AR”)
object
Detalhes da origem (dispositivo, conta, etc.). Ver Schema de payment details. Campos extras permitidos. Se a origem não for uma entidade no gu1, envie identificadores em
originDetails.paymentDetails para agrupar nós pseudo (taxId, cbu, cvu, pixKey, clabe, alias, iban, holderId, debinId, cardFingerprint, accountNumber + bankCode opcional — ver prioridade no schema).Gu1 adiciona o campo reservado linkedEntityGu1 ao criar a transação: linked indica que a origem foi vinculada, unresolved que pelo menos uma referência raiz (originEntityId, originExternalId ou originTaxId) foi enviada mas não resolvida no modo soft-link, e not_requested que nenhuma referência foi enviada. O campo pertence ao servidor: qualquer valor enviado pelo integrador é ignorado e sobrescrito.Destino (entidade)
Vínculo do destino: mesma precedência da origem:
destinationEntityId → destinationExternalId → destinationTaxId.Com destino vinculado, o gu1 sempre sincroniza destinationTaxId e destinationExternalId a partir da entidade (mesmas regras da origem). Sem vínculo, mantém os valores enviados.string
UUID da entidade de destino no gu1
string
Seu ID externo da entidade de destino. Após vincular, gravado como
entities.external_id.string
Tax / documento do destino no raiz; terceiro fallback depois de
destinationEntityId e destinationExternalId. Mesma regra de originTaxId. Após vincular, gravado como entities.tax_id. Opcional, máx. 50 caracteres.string
Nome do destino
string
Código de país ISO 2 do destino
object
Detalhes do destino (comerciante, conta, etc.). Campos opcionais; extras permitidos. Se o destino não for uma entidade no gu1, envie os mesmos identificadores em
destinationDetails.paymentDetails para agrupar nós pseudo (mesma prioridade que origem — ver Payment Details Schema).Gu1 adiciona o campo reservado linkedEntityGu1 ao criar a transação: linked indica que o destino foi vinculado, unresolved que pelo menos uma referência raiz (destinationEntityId, destinationExternalId ou destinationTaxId) foi enviada mas não resolvida no modo soft-link, e not_requested que nenhuma referência foi enviada. O campo pertence ao servidor: qualquer valor enviado pelo integrador é ignorado e sobrescrito.Localização e dispositivo
object
Localização:
country, city, region, address, latitude, longitude, postalCode, etc.object
Dispositivo:
deviceId, platform, osName, model, ipAddress, isVpn, isTor, etc.string
Canal (máx. 50 caracteres):
mobile_app, web_browser, pos_terminal, api, atm, etc.string
Motivo do resultado (opcional). Ver Enum de motivos. Se omitido, usa
WITHOUT_REASON.string
Fuso horário IANA opcional (independente de
operationalHours da entidade). Valores de transaction_time_zone. Se omitido, fica null.Normalização de transactedAt: se transactedAt tiver Z (como exige o validador deste endpoint), esse instante é gravado em UTC; timeZone é metadata opcional e não entra no parse. Com datetime local + timeZone (ferramentas internas/lote), a API pode converter horário local para UTC. Integrações que não enviam timeZone continuam como antes. Regras de horário operacional usam o instante gravado + operationalHours.timezone da entidade, não transaction.timeZone.Lista completa: Enum fuso horário.object
Metadados adicionais:
tags, purpose, enhanced_due_diligence, block_reason, compliance_alert, etc.Resposta
object
A transação criada (objeto). Inclui:
id, externalId, organizationId, type, amount (string), currency, status, riskScore (string), flagged, channel, reason, timeZone (string | null), originDetails, destinationDetails, locationDetails, deviceDetails, processingTimeMs, processedAt, transactedAt, createdAt, updatedAt.object
Presente quando executeRules é true.Síncrono (padrão): completo após as regras terminarem na mesma request.Async (
asyncRules=true): placeholder com success: true, rulesHit / rulesNoHit vazios e matchedRulesCount: 0. Alertas e score atualizam quando o processamento em background termina.Omitido se executeRules for false. Ver Resumo de Execução de Regras.boolean
Presente e
true apenas quando as regras foram enfileiradas. Omitido no fluxo síncrono padrão.string
No modo async:
"queued". Omitido quando as regras rodaram de forma síncrona.Exemplo básico
Regras async (ingestão em alto volume)
Para respostas rápidas e revisar alertas depois no gu1. As regras rodam em background;rulesExecutionSummary.rulesHit vem vazio na resposta HTTP.
Conversão de moeda
Quandocurrency difere da moeda base da organização (padrão USD), o Gueno busca a taxa automaticamente. O comportamento não muda se você omitir exchangeRate.
Ordem de resolução
Semântica de exchangeRate
- Direção: unidades da moeda base por 1 unidade de
currency(igual às taxas do provedor). - Fórmula:
valorNormalizado = amount × exchangeRate(persistido na moeda base da org). - Não é override: se a etapa 2 tiver sucesso,
exchangeRatedo cliente é ignorado.
Moedas não conversíveis (conversão automática)
O Gueno não obtém taxa de câmbio automática para estes códigos hoje. A conversão automática fica indisponível salvo se você enviarexchangeRate:
Demais códigos ISO seguem o fluxo automático usual (provedor ou histórico com
transactedAt).
Envie exchangeRate se precisar de valor normalizado na base para regras e relatórios.
Exemplo — WLD com taxa do cliente
63.05, rateSource: client-provided):
O batch (
POST /transactions/batch, upload, JSON) aceita o mesmo exchangeRate opcional em cada linha, com a mesma semântica.Com Redis configurado, os jobs vão para a fila
transaction-rules-eval (workers dedicados se DISABLE_INPROCESS_BULL_WORKERS=true). Se Redis não existir ou o enqueue falhar, a API ainda responde 200 com asyncRules: true e executa as regras no processo dessa instância (adequado para dev ou instância única; alto volume multi-instância: Redis + workers).Exemplo de resposta
Erros
400 - Dados inválidos
409 - Transação duplicada
429 - Limite de taxa
Próximos passos
- Obter transação - Por ID ou external ID
- Criar transações em lote - Carga em massa
- Alterar status da transação - Alterar status
- Monitoramento de transações - Detecção de fraude