Skip to main content

Payment Object

Overview​

The payment object contains detailed information about payment methods used in e-commerce events, enabling comprehensive payment tracking, financial analytics, and payment performance optimization. This object is used within e-commerce events to track payment amounts, payment types, transaction methods, and payment-related data across the customer journey.

Each payment object represents a single payment method or payment portion with its associated amount, payment type, transaction details, and custom properties that enable precise financial tracking and payment analytics.

Core Structure​

The payment object consists of several logical groups of properties:

  • Core Properties - Essential payment identification and amount information
  • Payment Classification - Payment types and method categories
  • Transaction Details - Payment processing and transaction metadata

Complete Reference​

payments[0] object

name string recommended

info

Payment method name.

name: "PAYMENT_NAME"

value number required

info

Amount paid with this payment method

value: 12.99

id string

info

Payment method internal identifier

id: "PAYMENT_INTERNAL_ID"

type string

info

Payment type (e.g., "card", "paypal", "bank_transfer", "gift_card")

type: "PAYMENT_TYPE"

Implementation Examples​

{
  // Credit card payment
  name: "Credit Card - Visa",
  value: 299.99,
  id: "CC_VISA_4532",
  type: "card"
}

Payment Types​

The type field categorizes payment methods for analytics and processing:

Credit and debit card payments:

{
  type: "card",              // Generic credit/debit card
  type: "credit_card",       // Credit card specifically
  type: "debit_card",        // Debit card specifically
  type: "business_card",     // Business credit card
  type: "prepaid_card"       // Prepaid card
}

Payment Method Examples​

Single Payment Methods​

{
  name: "Visa ending in 4532",
  value: 359.99,
  id: "CC_VISA_4532_001",
  type: "card"
}

Split Payment Scenarios​

[
  {
    name: "Gift Card Balance",
    value: 100.00,
    id: "GC_BALANCE_001",
    type: "gift_card"
  },
  {
    name: "Credit Card - Remaining",
    value: 249.99,
    id: "CC_REMAINING_001",
    type: "card"
  }
]

Regional Payment Methods​

[
  {
    name: "SEPA Direct Debit",
    value: 199.99,
    id: "SEPA_DD_001",
    type: "sepa"
  },
  {
    name: "iDEAL Netherlands",
    value: 89.99,
    id: "IDEAL_NL_001",
    type: "online_banking"
  },
  {
    name: "Klarna Pay Later",
    value: 299.99,
    id: "KLARNA_001",
    type: "buy_now_pay_later"
  }
]

Payment Processing Integration​

Payment Gateway Integration​

// Stripe payment integration
{
  name: "Credit Card via Stripe",
  value: 199.99,
  id: "pi_stripe_12345",
  type: "card",
  properties: {
    gateway: "stripe",
    payment_intent_id: "pi_1234567890",
    card_brand: "visa",
    last_four: "4242",
    country: "US"
  }
}

// PayPal payment integration
{
  name: "PayPal Express Checkout",
  value: 299.99,
  id: "PAYID-EXAMPLE123",
  type: "paypal",
  properties: {
    gateway: "paypal",
    payer_id: "EXAMPLE123456",
    transaction_id: "TXN123456789"
  }
}

Buy Now Pay Later (BNPL) Integration​

// Klarna BNPL payment
{
  name: "Klarna - Pay in 4",
  value: 399.99,
  id: "KLARNA_ORDER_001",
  type: "buy_now_pay_later",
  properties: {
    provider: "klarna",
    payment_plan: "pay_in_4",
    installments: 4,
    first_payment: 99.99,
    remaining_payments: 3
  }
}

// Afterpay BNPL payment
{
  name: "Afterpay - 4 Installments",
  value: 199.99,
  id: "AFTERPAY_001",
  type: "buy_now_pay_later",
  properties: {
    provider: "afterpay",
    installment_amount: 49.99,
    payment_schedule: "bi_weekly"
  }
}

Usage in E-commerce Events​

The payment object is used in e-commerce events within the payments array:

Integration Patterns​

Single Payment Method​

// Simple single payment
{
  payments: [
    {
      name: "Credit Card Payment",
      value: 299.99,
      id: "CC_PAYMENT_001",
      type: "card"
    }
  ]
}

Multiple Payment Methods​

// Split payment across multiple methods
{
  payments: [
    {
      name: "Gift Card",
      value: 50.00,
      id: "GC_001",
      type: "gift_card"
    },
    {
      name: "Credit Card - Balance",
      value: 249.99,
      id: "CC_BALANCE_001",
      type: "card"
    }
  ]
}

Subscription Payments​

// Recurring subscription payment
{
  payments: [
    {
      name: "Monthly Subscription - Auto Pay",
      value: 29.99,
      id: "SUB_MONTHLY_001",
      type: "card",
      properties: {
        subscription_id: "sub_12345",
        billing_cycle: "monthly",
        auto_renewal: true,
        next_billing_date: "2024-09-15"
      }
    }
  ]
}

Security and Compliance​

PCI Compliance Considerations​

// Safe payment data handling
{
  name: "Credit Card - Visa",
  value: 199.99,
  id: "CC_SAFE_001",
  type: "card",
  // DO NOT include full card numbers, CVV, or sensitive data
  properties: {
    last_four: "4242",      // Last 4 digits only
    card_brand: "visa",     // Brand is safe
    exp_month: "12",        // Expiry is generally safe
    exp_year: "2025"        // But avoid if possible
  }
}

Data Privacy Best Practices​

// Privacy-compliant payment tracking
{
  name: "Digital Wallet Payment",
  value: 159.99,
  id: "WALLET_HASHED_001",  // Use hashed or tokenized IDs
  type: "digital_wallet",
  properties: {
    payment_provider: "apple_pay",
    transaction_status: "completed",
    // Avoid storing personal financial details
    authorization_method: "biometric"
  }
}

Best Practices​

Data Quality​

  • Accurate Amounts - Ensure payment values reflect actual transaction amounts
  • Consistent Naming - Use standardized payment method names across events
  • Complete Transaction Data - Include payment IDs for transaction reconciliation
  • Type Classification - Use appropriate payment types for accurate reporting

Security​

  • PCI Compliance - Never store sensitive payment card data
  • Data Minimization - Collect only necessary payment information
  • Tokenization - Use payment tokens instead of raw card data
  • Secure Transmission - Always use HTTPS for payment data transmission

Performance Optimization​

  • Essential Data First - Prioritize required fields for fast checkout processing
  • Payment Method Analytics - Track payment method performance and preferences
  • Conversion Optimization - Monitor payment method impact on conversion rates
  • Fraud Prevention - Include relevant data for fraud detection systems

Customer Experience​

  • Clear Method Names - Use descriptive payment method names
  • Payment Options - Support multiple payment methods for customer preference
  • Split Payment Support - Enable flexible payment combinations
  • Error Handling - Gracefully handle payment failures and retries