Payment Methods Overview

Overview

Payment methods in Gu1 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

Fraud Detection - Detect suspicious payment method usage patterns
Card Verification - Validate card details and ownership
Account Monitoring - Track unusual account activity
Transaction Tracking - Link transactions to payment sources
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:

Create Payment Method - Create a new payment method entity
Get Payment Method - Retrieve payment method details
Update Payment Method - Update payment method information
List Payment Methods - List all payment methods
Analyze Payment Method - Run risk analysis on payment method

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'
    }
  }
);

​Overview

​What is a Payment Method Entity?

​Key Features

​Entity Relationships

​Risk Analysis

​Use Cases

​Data Structure

​Payment Method Types

​Credit Card

​Bank Account

​Digital Wallet

​Cryptocurrency Wallet

​API Endpoints

​Common Patterns

​Creating a Payment Method for a Person

​Checking Payment Method Usage

​See Also

Overview

What is a Payment Method Entity?

Key Features

Entity Relationships

Risk Analysis

Use Cases

Data Structure

Payment Method Types

Credit Card

Bank Account

Digital Wallet

Cryptocurrency Wallet

API Endpoints

Common Patterns

Creating a Payment Method for a Person

Checking Payment Method Usage

See Also