SynthesQ Docs

Appearance

Payment Processing ​

Overview ​

Payment processing in SynthesQ handles the complete payment lifecycle from creation through completion. This guide covers creating payments, payment methods, gateway integration, payment authorization and capture, and processing workflows.

Table of Contents ​

Payment Structure ​

Core Payment Fields ​

Payment Identity:

  • payment_number - Unique identifier (e.g., "PAY-12345678")
  • id - Internal database ID
  • type - Payment type (full_payment, partial_payment, deposit, refund)
  • method - Payment method (credit_card, debit_card, bank_transfer, etc.)

Financial Details:

  • amount - Total payment amount
  • currency - Currency code (default: USD)
  • net_amount - Amount after fees
  • processing_fee - Processing/transaction fee
  • gateway_fee - Payment gateway fee
  • total_fee - Combined fees

Relationships:

  • customer_id - Reference to customer
  • invoice_id - Reference to invoice (if applicable)
  • order_id - Reference to order (if applicable)

Transaction Details:

  • transaction_id - Internal transaction ID
  • gateway_transaction_id - Gateway's transaction ID
  • authorization_code - Authorization code from gateway
  • reference_number - External reference number

Gateway Information:

  • gateway_provider - Gateway name (stripe, paypal, authorize_net, etc.)
  • gateway_response - Full gateway response (JSON)
  • gateway_metadata - Additional gateway data

Risk Management:

  • risk_score - Fraud risk score (0-100)
  • fraud_flags - Array of fraud indicators

Status Tracking:

  • status - Current payment status
  • payment_date - When payment was initiated
  • processed_at - When payment was processed
  • completed_at - When payment was completed
  • failed_at - When payment failed (if applicable)

Settlement:

  • batch_id - Batch identifier
  • settlement_id - Settlement identifier
  • reconciliation_id - Reconciliation identifier
  • settled_at - When payment settled

Creating Payments ​

Create Payment Record ​

Endpoint: POST /api/v1/sales/payments

Authentication: Required (Bearer token)

Purpose: Create payment record for processing

Request Body:

json
{
  "customer_id": 42,
  "invoice_id": 456,
  "amount": 347.47,
  "currency": "USD",
  "method": "credit_card",
  "type": "full_payment",
  "payment_date": "2025-12-18",
  "reference_number": "CUST-REF-789",
  "notes": "Payment for invoice INV-20251217-001"
}

Response (201 Created):

json
{
  "message": "Payment created successfully",
  "data": {
    "id": 789,
    "payment_number": "PAY-12345678",
    "status": "pending",
    "type": "full_payment",
    "method": "credit_card",
    "amount": 347.47,
    "currency": "USD",
    "net_amount": 337.47,
    "processing_fee": 10.00,
    "gateway_fee": 0.00,
    "total_fee": 10.00,
    "customer": {
      "id": 42,
      "customer_number": "CUST-00042",
      "company_name": "Acme Corporation"
    },
    "invoice": {
      "id": 456,
      "invoice_number": "INV-20251217-001"
    },
    "payment_date": "2025-12-18T00:00:00Z",
    "risk_score": 15.5,
    "created_at": "2025-12-18T09:00:00Z"
  }
}

Create Payment with Gateway Details ​

json
{
  "customer_id": 42,
  "invoice_id": 456,
  "amount": 347.47,
  "method": "credit_card",
  "gateway_provider": "stripe",
  "gateway_metadata": {
    "card_brand": "visa",
    "card_last4": "4242",
    "card_exp_month": 12,
    "card_exp_year": 2026,
    "cardholder_name": "John Doe"
  }
}

Payment Methods ​

Available Payment Methods ​

Endpoint: GET /api/v1/sales/payments/payment-methods

Authentication: Required (Bearer token)

Response (200 OK):

json
{
  "data": {
    "available_methods": [
      {
        "method": "credit_card",
        "label": "Credit Card",
        "enabled": true,
        "supported_brands": ["visa", "mastercard", "amex", "discover"],
        "processing_fee_percentage": 2.9,
        "processing_fee_fixed": 0.30,
        "settlement_days": 2
      },
      {
        "method": "debit_card",
        "label": "Debit Card",
        "enabled": true,
        "processing_fee_percentage": 1.5,
        "processing_fee_fixed": 0.25,
        "settlement_days": 1
      },
      {
        "method": "bank_transfer",
        "label": "Bank Transfer (ACH)",
        "enabled": true,
        "processing_fee_percentage": 0.8,
        "processing_fee_fixed": 0.00,
        "settlement_days": 5
      },
      {
        "method": "wire_transfer",
        "label": "Wire Transfer",
        "enabled": true,
        "processing_fee_percentage": 0.0,
        "processing_fee_fixed": 0.00,
        "settlement_days": 1
      },
      {
        "method": "check",
        "label": "Check",
        "enabled": true,
        "processing_fee_percentage": 0.0,
        "processing_fee_fixed": 0.00,
        "settlement_days": 7
      },
      {
        "method": "cash",
        "label": "Cash",
        "enabled": true,
        "processing_fee_percentage": 0.0,
        "processing_fee_fixed": 0.00,
        "settlement_days": 0
      },
      {
        "method": "paypal",
        "label": "PayPal",
        "enabled": true,
        "processing_fee_percentage": 3.5,
        "processing_fee_fixed": 0.35,
        "settlement_days": 2
      }
    ]
  }
}

Payment Method Details ​

Credit Card:

  • Processing Fee: 2.9% + $0.30
  • Settlement: 2 business days
  • Supports: Visa, Mastercard, Amex, Discover
  • Security: 3D Secure, CVV verification

Debit Card:

  • Processing Fee: 1.5% + $0.25
  • Settlement: 1 business day
  • Lower fraud risk than credit cards

Bank Transfer (ACH):

  • Processing Fee: 0.8%
  • Settlement: 5 business days
  • Preferred for large transactions

Wire Transfer:

  • Processing Fee: None (customer pays bank fees)
  • Settlement: Same day or next day
  • Preferred for international payments

Check:

  • Processing Fee: None
  • Settlement: 7-10 business days (includes clearance)
  • Risk of bounced checks

Cash:

  • Processing Fee: None
  • Settlement: Immediate
  • In-person only

PayPal:

  • Processing Fee: 3.5% + $0.35
  • Settlement: 2 business days
  • Customer protection included

Processing Payments ​

Process Payment ​

Endpoint: POST /api/v1/sales/payments/{payment}/process

Authentication: Required (Bearer token)

Purpose: Process payment through payment gateway

Prerequisites:

  • Payment must be in pending status
  • Payment method must be configured
  • Gateway credentials must be valid
  • Sufficient funds/credit available

Request Body (Credit Card):

json
{
  "payment_method_token": "pm_1234567890abcdef",
  "cardholder_name": "John Doe",
  "billing_address": {
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "cvv": "123",
  "save_payment_method": false,
  "capture_immediately": true
}

Response (200 OK):

json
{
  "message": "Payment processed successfully",
  "data": {
    "id": 789,
    "payment_number": "PAY-12345678",
    "status": "completed",
    "amount": 347.47,
    "method": "credit_card",
    "transaction_id": "TXN-987654321",
    "gateway_transaction_id": "ch_1234567890",
    "authorization_code": "AUTH-456789",
    "processed_at": "2025-12-18T09:15:00Z",
    "completed_at": "2025-12-18T09:15:30Z",
    "gateway_provider": "stripe",
    "gateway_response": {
      "id": "ch_1234567890",
      "status": "succeeded",
      "amount": 34747,
      "currency": "usd",
      "payment_method": "card_visa",
      "receipt_url": "https://pay.stripe.com/receipts/..."
    },
    "risk_assessment": {
      "risk_score": 15.5,
      "risk_level": "low",
      "fraud_flags": []
    }
  }
}

Processing Steps:

  1. Validate payment method details
  2. Perform fraud/risk checks
  3. Contact payment gateway
  4. Authorize transaction
  5. Capture funds (if immediate capture)
  6. Update payment status
  7. Update invoice balance
  8. Send receipt to customer

Process with Bank Transfer ​

Request Body:

json
{
  "bank_account": {
    "account_holder": "Acme Corporation",
    "account_number": "****6789",
    "routing_number": "021000021",
    "account_type": "checking"
  },
  "verification_method": "micro_deposits",
  "capture_immediately": false
}

Response:

json
{
  "status": "processing",
  "verification_required": true,
  "verification_method": "micro_deposits",
  "estimated_completion": "2025-12-20",
  "message": "Micro-deposits will be sent for verification. Process will complete in 2-3 business days."
}

Processing Errors ​

Insufficient Funds:

json
{
  "error": "Payment declined",
  "message": "Insufficient funds",
  "gateway_error_code": "insufficient_funds",
  "decline_code": "insufficient_funds",
  "status": "failed",
  "failed_at": "2025-12-18T09:15:00Z"
}

Invalid Card:

json
{
  "error": "Payment declined",
  "message": "Card number is invalid",
  "gateway_error_code": "invalid_card_number",
  "decline_code": "invalid_number",
  "status": "failed"
}

Fraud Detection:

json
{
  "error": "Payment blocked",
  "message": "Transaction flagged by fraud detection",
  "risk_score": 85.5,
  "risk_level": "high",
  "fraud_flags": [
    "unusual_location",
    "high_velocity",
    "mismatched_billing"
  ],
  "status": "failed",
  "requires_manual_review": true
}

Payment Authorization ​

Authorize Payment (Without Capture) ​

Purpose: Reserve funds without immediately charging customer

Request Body:

json
POST /api/v1/sales/payments
{
  "customer_id": 42,
  "invoice_id": 456,
  "amount": 347.47,
  "method": "credit_card",
  "authorization_only": true,
  "capture_immediately": false,
  "authorization_hold_days": 7
}

Response:

json
{
  "data": {
    "id": 789,
    "status": "authorized",
    "amount": 347.47,
    "authorization_code": "AUTH-456789",
    "authorization_expires_at": "2025-12-25T09:15:00Z",
    "funds_reserved": true,
    "capture_required_by": "2025-12-25T09:15:00Z"
  }
}

Use Cases:

  • Reserve funds before shipping products
  • Hold deposits for services
  • Verify payment method validity
  • Pre-authorize large transactions

Capturing Payments ​

Capture Authorized Payment ​

Endpoint: POST /api/v1/sales/payments/{payment}/capture

Authentication: Required (Bearer token)

Purpose: Capture previously authorized payment

Prerequisites:

  • Payment must be in authorized status
  • Authorization must not be expired
  • Capture amount ≤ authorized amount

Request Body (Full Capture):

json
{
  "amount": 347.47,
  "notes": "Order shipped - capturing full amount"
}

Response (200 OK):

json
{
  "message": "Payment captured successfully",
  "data": {
    "id": 789,
    "payment_number": "PAY-12345678",
    "status": "completed",
    "amount": 347.47,
    "captured_amount": 347.47,
    "authorization_code": "AUTH-456789",
    "transaction_id": "TXN-987654321",
    "captured_at": "2025-12-18T14:30:00Z",
    "completed_at": "2025-12-18T14:30:00Z"
  }
}

Partial Capture ​

Request Body:

json
{
  "amount": 300.00,
  "release_remaining": false,
  "notes": "Partial shipment - capturing $300 of $347.47 authorized"
}

Response:

json
{
  "data": {
    "status": "partially_captured",
    "captured_amount": 300.00,
    "remaining_authorized": 47.47,
    "can_capture_more": true
  }
}

Void Authorization ​

Endpoint: POST /api/v1/sales/payments/{payment}/void

Purpose: Cancel authorization and release reserved funds

Request Body:

json
{
  "void_reason": "Customer cancelled order before shipment",
  "notify_customer": true
}

Response:

json
{
  "message": "Payment authorization voided successfully",
  "data": {
    "id": 789,
    "status": "voided",
    "voided_at": "2025-12-18T15:00:00Z",
    "funds_released": true
  }
}

Payment Status Lifecycle ​

Status Flow ​

Pending → Processing → Completed

  • Normal successful flow

Pending → Failed

  • Declined, insufficient funds, invalid card

Pending → Authorized → Completed

  • Authorization then capture flow

Pending → Authorized → Voided

  • Authorization cancelled before capture

Completed → Refunded

  • Full refund issued

Completed → Partially Refunded

  • Partial refund issued

Completed → Disputed

  • Customer disputes charge (chargeback)

Payment Statuses ​

Pending:

  • Initial state
  • Awaiting processing
  • No funds moved

Processing:

  • Being processed by gateway
  • Communication in progress
  • Funds authorization in process

Authorized:

  • Funds reserved but not captured
  • Customer cannot use reserved amount
  • Must capture within hold period

Completed:

  • Payment successful
  • Funds transferred
  • Invoice updated
  • Receipt sent

Failed:

  • Payment declined or error
  • Reason documented
  • Customer notified

Cancelled:

  • Payment cancelled by user
  • Before processing completed
  • Funds not moved

Voided:

  • Authorization cancelled
  • Funds released
  • Cannot be captured

Refunded:

  • Full refund issued
  • Funds returned to customer
  • Original payment reversed

Partially Refunded:

  • Partial refund issued
  • Some funds returned
  • Remaining amount settled

Disputed:

  • Customer disputed charge
  • Chargeback initiated
  • Under review

Gateway Integration ​

Supported Payment Gateways ​

Stripe:

json
{
  "gateway_provider": "stripe",
  "gateway_config": {
    "publishable_key": "pk_live_...",
    "webhook_secret": "whsec_..."
  }
}

PayPal:

json
{
  "gateway_provider": "paypal",
  "gateway_config": {
    "client_id": "...",
    "client_secret": "...",
    "mode": "live"
  }
}

Authorize.Net:

json
{
  "gateway_provider": "authorize_net",
  "gateway_config": {
    "api_login_id": "...",
    "transaction_key": "...",
    "sandbox": false
  }
}

Gateway Response Handling ​

All gateway responses stored in gateway_response field:

json
{
  "gateway_response": {
    "id": "ch_1234567890",
    "object": "charge",
    "amount": 34747,
    "currency": "usd",
    "status": "succeeded",
    "payment_method": "card",
    "receipt_url": "https://...",
    "created": 1702896900
  }
}

Best Practices ​

  1. Always Authorize First: For large transactions, authorize then capture after shipment

  2. Validate Before Processing: Check customer details, amounts, and payment methods before processing

  3. Handle Errors Gracefully: Provide clear error messages to customers for declined payments

  4. Store Minimal Card Data: Never store full card numbers or CVV codes

  5. Use Tokenization: Use payment gateway tokens instead of raw card data

  6. Monitor Risk Scores: Review high-risk transactions manually before processing

  7. Capture Promptly: Capture authorized payments quickly (within 7 days typically)

  8. Send Receipts: Always send payment receipts to customers

  9. Track Settlements: Monitor settlement status for accounting reconciliation

  10. Test Thoroughly: Use gateway sandbox/test modes before going live

Documentation for SynthesQ CRM/ERP Platform

Copyright © 2025 SynthesQ