Endpoint Criar Transação para Monitoramento

API Reference - Monitoramento de Transações

curl --request POST \
  --url http://api.gu1.ai/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalId": "<string>",
  "type": "<string>",
  "status": "<string>",
  "amount": 123,
  "currency": "<string>",
  "paymentMethod": "<string>",
  "originEntityId": "<string>",
  "originExternalId": "<string>",
  "originTaxId": "<string>",
  "originName": "<string>",
  "originCountry": "<string>",
  "originDetails": {},
  "destinationEntityId": "<string>",
  "destinationExternalId": "<string>",
  "destinationTaxId": "<string>",
  "destinationName": "<string>",
  "destinationCountry": "<string>",
  "destinationDetails": {},
  "channel": "<string>",
  "reason": "<string>",
  "locationDetails": {},
  "deviceDetails": {},
  "description": "<string>",
  "category": "<string>",
  "metadata": {},
  "transactedAt": "<string>",
  "executeRules": true
}
'

import requests

url = "http://api.gu1.ai/transactions"

payload = {
    "externalId": "<string>",
    "type": "<string>",
    "status": "<string>",
    "amount": 123,
    "currency": "<string>",
    "paymentMethod": "<string>",
    "originEntityId": "<string>",
    "originExternalId": "<string>",
    "originTaxId": "<string>",
    "originName": "<string>",
    "originCountry": "<string>",
    "originDetails": {},
    "destinationEntityId": "<string>",
    "destinationExternalId": "<string>",
    "destinationTaxId": "<string>",
    "destinationName": "<string>",
    "destinationCountry": "<string>",
    "destinationDetails": {},
    "channel": "<string>",
    "reason": "<string>",
    "locationDetails": {},
    "deviceDetails": {},
    "description": "<string>",
    "category": "<string>",
    "metadata": {},
    "transactedAt": "<string>",
    "executeRules": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    externalId: '<string>',
    type: '<string>',
    status: '<string>',
    amount: 123,
    currency: '<string>',
    paymentMethod: '<string>',
    originEntityId: '<string>',
    originExternalId: '<string>',
    originTaxId: '<string>',
    originName: '<string>',
    originCountry: '<string>',
    originDetails: {},
    destinationEntityId: '<string>',
    destinationExternalId: '<string>',
    destinationTaxId: '<string>',
    destinationName: '<string>',
    destinationCountry: '<string>',
    destinationDetails: {},
    channel: '<string>',
    reason: '<string>',
    locationDetails: {},
    deviceDetails: {},
    description: '<string>',
    category: '<string>',
    metadata: {},
    transactedAt: '<string>',
    executeRules: true
  })
};

fetch('http://api.gu1.ai/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'externalId' => '<string>',
    'type' => '<string>',
    'status' => '<string>',
    'amount' => 123,
    'currency' => '<string>',
    'paymentMethod' => '<string>',
    'originEntityId' => '<string>',
    'originExternalId' => '<string>',
    'originTaxId' => '<string>',
    'originName' => '<string>',
    'originCountry' => '<string>',
    'originDetails' => [
        
    ],
    'destinationEntityId' => '<string>',
    'destinationExternalId' => '<string>',
    'destinationTaxId' => '<string>',
    'destinationName' => '<string>',
    'destinationCountry' => '<string>',
    'destinationDetails' => [
        
    ],
    'channel' => '<string>',
    'reason' => '<string>',
    'locationDetails' => [
        
    ],
    'deviceDetails' => [
        
    ],
    'description' => '<string>',
    'category' => '<string>',
    'metadata' => [
        
    ],
    'transactedAt' => '<string>',
    'executeRules' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/transactions"

	payload := strings.NewReader("{\n  \"externalId\": \"<string>\",\n  \"type\": \"<string>\",\n  \"status\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"originEntityId\": \"<string>\",\n  \"originExternalId\": \"<string>\",\n  \"originTaxId\": \"<string>\",\n  \"originName\": \"<string>\",\n  \"originCountry\": \"<string>\",\n  \"originDetails\": {},\n  \"destinationEntityId\": \"<string>\",\n  \"destinationExternalId\": \"<string>\",\n  \"destinationTaxId\": \"<string>\",\n  \"destinationName\": \"<string>\",\n  \"destinationCountry\": \"<string>\",\n  \"destinationDetails\": {},\n  \"channel\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"locationDetails\": {},\n  \"deviceDetails\": {},\n  \"description\": \"<string>\",\n  \"category\": \"<string>\",\n  \"metadata\": {},\n  \"transactedAt\": \"<string>\",\n  \"executeRules\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/transactions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalId\": \"<string>\",\n  \"type\": \"<string>\",\n  \"status\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"originEntityId\": \"<string>\",\n  \"originExternalId\": \"<string>\",\n  \"originTaxId\": \"<string>\",\n  \"originName\": \"<string>\",\n  \"originCountry\": \"<string>\",\n  \"originDetails\": {},\n  \"destinationEntityId\": \"<string>\",\n  \"destinationExternalId\": \"<string>\",\n  \"destinationTaxId\": \"<string>\",\n  \"destinationName\": \"<string>\",\n  \"destinationCountry\": \"<string>\",\n  \"destinationDetails\": {},\n  \"channel\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"locationDetails\": {},\n  \"deviceDetails\": {},\n  \"description\": \"<string>\",\n  \"category\": \"<string>\",\n  \"metadata\": {},\n  \"transactedAt\": \"<string>\",\n  \"executeRules\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/transactions")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalId\": \"<string>\",\n  \"type\": \"<string>\",\n  \"status\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"originEntityId\": \"<string>\",\n  \"originExternalId\": \"<string>\",\n  \"originTaxId\": \"<string>\",\n  \"originName\": \"<string>\",\n  \"originCountry\": \"<string>\",\n  \"originDetails\": {},\n  \"destinationEntityId\": \"<string>\",\n  \"destinationExternalId\": \"<string>\",\n  \"destinationTaxId\": \"<string>\",\n  \"destinationName\": \"<string>\",\n  \"destinationCountry\": \"<string>\",\n  \"destinationDetails\": {},\n  \"channel\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"locationDetails\": {},\n  \"deviceDetails\": {},\n  \"description\": \"<string>\",\n  \"category\": \"<string>\",\n  \"metadata\": {},\n  \"transactedAt\": \"<string>\",\n  \"executeRules\": true\n}"

response = http.request(request)
puts response.read_body

{
  "transaction": {},
  "rulesExecutionSummary": {}
}

POST

transactions

API Reference - Monitoramento de Transações

curl --request POST \
  --url http://api.gu1.ai/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalId": "<string>",
  "type": "<string>",
  "status": "<string>",
  "amount": 123,
  "currency": "<string>",
  "paymentMethod": "<string>",
  "originEntityId": "<string>",
  "originExternalId": "<string>",
  "originTaxId": "<string>",
  "originName": "<string>",
  "originCountry": "<string>",
  "originDetails": {},
  "destinationEntityId": "<string>",
  "destinationExternalId": "<string>",
  "destinationTaxId": "<string>",
  "destinationName": "<string>",
  "destinationCountry": "<string>",
  "destinationDetails": {},
  "channel": "<string>",
  "reason": "<string>",
  "locationDetails": {},
  "deviceDetails": {},
  "description": "<string>",
  "category": "<string>",
  "metadata": {},
  "transactedAt": "<string>",
  "executeRules": true
}
'

import requests

url = "http://api.gu1.ai/transactions"

payload = {
    "externalId": "<string>",
    "type": "<string>",
    "status": "<string>",
    "amount": 123,
    "currency": "<string>",
    "paymentMethod": "<string>",
    "originEntityId": "<string>",
    "originExternalId": "<string>",
    "originTaxId": "<string>",
    "originName": "<string>",
    "originCountry": "<string>",
    "originDetails": {},
    "destinationEntityId": "<string>",
    "destinationExternalId": "<string>",
    "destinationTaxId": "<string>",
    "destinationName": "<string>",
    "destinationCountry": "<string>",
    "destinationDetails": {},
    "channel": "<string>",
    "reason": "<string>",
    "locationDetails": {},
    "deviceDetails": {},
    "description": "<string>",
    "category": "<string>",
    "metadata": {},
    "transactedAt": "<string>",
    "executeRules": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    externalId: '<string>',
    type: '<string>',
    status: '<string>',
    amount: 123,
    currency: '<string>',
    paymentMethod: '<string>',
    originEntityId: '<string>',
    originExternalId: '<string>',
    originTaxId: '<string>',
    originName: '<string>',
    originCountry: '<string>',
    originDetails: {},
    destinationEntityId: '<string>',
    destinationExternalId: '<string>',
    destinationTaxId: '<string>',
    destinationName: '<string>',
    destinationCountry: '<string>',
    destinationDetails: {},
    channel: '<string>',
    reason: '<string>',
    locationDetails: {},
    deviceDetails: {},
    description: '<string>',
    category: '<string>',
    metadata: {},
    transactedAt: '<string>',
    executeRules: true
  })
};

fetch('http://api.gu1.ai/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'externalId' => '<string>',
    'type' => '<string>',
    'status' => '<string>',
    'amount' => 123,
    'currency' => '<string>',
    'paymentMethod' => '<string>',
    'originEntityId' => '<string>',
    'originExternalId' => '<string>',
    'originTaxId' => '<string>',
    'originName' => '<string>',
    'originCountry' => '<string>',
    'originDetails' => [
        
    ],
    'destinationEntityId' => '<string>',
    'destinationExternalId' => '<string>',
    'destinationTaxId' => '<string>',
    'destinationName' => '<string>',
    'destinationCountry' => '<string>',
    'destinationDetails' => [
        
    ],
    'channel' => '<string>',
    'reason' => '<string>',
    'locationDetails' => [
        
    ],
    'deviceDetails' => [
        
    ],
    'description' => '<string>',
    'category' => '<string>',
    'metadata' => [
        
    ],
    'transactedAt' => '<string>',
    'executeRules' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/transactions"

	payload := strings.NewReader("{\n  \"externalId\": \"<string>\",\n  \"type\": \"<string>\",\n  \"status\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"originEntityId\": \"<string>\",\n  \"originExternalId\": \"<string>\",\n  \"originTaxId\": \"<string>\",\n  \"originName\": \"<string>\",\n  \"originCountry\": \"<string>\",\n  \"originDetails\": {},\n  \"destinationEntityId\": \"<string>\",\n  \"destinationExternalId\": \"<string>\",\n  \"destinationTaxId\": \"<string>\",\n  \"destinationName\": \"<string>\",\n  \"destinationCountry\": \"<string>\",\n  \"destinationDetails\": {},\n  \"channel\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"locationDetails\": {},\n  \"deviceDetails\": {},\n  \"description\": \"<string>\",\n  \"category\": \"<string>\",\n  \"metadata\": {},\n  \"transactedAt\": \"<string>\",\n  \"executeRules\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/transactions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"externalId\": \"<string>\",\n  \"type\": \"<string>\",\n  \"status\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"originEntityId\": \"<string>\",\n  \"originExternalId\": \"<string>\",\n  \"originTaxId\": \"<string>\",\n  \"originName\": \"<string>\",\n  \"originCountry\": \"<string>\",\n  \"originDetails\": {},\n  \"destinationEntityId\": \"<string>\",\n  \"destinationExternalId\": \"<string>\",\n  \"destinationTaxId\": \"<string>\",\n  \"destinationName\": \"<string>\",\n  \"destinationCountry\": \"<string>\",\n  \"destinationDetails\": {},\n  \"channel\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"locationDetails\": {},\n  \"deviceDetails\": {},\n  \"description\": \"<string>\",\n  \"category\": \"<string>\",\n  \"metadata\": {},\n  \"transactedAt\": \"<string>\",\n  \"executeRules\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/transactions")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"externalId\": \"<string>\",\n  \"type\": \"<string>\",\n  \"status\": \"<string>\",\n  \"amount\": 123,\n  \"currency\": \"<string>\",\n  \"paymentMethod\": \"<string>\",\n  \"originEntityId\": \"<string>\",\n  \"originExternalId\": \"<string>\",\n  \"originTaxId\": \"<string>\",\n  \"originName\": \"<string>\",\n  \"originCountry\": \"<string>\",\n  \"originDetails\": {},\n  \"destinationEntityId\": \"<string>\",\n  \"destinationExternalId\": \"<string>\",\n  \"destinationTaxId\": \"<string>\",\n  \"destinationName\": \"<string>\",\n  \"destinationCountry\": \"<string>\",\n  \"destinationDetails\": {},\n  \"channel\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"locationDetails\": {},\n  \"deviceDetails\": {},\n  \"description\": \"<string>\",\n  \"category\": \"<string>\",\n  \"metadata\": {},\n  \"transactedAt\": \"<string>\",\n  \"executeRules\": true\n}"

response = http.request(request)
puts response.read_body

{
  "transaction": {},
  "rulesExecutionSummary": {}
}

Referência canónica do endpoint

A referência oficial do endpoint POST /transactions (estrutura da resposta, erros, campos) está em: Criar transação (API Reference → Transações) Lá você encontra a resposta atual: transaction é um objeto (a transação criada) e, quando as regras rodam, rulesExecutionSummary vem na raiz da resposta (ver Resumo de Execução de Regras). Esta página adiciona contexto de uso para monitoramento: conversão de moeda, exemplos por método de pagamento (PIX, cartão, multi-moeda) e descrição detalhada dos campos.

Endpoint: Criar Transação

POST http://api.gu1.ai/transactions

Cria uma nova transação. Os valores são convertidos para USD quando a moeda não for USD. Com executeRules: true (padrão), o motor de regras é executado e a resposta inclui rulesExecutionSummary na raiz quando as regras são executadas.

Autenticação

Todas as requisições devem incluir uma chave API no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Cabeçalhos Obrigatórios

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Corpo da Requisição

string

required

Seu identificador único para esta transação no seu sistemaTipo: string (comprimento mínimo: 1)

string

required

Tipo de transação. Opções:

PAYMENT - Compra ou pagamento a comerciante
TRANSFER - Transferência entre contas/usuários
WITHDRAWAL - Saque ou débito de conta
DEPOSIT - Depósito ou crédito de conta
REFUND - Reembolso de transação anterior
CHARGEBACK - Disputa de estorno
REVERSAL - Reversão de transação
FEE - Cobrança de taxa ou comissão
ADJUSTMENT - Ajuste de saldo
OTHER - Outro tipo de transação

Tipo: enum -

'PAYMENT' | 'TRANSFER' | 'WITHDRAWAL' | 'DEPOSIT' | 'REFUND' | 'CHARGEBACK' | 'REVERSAL' | 'FEE' | 'ADJUSTMENT' | 'OTHER'

string

default:"CREATED"

Status da transação. Segue um modelo de máquina de estados com estados abertos e fechados.Estados Abertos (podem transitar para outros estados):

CREATED - Transação criada (padrão)
PROCESSING - Transação em processamento
SUSPENDED - Transação temporariamente suspensa

Estados Fechados (finais, não podem voltar a estados abertos):

SENT - Transação enviada/transmitida
EXPIRED - Transação expirada
DECLINED - Transação recusada/declinada
REFUNDED - Transação reembolsada/revertida
SUCCESSFUL - Transação concluída com sucesso

number

required

Valor da transação (deve ser positivo)Tipo: number (> 0)

string

required

Código ISO 4217 de moeda (ex: “USD”, “BRL”, “EUR”)Tipo: string (comprimento: 3)

string

Método de pagamento utilizado para a transaçãoTipo: string (enum, opcional)Valores Possíveis:

CARD - Pagamento com cartão de crédito ou débito
ACH - Automated Clearing House (transferência bancária US)
PIX - Sistema de pagamentos instantâneos do Brasil
TED - Transferência bancária brasileira (Transferência Eletrônica Disponível)
BOLETO - Boleto de pagamento brasileiro
WALLET - Carteira digital (PayPal, Venmo, etc.)
SWIFT - Transferência internacional SWIFT
IBAN - Transferência bancária baseada em IBAN
CBU - Conta bancária argentina (Clave Bancaria Uniforme)
CVU - Conta virtual argentina (Clave Virtual Uniforme)
DEBIN - Sistema de débito instantâneo argentino
GENERIC_BANK_ACCOUNT - Transferência de conta bancária genérica
MPESA - M-Pesa mobile money (Quênia)
UPI - Unified Payments Interface (Índia)
CHECK - Pagamento com cheque
ECHECK - Cheque eletrônico
QR_CODE - Pagamento com código QR
ONLINE_PAYMENT - Pagamento online genérico
WITHDRAWAL_ORDER - Ordem de saque

Exemplo: "PIX" ou "CARD"

string

UUID da entidade de origem (remetente) no sistema gu1Tipo: string (uuid, opcional)

string

Seu ID externo para a entidade de origemTipo: string (opcional)

string

Tax / documento de origem no raiz do corpo. Terceiro critério (após originEntityId e originExternalId); match normalizado a entity.taxId. Máx. 50 caracteres. Tipo: string (opcional)

string

Nome da entidade de origem (remetente)Tipo: string (comprimento máximo: 500, opcional)

string

Código de país ISO 3166-1 alpha-2 da entidade de origemTipo: string (comprimento: 2, opcional)

object

Informações contextuais sobre a origem da transação (dispositivo, geolocalização, conta, flags de segurança). Estes campos coincidem com o schema da API; também pode enviar campos custom adicionais (ex.: paymentDetails aninhado ou outras chaves) e serão armazenados.Tipo: object (opcional, estrutura validada; chaves extras permitidas)Diferença Importante:

originCountry (campo direto) = País da entidade
originDetails.country = País do dispositivo/IP no momento da transação (pode diferir se estiver viajando)

Campos Suportados:Dispositivo/Técnico:

deviceId (string) - Identificador do dispositivo
deviceFingerprint (string) - Hash de impressão digital do dispositivo
deviceType (enum) - mobile | desktop | tablet | pos | atm
userAgent (string) - User agent do navegador
ipAddress (string) - Endereço IP (formato validado)

Geolocalização:

country (string) - Código ISO de 2 letras
city (string) - Nome da cidade
region (string) - Estado/província
latitude (number) - Latitude (-90 a 90)
longitude (number) - Longitude (-180 a 180)
timezone (string) - Identificador de fuso horário

Detalhes de Pagamento (objeto aninhado):

paymentDetails (object) - Informações específicas de pagamento para a origem. Você pode enviar qualquer campo relacionado a pagamento:
- Detalhes Bancários/Conta:
  - accountNumber (string) - Número da conta
  - accountType (enum) - checking | savings | business | personal
  - bankCode (string) - Código do banco
  - bankName (string) - Nome do banco
  - routingNumber (string) - Routing number (US)
  - swiftCode (string) - Código SWIFT/BIC
  - iban (string) - IBAN (International Bank Account Number)
- Detalhes PIX (Brasil):
  - pixKey (string) - Chave PIX
  - pixType (enum) - Tipo de chave PIX: email | phone | cpf | cnpj | random
  - endToEndId (string) - ID único end-to-end do PIX
- Detalhes de Cartão:
  - cardLast4 (string) - Últimos 4 dígitos do cartão
  - cardBrand (string) - Bandeira do cartão (Visa, Mastercard, Amex, etc.)
  - cardholderName (string) - Nome no cartão
  - cardBin (string) - Primeiros 6 dígitos do cartão (BIN)
  - cardType (enum) - credit | debit | prepaid
  - cardCountry (string) - País emissor do cartão (ISO 2 letras)
  - cardExpiry (string) - Data de vencimento (MM/AA)
  - cardFingerprint (string) - Impressão digital única do cartão para rastreamento
- Detalhes Crypto:
  - walletAddress (string) - Endereço de carteira de criptomoeda
  - walletType (string) - Tipo de carteira (ex: “metamask”, “coinbase”)
  - blockchain (string) - Rede blockchain (ex: “ethereum”, “bitcoin”)
  - tokenSymbol (string) - Símbolo do token (ex: “ETH”, “BTC”, “USDT”)
  - txHash (string) - Hash da transação blockchain
  - confirmations (number) - Número de confirmações blockchain
- Carteira/Pagamento Digital:
  - walletId (string) - Identificador de carteira digital
  - walletProvider (string) - Provedor de carteira (ex: “paypal”, “venmo”, “mercadopago”)
  - walletEmail (string) - Email associado à carteira
- Campos Argentina (CBU/CVU):
  - cbu (string) - CBU argentino (22 dígitos)
  - cvu (string) - CVU argentino (22 dígitos)
  - alias (string) - Alias do CBU/CVU
- Campos México (SPEI):
  - clabe (string) - Número CLABE (México, 18 dígitos)
  - trackingKey (string) - Chave de rastreamento SPEI
- Campos Dinheiro/Cheque:
  - checkNumber (string) - Número do cheque
  - receiptNumber (string) - Número do recibo
  - location (string) - Localização do pagamento (dinheiro)
- E quaisquer outros campos relacionados a pagamento que você precisar

Referência: Para estruturas sugeridas por método de pagamento (cartão, PIX, CBU/CVU, SPEI, PSE, DEBIN, cripto, wallet, dinheiro, cheque, etc.) ver Payment Details Schema. Nada é exigido; campos custom são permitidos.Flags de Segurança:

isVpn (boolean) - VPN detectada
isTor (boolean) - Rede Tor detectada
isProxy (boolean) - Proxy detectado
governmentAccount (boolean) - Flag de conta governamental

Exemplo:

{
  "deviceType": "mobile",
  "ipAddress": "189.123.45.67",
  "country": "BR",
  "city": "São Paulo",
  "isVpn": false,
  "paymentDetails": {
    "accountNumber": "12345",
    "accountType": "personal",
    "bankName": "Banco do Brasil",
    "pixKey": "user@email.com",
    "pixType": "email"
  }
}

Campos personalizados são permitidos - o sistema validará campos conhecidos e preservará os personalizados.

string

UUID da entidade de destino (destinatário) no sistema gu1Tipo: string (uuid, opcional)

string

Seu ID externo para a entidade de destinoTipo: string (opcional)

string

Documento de destino no raiz; terceiro critério, mesma regra de originTaxId. Tipo: string (opcional)

string

Nome da entidade de destino (destinatário)Tipo: string (comprimento máximo: 500, opcional)

string

Código de país ISO 3166-1 alpha-2 da entidade de destinoTipo: string (comprimento: 2, opcional)

object

Informações contextuais sobre o destino da transação (comerciante, dispositivo, geolocalização, conta, flags de risco). Estes campos coincidem com o schema da API; também pode enviar campos custom adicionais (ex.: paymentDetails aninhado ou outras chaves) e serão armazenados.Tipo: object (opcional, estrutura validada; chaves extras permitidas)Campos Suportados:Informações de Comerciante:

mcc (string) - Merchant Category Code (4 dígitos, ISO 18245)
mccDescription (string) - Descrição do MCC (ex: “Restaurants”)
merchantId (string) - Identificador do comerciante
merchantName (string) - Nome do comerciante
merchantType (string) - Tipo/categoria do comerciante

Dispositivo/Técnico:

deviceId (string) - Identificador do dispositivo
deviceType (enum) - pos | online | mobile | atm
ipAddress (string) - Endereço IP (formato validado)

Geolocalização:

country (string) - Código ISO de 2 letras
city (string) - Nome da cidade
region (string) - Estado/província

Detalhes de Pagamento (objeto aninhado):

paymentDetails (object) - Informações específicas de pagamento para o destino. Você pode enviar qualquer campo relacionado a pagamento:
- Detalhes Bancários/Conta:
  - accountNumber (string) - Número da conta de destino
  - accountType (enum) - checking | savings | business | merchant
  - bankCode (string) - Código do banco
  - bankName (string) - Nome do banco
  - routingNumber (string) - Routing number (US)
  - swiftCode (string) - Código SWIFT/BIC
  - iban (string) - IBAN (International Bank Account Number)
- Detalhes PIX (Brasil):
  - pixKey (string) - Chave PIX
  - pixType (enum) - Tipo de chave PIX: email | phone | cpf | cnpj | random
  - endToEndId (string) - ID único end-to-end do PIX
- Detalhes de Cartão:
  - cardLast4 (string) - Últimos 4 dígitos do cartão
  - cardBrand (string) - Bandeira do cartão (Visa, Mastercard, Amex, etc.)
  - cardholderName (string) - Nome no cartão
  - cardBin (string) - Primeiros 6 dígitos do cartão (BIN)
  - cardType (enum) - credit | debit | prepaid
  - cardCountry (string) - País emissor do cartão (ISO 2 letras)
  - cardExpiry (string) - Data de vencimento (MM/AA)
  - cardFingerprint (string) - Impressão digital única do cartão para rastreamento
- Detalhes Crypto:
  - walletAddress (string) - Endereço de carteira de criptomoeda
  - walletType (string) - Tipo de carteira (ex: “metamask”, “coinbase”)
  - blockchain (string) - Rede blockchain (ex: “ethereum”, “bitcoin”)
  - tokenSymbol (string) - Símbolo do token (ex: “ETH”, “BTC”, “USDT”)
  - txHash (string) - Hash da transação blockchain
  - confirmations (number) - Número de confirmações blockchain
- Carteira/Pagamento Digital:
  - walletId (string) - Identificador de carteira digital
  - walletProvider (string) - Provedor de carteira (ex: “paypal”, “venmo”, “mercadopago”)
  - walletEmail (string) - Email associado à carteira
- Campos Argentina (CBU/CVU):
  - cbu (string) - CBU argentino (22 dígitos)
  - cvu (string) - CVU argentino (22 dígitos)
  - alias (string) - Alias do CBU/CVU
- Campos México (SPEI):
  - clabe (string) - Número CLABE (México, 18 dígitos)
  - trackingKey (string) - Chave de rastreamento SPEI
- Campos Dinheiro/Cheque:
  - checkNumber (string) - Número do cheque
  - receiptNumber (string) - Número do recibo
  - location (string) - Localização do pagamento (dinheiro)
- E quaisquer outros campos relacionados a pagamento que você precisar

Referência: Para estruturas sugeridas por método de pagamento ver Payment Details Schema. Nada é exigido; campos custom são permitidos.Flags de Risco:

cryptoExchange (boolean) - É uma exchange de criptomoedas
highRisk (boolean) - Flag de comerciante de alto risco
privateSector (boolean) - Flag de setor privado

Exemplo:

{
  "mcc": "5812",
  "mccDescription": "Restaurants",
  "merchantName": "Restaurant ABC",
  "country": "US",
  "highRisk": false,
  "paymentDetails": {
    "accountNumber": "98765",
    "accountType": "merchant",
    "bankName": "Bradesco"
  }
}

Campos personalizados são permitidos - o sistema validará campos conhecidos e preservará os personalizados.

string

O canal através do qual a transação foi iniciada (máximo 50 caracteres).Tipo: string (comprimento máximo: 50, opcional)Exemplos Comuns:

mobile_app - Aplicativo móvel
web_browser - Navegador web
pos_terminal - Terminal ponto de venda
api - Integração API direta
atm - Caixa eletrônico
phone_banking - Banking telefônico
branch - Agência física
call_center - Central de atendimento
partner_api - Integração com parceiro

Caso de Uso: Ajuda a segmentar transações por canal de origem para análise de risco, relatórios e inteligência de negócios.Exemplo:

{
  "channel": "mobile_app"
}

string

Motivo opcional do resultado da transação (ex.: recusa, falha, limite excedido). O cliente pode enviar qualquer valor do enum transaction_reason_type. Se omitido, o sistema usa WITHOUT_REASON. Não é obrigatório — integrações atuais continuam válidas.Tipo: string (enum, opcional, padrão: WITHOUT_REASON)Valores comuns (o enum completo tem 60+ valores):

WITHOUT_REASON - Sem motivo específico (padrão quando omitido)
INSUFFICIENT_FUNDS - Fundos insuficientes
LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED, MONTHLY_LIMIT_EXCEEDED, TRANSACTION_LIMIT_EXCEEDED
ACCOUNT_BLOCKED, ACCOUNT_FROZEN, ACCOUNT_CLOSED
CARD_EXPIRED, CARD_BLOCKED, CARD_LOST_OR_STOLEN, INVALID_CARD, INVALID_ACCOUNT
FRAUD_SUSPECTED, COMPLIANCE_BLOCK, SANCTIONS_MATCH, AML_ALERT, RISK_SCORE_THRESHOLD
MERCHANT_BLOCKED, COUNTRY_RESTRICTION, CURRENCY_NOT_SUPPORTED, CHANNEL_NOT_ALLOWED
SYSTEM_ERROR, TIMEOUT, INVALID_AMOUNT, KYC_PENDING, KYC_REJECTED
EXPIRED, CANCELLED_BY_USER, CANCELLED_BY_MERCHANT, REFUSED_BY_ISSUER, DO_NOT_HONOR
INVALID_PIN, PIN_TRIES_EXCEEDED, INSUFFICIENT_LIQUIDITY, VALIDATION_FAILED, OTHER

Lista completa: Ver Enum Motivo da Transação para os 60+ valores permitidos.Exemplo:

{
  "reason": "INSUFFICIENT_FUNDS"
}

object

Informações de localização geográfica onde a transação ocorreu. Útil para detecção de fraude, análise de risco geográfico e relatórios de conformidade.Tipo: object (opcional)Campos Suportados:Informações de Endereço:

country (string) - Código de país ISO 3166-1 alpha-2 (ex: “US”, “BR”, “AR”)
countryName (string) - Nome completo do país
city (string) - Nome da cidade
region (string) - Estado ou província
address (string) - Endereço completo
street (string) - Nome da rua
streetNumber (string) - Número da rua
postalCode (string) - Código postal/CEP
neighborhood (string) - Bairro ou distrito

Coordenadas (para visualização em mapas):

latitude (number) - Coordenada de latitude (-90 a 90)
longitude (number) - Coordenada de longitude (-180 a 180)

Informações Adicionais:

timezone (string) - Fuso horário IANA (ex: “America/Sao_Paulo”)
placeId (string) - ID do Google Places ou identificador similar

Exemplo:

{
  "country": "BR",
  "countryName": "Brasil",
  "city": "São Paulo",
  "region": "SP",
  "address": "Av. Paulista, 1578",
  "street": "Av. Paulista",
  "streetNumber": "1578",
  "postalCode": "01310-200",
  "latitude": -23.5505,
  "longitude": -46.6333,
  "timezone": "America/Sao_Paulo"
}

Casos de Uso:

Detecção de Fraude: Identificar transações de localizações incomuns ou países de alto risco
Análise Geográfica: Analisar padrões de transações por região
Conformidade: Rastrear transações transfronteiriças para relatórios regulatórios
Regras de Velocidade: Detectar viagens impossíveis (mesmo usuário em diferentes localizações em pouco tempo)

object

Informações do dispositivo para a transação. Crítico para detecção de fraude, fingerprinting de dispositivos e análise de segurança.Tipo: object (opcional)Campos Suportados:Identificação do Dispositivo:

deviceId (string) - Identificador único do dispositivo
externalId (string) - Seu ID externo do dispositivo

Plataforma e Sistema Operacional:

platform (enum) - Plataforma do dispositivo: android, ios, web, desktop, mobile, tablet, pos, atm
osName (string) - Nome do sistema operacional (ex: “Android”, “iOS”, “Windows”, “macOS”)
osVersion (string) - Versão do SO (ex: “13.0”, “16.4”)

Informações do Dispositivo:

manufacturer (string) - Fabricante do dispositivo (ex: “Samsung”, “Apple”)
model (string) - Modelo do dispositivo (ex: “Galaxy S22”, “iPhone 14”)
brand (string) - Marca do dispositivo
deviceName (string) - Nome atribuído pelo usuário ao dispositivo

Informações do Navegador (para plataforma web):

browser (string) - Nome do navegador (ex: “Chrome”, “Safari”, “Firefox”)
browserVersion (string) - Versão do navegador
userAgent (string) - String completa do user agent

Flags de Segurança:

isEmulator (boolean) - Se o dispositivo é um emulador
isRooted (boolean) - Se o dispositivo está com root (Android)
isJailbroken (boolean) - Se o dispositivo está com jailbreak (iOS)

Informações de Rede:

ipAddress (string) - Endereço IP (formato validado)
isVpn (boolean) - Se a conexão é através de VPN
isTor (boolean) - Se a conexão é através de Tor
isProxy (boolean) - Se a conexão é através de proxy

Fingerprinting de Dispositivo:

deviceFingerprint (string) - Hash único de impressão digital do dispositivo para rastreamento

Detalhes Adicionais:

screenResolution (string) - Resolução da tela (ex: “1920x1080”)
language (string) - Idioma do dispositivo
timezone (string) - Fuso horário do dispositivo

Exemplo:

{
  "platform": "mobile",
  "osName": "Android",
  "osVersion": "13",
  "manufacturer": "Samsung",
  "model": "Galaxy S22",
  "brand": "Samsung",
  "ipAddress": "192.168.1.1",
  "isVpn": false,
  "isTor": false,
  "isEmulator": false,
  "isRooted": false,
  "deviceFingerprint": "abc123def456...",
  "screenResolution": "1080x2400",
  "language": "pt-BR",
  "timezone": "America/Sao_Paulo"
}

Casos de Uso:

Detecção de Fraude: Identificar dispositivos suspeitos (emuladores, dispositivos com root, uso de VPN)
Fingerprinting de Dispositivo: Rastrear dispositivos únicos através de transações para análise comportamental
Análise de Segurança: Detectar anomalias em padrões de dispositivos (novo dispositivo, velocidade de dispositivo impossível)
Conformidade: Documentar informações do dispositivo para rastros de auditoria
Experiência do Usuário: Personalizar experiência baseada em tipo e capacidades do dispositivo

string

Descrição da transaçãoTipo: string (comprimento máximo: 1000, opcional)

string

Categoria da transação para agrupamentoTipo: string (comprimento máximo: 100, opcional)

object

Metadados personalizados para armazenar informações adicionais da transação.Tipo: object (opcional, estrutura validada)Campos Padrão Suportados:

`tags` (object) - Sistema de Categorização Chave-Valor

O campo tags permite adicionar pares chave-valor personalizados para categorização flexível, filtragem e gerenciamento de fluxos de trabalho. Isso é particularmente útil para:

Filtragem personalizada em dashboards e relatórios
Ativar lógica de negócio específica
Acompanhamento do status de revisão
Categorização por nível de risco ou fonte
Estados de fluxo de trabalho personalizados

Formato: { "chave1": "valor1", "chave2": "valor2" }Padrões Comuns de Tags:

risk_level (string) - “low”, “medium”, “high”, “critical”
source (string) - “api”, “web”, “mobile”, “batch”, “import”
channel (string) - “online”, “branch”, “atm”, “call_center”, “partner”
reviewed (boolean) - false (pendente de revisão), true (revisado)
category (string) - “payroll”, “supplier”, “refund”, “investment”, “loan”, “bill_payment”
priority (string) - “low”, “normal”, “high”, “urgent”
team (string) - “compliance”, “fraud”, “support”, “operations”
campaign (string) - Identificador de campanha de marketing ou negócio
approved_by (string) - Usuário ou sistema que aprovou
requires_approval (boolean) - Requer aprovação manual
customer_segment (string) - “vip”, “regular”, “new”, “dormant”
product_type (string) - “savings”, “investment”, “loan”, “transfer”
region (string) - “north”, “south”, “latam”, “emea”, “apac”
business_unit (string) - “retail”, “corporate”, “wealth”, “sme”

Exemplos de Casos de Uso:Exemplo 1: Fluxo de trabalho baseado em risco

{
  "tags": {
    "risk_level": "high",
    "reviewed": false,
    "requires_approval": true,
    "assigned_to": "fraud_team"
  }
}

Exemplo 2: Categorização de negócio

{
  "tags": {
    "category": "payroll",
    "batch_id": "PAY_2025_01",
    "department": "engineering",
    "cost_center": "R&D"
  }
}

Exemplo 3: Rastreamento multi-canal

{
  "tags": {
    "source": "mobile_app",
    "channel": "online",
    "campaign": "winter_2025",
    "referral_code": "FRIEND123",
    "first_transaction": true,
    "customer_segment": "new"
  }
}

Exemplo 4: Operações bancárias

{
  "tags": {
    "channel": "branch",
    "business_unit": "retail",
    "product_type": "loan",
    "region": "latam",
    "requires_approval": true,
    "approved_by": "manager_john"
  }
}

Filtrar transações por tags: Posteriormente você pode filtrar transações usando essas tags em endpoints de listagem ou dashboards.

Outros Campos de Metadata:

purpose (string) - Propósito da transação (ex: “salary”, “invoice_payment”)
frequency (string) - Frequência da transação (ex: “monthly”, “one-time”)
contract_number (string) - Número de contrato (para pagamentos empresariais)
enhanced_due_diligence (boolean) - Flag de EDD
block_reason (string) - Razão do bloqueio
compliance_alert (boolean) - Flag de alerta de compliance

Exemplo Completo:

{
  "tags": {
    "risk_level": "medium",
    "source": "api",
    "reviewed": false,
    "category": "invoice_payment"
  },
  "purpose": "supplier_payment",
  "frequency": "monthly",
  "contract_number": "CNT-2025-001",
  "enhanced_due_diligence": false
}

Campos personalizados além dos padrão são permitidos e serão preservados.

string

Quando a transação ocorreu (timestamp ISO 8601). Padrão para o horário atual se não for fornecido.Tipo: string (datetime ISO 8601, opcional)

boolean

default:"true"

Se deve executar regras de risco automaticamente após criar a transaçãoTipo: boolean (padrão: true)

Métodos de Pagamento

CARD - Pagamento com cartão de crédito/débito
ACH - Transferência ACH (EUA)
PIX - Pagamento instantâneo brasileiro
TED - Transferência bancária brasileira (TED)
BOLETO - Pagamento com boleto brasileiro
WALLET - Pagamento com carteira digital
SWIFT - Transferência internacional SWIFT
IBAN - Transferência baseada em IBAN
CBU - Conta bancária argentina (CBU)
CVU - Carteira virtual argentina (CVU)
DEBIN - Débito direto argentino
GENERIC_BANK_ACCOUNT - Transferência bancária genérica
MPESA - Dinheiro móvel M-Pesa
UPI - Pagamento UPI da Índia
CHECK - Cheque físico
ECHECK - Cheque eletrônico
QR_CODE - Pagamento com código QR
ONLINE_PAYMENT - Pagamento online genérico
WITHDRAWAL_ORDER - Ordem de saque

Tipos de Conta

PERSONAL - Conta pessoal
BUSINESS - Conta empresarial
MERCHANT - Conta de comerciante
SAVINGS - Conta poupança
CHECKING - Conta corrente
INVESTMENT - Conta de investimento
ESCROW - Conta escrow
PREPAID - Conta pré-paga
OTHER - Outro tipo de conta

Códigos MCC

Merchant Category Codes (MCC) classificam tipos de negócios:

{
  "mccCode": "5411"  // Supermercados
}

Exemplos comuns:

5411 - Supermercados
5812 - Restaurantes
5999 - Varejo Diversos
6011 - Caixa Eletrônico/Saque
7995 - Jogos de Azar

Tags e Metadata

{
  "tags": ["high_value", "first_transaction", "promotional"],
  "metadata": {
    "campaignId": "summer_2024",
    "referralCode": "FRIEND10",
    "customField": "any_value"
  }
}

Suporte Multi-Moeda

O gu1 oferece conversão automática de moeda para todas as transações. Cada organização tem uma moeda base configurada (padrão: USD), e todas as transações são automaticamente convertidas para esta moeda base para avaliação consistente de regras e relatórios.

Como Funciona

Detecção Automática: Quando a currency de uma transação difere da moeda base da sua organização, a conversão automática é acionada
Taxas em Tempo Real: Taxas de câmbio são obtidas do nosso serviço de moeda em tempo real
Armazenamento de Valor Duplo: Ambos os valores original e convertido são armazenados
Avaliação de Regras: Regras podem usar tanto amount (original) quanto amountInUsd (convertido em USD)

Moedas Suportadas

Mais de 150 moedas suportadas incluindo:

Principais: USD, EUR, GBP, JPY, CHF, CAD, AUD
América Latina: BRL, ARS, MXN, COP, CLP, PEN, UYU
Ásia: CNY, INR, KRW, SGD, HKD, THB, MYR
Cripto: BTC, ETH, USDT, USDC
E muitas mais (padrão ISO 4217)

Fontes de Taxa de Câmbio

Fonte	Descrição	Quando Usado
`ms-provider`	Taxas em tempo real do microserviço de moeda	Fonte primária
`cache-fallback`	Taxas em cache quando serviço indisponível	Fallback (< 1h)
`no-conversion`	Conversão não necessária (mesma moeda)	Igual à base
`client-provided`	Taxa personalizada fornecida pelo cliente	Override opcional

Campos de resposta

Os dados de conversão vêm no objeto transaction, não em um bloco separado:

transaction.amount, transaction.currency – valor e moeda originais
transaction.amountInUsd – valor convertido em USD (null se a conversão falhar ou não se aplicar)
transaction.exchangeRate, transaction.rateSource – taxa usada e fonte (ex.: ms-provider)

Usando Valores Convertidos em Regras

Regras podem referenciar ambos os valores:

{
  "conditions": [
    {
      "field": "amount",
      "operator": "GREATER_THAN",
      "value": 1000
    }
  ]
}

Ou use o valor convertido para limites consistentes:

{
  "conditions": [
    {
      "field": "amountInUsd",
      "operator": "GREATER_THAN",
      "value": 10000
    }
  ]
}

Melhor Prática: Use amountInUsd em regras para garantir limites consistentes independentemente da moeda da transação.

Tratamento de Erros

Se a conversão de moeda falhar:

O processamento da transação continua com o valor original
transaction.amountInUsd e transaction.exchangeRate serão null
Regras usando amountInUsd usarão o amount original como fallback se a conversão falhar
O erro é registrado mas não bloqueia a transação

Exemplo: Transação Multi-Moeda

{
  "transaction": {
    "externalId": "txn_euro_001",
    "type": "PAYMENT",
    "amount": 850.00,
    "currency": "EUR",
    "timestamp": "2024-10-28T15:00:00Z",
    "originEntityId": "customer_france_001",
    "destinationEntityId": "merchant_usa_001"
  }
}

Resposta (a conversão fica no transaction):

{
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_euro_001",
    "type": "PAYMENT",
    "amount": 850.00,
    "currency": "EUR",
    "amountInUsd": 935.00,
    "exchangeRate": 1.10,
    "rateSource": "ms-provider",
    "status": "CREATED",
    "riskScore": 25,
    "flagged": false,
    "createdAt": "2024-10-28T15:00:01.000Z",
    "updatedAt": "2024-10-28T15:00:01.000Z"
  },
  "rulesExecutionSummary": null
}

Exemplos Completos de Requisição

Transferência PIX (Brasil)

curl -X POST http://api.gu1.ai/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "txn_pix_12345",
    "type": "TRANSFER",
    "status": "CREATED",
    "amount": 500.00,
    "currency": "BRL",
    "originEntityId": "customer_maria_001",
    "originName": "Maria Silva",
    "originCountry": "BR",
    "originDetails": {
      "deviceId": "device_123",
      "ipAddress": "189.123.45.67",
      "country": "BR",
      "city": "São Paulo",
      "paymentDetails": {
        "pixKey": "maria.silva@example.com",
        "pixType": "email",
        "bankName": "Banco do Brasil"
      }
    },
    "destinationEntityId": "merchant_loja_002",
    "destinationName": "Loja Online",
    "destinationCountry": "BR",
    "destinationDetails": {
      "merchantId": "MER_002",
      "mcc": "5411",
      "paymentDetails": {
        "accountNumber": "98765",
        "accountType": "merchant",
        "bankName": "Bradesco"
      }
    },
    "description": "Purchase at Online Store",
    "category": "retail",
    "metadata": {
      "storeId": "store_002",
      "orderId": "order_789"
    },
    "transactedAt": "2024-12-23T14:30:00Z",
    "executeRules": true
  }'

const response = await fetch('http://api.gu1.ai/transactions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    externalId: 'txn_pix_12345',
    type: 'transfer',
    status: 'CREATED',
    amount: 500.00,
    currency: 'BRL',
    originEntityId: 'customer_maria_001',
    originName: 'Maria Silva',
    originCountry: 'BR',
    originDetails: {
      deviceId: 'device_123',
      ipAddress: '189.123.45.67',
      country: 'BR',
      city: 'São Paulo',
      paymentDetails: {
        pixKey: 'maria.silva@example.com',
        pixType: 'email',
        bankName: 'Banco do Brasil'
      }
    },
    destinationEntityId: 'merchant_loja_002',
    destinationName: 'Loja Online',
    destinationCountry: 'BR',
    destinationDetails: {
      merchantId: 'MER_002',
      mcc: '5411',
      paymentDetails: {
        accountNumber: '98765',
        accountType: 'merchant',
        bankName: 'Bradesco'
      }
    },
    description: 'Purchase at Online Store',
    category: 'retail',
    metadata: {
      storeId: 'store_002',
      orderId: 'order_789'
    },
    transactedAt: new Date().toISOString(),
    executeRules: true
  })
});

const result = await response.json();
console.log(result);

import requests
from datetime import datetime

url = "http://api.gu1.ai/transactions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "externalId": "txn_pix_12345",
    "type": "TRANSFER",
    "status": "CREATED",
    "amount": 500.00,
    "currency": "BRL",
    "originEntityId": "customer_maria_001",
    "originName": "Maria Silva",
    "originCountry": "BR",
    "originDetails": {
        "deviceId": "device_123",
        "ipAddress": "189.123.45.67",
        "country": "BR",
        "city": "São Paulo",
        "paymentDetails": {
            "pixKey": "maria.silva@example.com",
            "pixType": "email",
            "bankName": "Banco do Brasil"
        }
    },
    "destinationEntityId": "merchant_loja_002",
    "destinationName": "Loja Online",
    "destinationCountry": "BR",
    "destinationDetails": {
        "merchantId": "MER_002",
        "mcc": "5411",
        "paymentDetails": {
            "accountNumber": "98765",
            "accountType": "merchant",
            "bankName": "Bradesco"
        }
    },
    "description": "Purchase at Online Store",
    "category": "retail",
    "metadata": {
        "storeId": "store_002",
        "orderId": "order_789"
    },
    "transactedAt": datetime.utcnow().isoformat() + "Z",
    "executeRules": True
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"Transaction ID: {result['transaction']['id']}")
print(f"Risk Score: {result['transaction']['riskScore']}")

Pagamento com Cartão

curl -X POST http://api.gu1.ai/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "txn_card_67890",
    "type": "PAYMENT",
    "amount": 1250.00,
    "currency": "USD",
    "originEntityId": "customer_john_003",
    "originName": "John Smith",
    "originCountry": "US",
    "originDetails": {
      "deviceId": "device_456",
      "deviceType": "desktop",
      "ipAddress": "198.51.100.42",
      "country": "US",
      "paymentDetails": {
        "cardLast4": "8765",
        "cardBrand": "Visa",
        "expiryMonth": "12",
        "expiryYear": "2027"
      }
    },
    "destinationEntityId": "merchant_electronics_001",
    "destinationName": "Electronics Store",
    "destinationCountry": "US",
    "destinationDetails": {
      "mcc": "5732",
      "merchantId": "MER_ELEC_001",
      "paymentDetails": {
        "accountNumber": "ACC123456",
        "accountType": "merchant"
      }
    },
    "description": "Laptop purchase",
    "category": "electronics",
    "metadata": {
      "sessionId": "sess_abc123",
      "isFirstTransaction": true
    },
    "executeRules": true
  }'

const response = await fetch('http://api.gu1.ai/transactions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    externalId: 'txn_card_67890',
    type: 'payment',
    amount: 1250.00,
    currency: 'USD',
    originEntityId: 'customer_john_003',
    originName: 'John Smith',
    originCountry: 'US',
    originDetails: {
      deviceId: 'device_456',
      deviceType: 'desktop',
      ipAddress: '198.51.100.42',
      country: 'US',
      paymentDetails: {
        cardLast4: '8765',
        cardBrand: 'Visa',
        expiryMonth: '12',
        expiryYear: '2027'
      }
    },
    destinationEntityId: 'merchant_electronics_001',
    destinationName: 'Electronics Store',
    destinationCountry: 'US',
    destinationDetails: {
      mcc: '5732',
      merchantId: 'MER_ELEC_001',
      paymentDetails: {
        accountNumber: 'ACC123456',
        accountType: 'merchant'
      }
    },
    description: 'Laptop purchase',
    category: 'electronics',
    metadata: {
      sessionId: 'sess_abc123',
      isFirstTransaction: true
    },
    executeRules: true
  })
});

const result = await response.json();
console.log(result);

import requests

url = "http://api.gu1.ai/transactions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "externalId": "txn_card_67890",
    "type": "PAYMENT",
    "amount": 1250.00,
    "currency": "USD",
    "originEntityId": "customer_john_003",
    "originName": "John Smith",
    "originCountry": "US",
    "originDetails": {
        "deviceId": "device_456",
        "deviceType": "desktop",
        "ipAddress": "198.51.100.42",
        "country": "US",
        "paymentDetails": {
            "cardLast4": "8765",
            "cardBrand": "Visa",
            "expiryMonth": "12",
            "expiryYear": "2027"
        }
    },
    "destinationEntityId": "merchant_electronics_001",
    "destinationName": "Electronics Store",
    "destinationCountry": "US",
    "destinationDetails": {
        "mcc": "5732",
        "merchantId": "MER_ELEC_001",
        "paymentDetails": {
            "accountNumber": "ACC123456",
            "accountType": "merchant"
        }
    },
    "description": "Laptop purchase",
    "category": "electronics",
    "metadata": {
        "sessionId": "sess_abc123",
        "isFirstTransaction": True
    },
    "executeRules": True
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"Transaction ID: {result['transaction']['id']}")
print(f"Status: {result['transaction']['status']}")

Transferência Multi-Moeda

curl -X POST http://api.gu1.ai/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "txn_euro_001",
    "type": "TRANSFER",
    "amount": 750.50,
    "currency": "EUR",
    "originEntityId": "user_alice_001",
    "originName": "Alice Martinez",
    "originCountry": "ES",
    "originDetails": {
      "deviceId": "device_789",
      "ipAddress": "88.22.15.10",
      "country": "ES",
      "city": "Madrid",
      "paymentDetails": {
        "accountNumber": "ES1234567890123456789012",
        "bankName": "Banco Santander",
        "accountType": "personal"
      }
    },
    "destinationEntityId": "user_bob_002",
    "destinationName": "Bob Johnson",
    "destinationCountry": "DE",
    "destinationDetails": {
      "country": "DE",
      "paymentDetails": {
        "accountNumber": "DE89370400440532013000",
        "bankName": "Deutsche Bank",
        "accountType": "personal"
      }
    },
    "description": "International transfer",
    "category": "p2p",
    "executeRules": true
  }'

Resposta

Especificação completa: Criar transação. A API retorna transaction como objeto (transação criada).

Resposta de Sucesso (201 Created)

{
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_pix_12345",
    "organizationId": "org_uuid",
    "type": "TRANSFER",
    "status": "CREATED",
    "amount": "500.00",
    "currency": "BRL",
    "amountInUsd": "100.00",
    "exchangeRate": "0.2000000000",
    "rateSource": "ms-provider",
    "rateTimestamp": "2024-12-23T14:30:00.000Z",
    "convertedAt": "2024-12-23T14:30:01.000Z",
    "originEntityId": "customer_maria_001",
    "originExternalId": null,
    "originName": "Maria Silva",
    "originCountry": "BR",
    "originDetails": {
      "deviceId": "device_123",
      "ipAddress": "189.123.45.67",
      "country": "BR",
      "city": "São Paulo",
      "paymentDetails": {
        "pixKey": "maria.silva@example.com",
        "pixType": "email",
        "bankName": "Banco do Brasil"
      }
    },
    "destinationEntityId": "merchant_loja_002",
    "destinationExternalId": null,
    "destinationName": "Loja Online",
    "destinationCountry": "BR",
    "destinationDetails": {
      "merchantId": "MER_002",
      "mcc": "5411",
      "paymentDetails": {
        "accountNumber": "98765",
        "accountType": "merchant",
        "bankName": "Bradesco"
      }
    },
    "riskScore": "25.50",
    "riskFactors": [
      {
        "factor": "velocity_check",
        "score": 15,
        "description": "3 transactions in the last hour"
      }
    ],
    "flagged": false,
    "description": "Purchase at Online Store",
    "category": "retail",
    "metadata": {
      "storeId": "store_002",
      "orderId": "order_789"
    },
    "transactedAt": "2024-12-23T14:30:00.000Z",
    "createdAt": "2024-12-23T14:30:01.000Z",
    "updatedAt": "2024-12-23T14:30:01.000Z"
  },
  "rulesExecutionSummary": {
    "rulesHit": [],
    "rulesNoHit": [],
    "actionsExecuted": {},
    "totalScore": 25
  }
}

Campos de Resposta

object

A transação criada com todos os seus dados incluindo:

id (string) - UUID interno do gu1
externalId (string) - Seu ID externo
type (enum) - Tipo de transação
status (enum) - Status da transação
amount (string) - Valor original (string numérica)
currency (string) - Código de moeda original (ISO 4217)
amountInUsd (string | null) - Valor convertido em USD
exchangeRate (string | null) - Taxa de câmbio usada (precisão: 10 decimais)
rateSource (string | null) - Fonte da taxa de câmbio
riskScore (string | null) - Pontuação de risco 0-100 (precisão: 2 decimais) se regras foram executadas
riskFactors (array) - Array de fatores de risco identificados
flagged (boolean) - Se a transação foi sinalizada para revisão
reason (string | null) - Motivo opcional do resultado (ex.: WITHOUT_REASON, INSUFFICIENT_FUNDS); padrão WITHOUT_REASON quando omitido

object

Na raiz da resposta. Presente apenas quando executeRules é true e o motor de regras foi executado. Resumo de quais regras deram match (hit) e quais não (no hit), ações executadas e pontuação total. Omitido quando executeRules é false. Estrutura completa e exemplo: Resumo de Execução de Regras.

rulesHit (array) - Regras cujas condições foram atendidas. Cada item: name, description, score, priority, category, status (ex. active, shadow), conditions (array de { field, value, operator? }), actions (alerts, suggestion, status, assignedUser).
rulesNoHit (array) - Regras avaliadas cujas condições não foram atendidas. Mesma estrutura que rulesHit (inclui ações configuradas, não executadas).
actionsExecuted (object) - Ações executadas agregadas de todas as regras que deram hit: alerts (array de { name?, type?, severity?, description? }), suggestion (BLOCK | SUSPEND | FLAG, maior peso), status (status da entidade aplicado, se houver), assignedUser ({ userId }, se houver), customKeys (array de strings, opcional) — chaves de ações personalizadas das regras que deram match (ex. require_kyc, flag_for_review). Presente quando alguma regra que deu match tem uma ação personalizada com chave; para integrações/workflows.
totalScore (number) - Soma do score de todas as regras que deram hit e não estão em status shadow.

Valores de Status da Transação

O status da transação segue um modelo de máquina de estados com estados abertos e fechados:

Estados Abertos (Podem Transitar)

Status	Descrição	Pode Transitar Para
`CREATED`	Transação criada (estado inicial)	PROCESSING, SUSPENDED, SENT, EXPIRED, DECLINED, SUCCESSFUL
`PROCESSING`	Transação em processamento	SUSPENDED, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFUL
`SUSPENDED`	Transação temporariamente suspensa	PROCESSING, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFUL

Estados Fechados (Finais)

Status	Descrição	Nota
`SENT`	Transação enviada/transmitida	Estado final - sem mais transições
`EXPIRED`	Transação expirada	Estado final - sem mais transições
`DECLINED`	Transação recusada/declinada	Estado final - sem mais transições
`REFUNDED`	Transação reembolsada/revertida	Estado final - sem mais transições
`SUCCESSFUL`	Transação concluída com sucesso	Estado final - sem mais transições

Importante: Uma vez que uma transação atinge um estado fechado, não pode transitar de volta para um estado aberto. Isso garante a integridade da transação e trilhas de auditoria adequadas.

Faixas de Pontuação de Risco

Pontuação de risco de 0 a 100 (armazenada com 2 decimais de precisão):

0-30: Risco baixo (verde)
31-60: Risco médio (amarelo)
61-80: Risco alto (laranja)
81-100: Risco crítico (vermelho)

Fontes de Taxa de Conversão de Moeda

O campo rateSource indica como a taxa de câmbio foi obtida:

ms-provider: Taxa em tempo real do microserviço de moeda (fonte primária)
cache-fallback: Taxa em cache (< 1h) quando serviço indisponível
no-conversion: Conversão não necessária (moeda já é USD)
null: Conversão falhou ou não é aplicável

Respostas de Erro

400 Bad Request - Erro de Validação

Exemplo 1: Campos obrigatórios faltando

{
  "error": "Validation failed",
  "details": [
    {
      "path": "externalId",
      "message": "Required",
      "code": "invalid_type"
    },
    {
      "path": "amount",
      "message": "Number must be greater than 0",
      "code": "too_small"
    }
  ]
}

Exemplo 2: paymentDetails inválidos para cartão (aninhado em originDetails)

{
  "error": "Validation failed",
  "details": [
    {
      "path": "originDetails.paymentDetails.cardLast4",
      "message": "Card last 4 digits must be exactly 4 characters",
      "code": "invalid_length"
    },
    {
      "path": "originDetails.paymentDetails.cardBrand",
      "message": "Invalid card brand",
      "code": "invalid_string"
    }
  ]
}

Exemplo 3: Detalhes PIX inválidos (aninhado em originDetails)

{
  "error": "Validation failed",
  "details": [
    {
      "path": "originDetails.paymentDetails.pixKey",
      "message": "Required",
      "code": "invalid_type"
    },
    {
      "path": "originDetails.paymentDetails.pixType",
      "message": "Invalid PIX type",
      "code": "invalid_enum_value"
    },
    {
      "path": "originDetails.paymentDetails.bankName",
      "message": "String must contain at least 1 character(s)",
      "code": "too_small"
    }
  ]
}

Exemplo 4: Endereço IP inválido em originDetails

{
  "error": "Validation failed",
  "details": [
    {
      "path": "originDetails.ipAddress",
      "message": "Invalid IP address format",
      "code": "invalid_string"
    },
    {
      "path": "originDetails.country",
      "message": "Country must be ISO 2 letter code",
      "code": "invalid_length"
    }
  ]
}

400 Bad Request - Organização Faltando

{
  "error": "Organization ID and User ID are required"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Failed to create transaction",
  "details": "Database connection error"
}

Próximos Passos

Configuração de Regras

Aprenda a criar regras

Detecção de Fraude

Exemplos de detecção de fraude

Monitoramento AML

Regras de conformidade AML

Visão Geral

Voltar para visão geral

Monitoramento de Comerciantes Alterar Status da Transação

⌘I

​Referência canónica do endpoint

​Endpoint: Criar Transação

​Autenticação

​Cabeçalhos Obrigatórios

​Corpo da Requisição

​tags (object) - Sistema de Categorização Chave-Valor

​Outros Campos de Metadata:

​Métodos de Pagamento

​Tipos de Conta

​Códigos MCC

​Tags e Metadata

​Suporte Multi-Moeda

​Como Funciona

​Moedas Suportadas

​Fontes de Taxa de Câmbio

​Campos de resposta

​Usando Valores Convertidos em Regras

​Tratamento de Erros

​Exemplo: Transação Multi-Moeda

​Exemplos Completos de Requisição

​Transferência PIX (Brasil)

​Pagamento com Cartão

​Transferência Multi-Moeda

​Resposta

​Resposta de Sucesso (201 Created)

​Campos de Resposta

​Valores de Status da Transação

​Estados Abertos (Podem Transitar)

​Estados Fechados (Finais)

​Faixas de Pontuação de Risco

​Fontes de Taxa de Conversão de Moeda

​Respostas de Erro

​400 Bad Request - Erro de Validação

​400 Bad Request - Organização Faltando

​401 Unauthorized

​500 Internal Server Error

​Próximos Passos

Configuração de Regras

Detecção de Fraude

Monitoramento AML

Visão Geral

Referência canónica do endpoint

Endpoint: Criar Transação

Autenticação

Cabeçalhos Obrigatórios

Corpo da Requisição

`tags` (object) - Sistema de Categorização Chave-Valor

Outros Campos de Metadata:

Métodos de Pagamento

Tipos de Conta

Códigos MCC

Tags e Metadata

Suporte Multi-Moeda

Como Funciona

Moedas Suportadas

Fontes de Taxa de Câmbio

Campos de resposta

Usando Valores Convertidos em Regras

Tratamento de Erros

Exemplo: Transação Multi-Moeda

Exemplos Completos de Requisição

Transferência PIX (Brasil)

Pagamento com Cartão

Transferência Multi-Moeda

Resposta

Resposta de Sucesso (201 Created)

Campos de Resposta

Valores de Status da Transação

Estados Abertos (Podem Transitar)

Estados Fechados (Finais)

Faixas de Pontuação de Risco

Fontes de Taxa de Conversão de Moeda

Respostas de Erro

400 Bad Request - Erro de Validação

400 Bad Request - Organização Faltando

401 Unauthorized

500 Internal Server Error

Próximos Passos