Payment Processing

Architecture Overview

DoorStax uses a multi-merchant payment architecture. The platform holds master credentials with Kadima Gateway, while each property manager operates under their own merchant account. Payments are routed to the appropriate merchant based on the property manager associated with the tenant's lease.

{
  "pmId": "pm_001",
  "merchantId": "mid_kadima_abc",
  "merchantStatus": "APPROVED",
  "processingCurrency": "USD",
  "supportedMethods": ["CARD", "ACH"],
  "cardSurchargeRate": 3.25,
  "achFeeAmount": 250,
  "applicationApprovedAt": "2025-01-10T00:00:00.000Z"
}

Card Payment Flow

Card payments use Kadima's vault tokenization system. The tenant's card is stored as a vault token on first use. Subsequent payments reference the vault token viamerchantCreateSaleFromVault to process charges without re-entering card details.

{
  "merchantId": "mid_kadima_abc",
  "vaultToken": "vtk_card_9876",
  "amount": 155000,
  "currency": "USD",
  "surcharge": 5038,
  "totalCharge": 160038,
  "description": "Rent payment - February 2025",
  "metadata": {
    "tenantId": "tnt_012",
    "leaseId": "lea_xyz789",
    "paymentType": "RENT"
  }
}

ACH Payment Flow

ACH payments use vault bank account tokens for direct debit from the tenant's checking or savings account. ACH transactions typically settle in 3-5 business days.

{
  "merchantId": "mid_kadima_abc",
  "vaultToken": "vtk_ach_5432",
  "amount": 150000,
  "currency": "USD",
  "achFee": 250,
  "totalCharge": 150250,
  "accountType": "CHECKING",
  "description": "Rent payment - February 2025",
  "metadata": {
    "tenantId": "tnt_012",
    "leaseId": "lea_xyz789",
    "paymentType": "RENT"
  }
}

Autopay Engine

Tenants can enroll in autopay to automatically charge their saved payment method on the rent due date. The system sends pre-charge notifications 3 days before processing and handles failures with automatic retries.

Fee Calculation

Processing fees are calculated based on the payment method. Card payments incur a surcharge of 3.25% added to the total. ACH fees follow a cascade: property-level override, then owner-level override, then the system default.

Outstanding Charges

When a tenant logs into their dashboard, they see all outstanding charges alongside their regular rent. This includes tenant-payable expenses, late fees, and any other non-rent charges. The tenant can pay all charges in a single transaction or select individual items.

Payment Void & Write-Off

Property managers can void a payment (before settlement) or write off an outstanding balance. Both actions require a reason and create a corresponding ledger entry. If the payment was tied to an expense, the expense record is updated to reflect the change.

{
  "paymentId": "pay_abc123",
  "action": "VOID",
  "reason": "Duplicate payment processed in error",
  "initiatedBy": "usr_pm001",
  "ledgerEntry": {
    "type": "VOID",
    "amount": -150000,
    "description": "Void: Duplicate payment"
  }
}

Receipt PDF Generation

A PDF receipt is automatically generated for every successful payment. The receipt includes the payment amount, method, date, property address, unit number, and a unique confirmation number. Receipts are available for download from the tenant dashboard and are also attached to the payment confirmation email.

Merchant Approval Guard

Payments are blocked until the property manager's merchant application has been approved by Kadima. The system checks the merchant status before every payment attempt and returns a clear error if the merchant is not yet approved.

API Reference

Payment endpoints handle the full transaction lifecycle from charge to settlement.