Skip to main content

​
Overview

Payment methods in Güeno are represented as entities of type payment_method. This allows you to track credit cards, bank accounts, wallets, and other payment instruments associated with persons or companies.
Payment methods are created using the universal /entities endpoint with entityType: "payment_method".

​
What is a Payment Method Entity?

A payment method entity represents any financial instrument used for transactions:
  • Credit Cards - Visa, Mastercard, Amex, etc.
  • Debit Cards - Bank-issued debit cards
  • Bank Accounts - Checking, savings accounts
  • Digital Wallets - PayPal, Apple Pay, Google Pay, etc.
  • Cryptocurrency Wallets - Bitcoin, Ethereum addresses

​
Key Features

​
Entity Relationships

Payment methods can be linked to other entities:
  • Owned by - Link to the person or company owner
  • Used in - Link to transactions where this payment method was used
  • Associated with - Link to devices used for transactions

​
Risk Analysis

Payment methods can be analyzed for fraud detection:
  • Transaction velocity monitoring
  • Geographic anomaly detection
  • Device fingerprinting correlation
  • Historical usage patterns

​
Use Cases

  1. Fraud Detection - Detect suspicious payment method usage patterns
  2. Card Verification - Validate card details and ownership
  3. Account Monitoring - Track unusual account activity
  4. Transaction Tracking - Link transactions to payment sources
  5. Multi-account Detection - Identify shared payment methods across users

​
Data Structure

Payment method entities contain: 
{
  "entityType": "payment_method",
  "entityData": {
    "paymentMethod": {
      "type": "credit_card",           // Type of payment method
      "last4": "4242",                  // Last 4 digits
      "brand": "visa",                  // Card brand
      "expiryMonth": "12",              // Expiration month
      "expiryYear": "2025",             // Expiration year
      "holderName": "John Doe",         // Cardholder name
      "issuerCountry": "BR",            // Issuing country
      "bin": "424242",                  // Bank Identification Number
      "fingerprint": "abc123xyz",       // Unique fingerprint
      "funding": "credit",              // Funding type (credit/debit)
      "network": "visa"                 // Payment network
    }
  },
  "relationships": [
    {
      "targetEntityId": "person-uuid-123",
      "relationshipType": "owns",
      "strength": 1.0
    }
  ]
}

​
Payment Method Types

​
Credit Card

{
  "type": "credit_card",
  "brand": "visa",
  "last4": "4242",
  "expiryMonth": "12",
  "expiryYear": "2025",
  "holderName": "John Doe",
  "issuerCountry": "BR",
  "bin": "424242",
  "funding": "credit"
}

​
Bank Account

{
  "type": "bank_account",
  "accountNumber": "12345-6",
  "accountType": "checking",
  "bank": "Banco do Brasil",
  "currency": "BRL",
  "routingNumber": "001"
}

​
Digital Wallet

{
  "type": "digital_wallet",
  "provider": "paypal",
  "email": "user@example.com",
  "accountId": "paypal-12345"
}

​
Cryptocurrency Wallet

{
  "type": "crypto_wallet",
  "currency": "BTC",
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "network": "bitcoin"
}

​
API Endpoints

Payment method entities use the standard entity endpoints:

​
Common Patterns

​
Creating a Payment Method for a Person

const response = await fetch('http://api.gu1.ai/entities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    entityType: 'payment_method',
    entityData: {
      paymentMethod: {
        type: 'credit_card',
        last4: '4242',
        brand: 'visa',
        expiryMonth: '12',
        expiryYear: '2025',
        holderName: 'John Doe'
      }
    },
    relationships: [
      {
        targetEntityId: 'person-uuid-123',
        relationshipType: 'owns',
        strength: 1.0
      }
    ]
  })
});

​
Checking Payment Method Usage

Find all transactions using a specific payment method: 
const response = await fetch(
  `http://api.gu1.ai/entities?entityType=transaction&relationshipWith=${paymentMethodId}`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

​
See Also