Invoice Payments

Track and manage invoice payments, including partial payments and payment history.

Overview

Monitor and record invoice payments:

• 💰 Full payments - Complete invoice settlement
• 📊 Partial payments - Accept payment installments
• 📝 Payment history - Track all payment attempts
• 🔄 Auto-reconciliation - Match payments to invoices
• 📧 Payment receipts - Automatic confirmation emails

Record Payment

Endpoint

POST /api/v1/invoices/:invoiceId/payment

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/payment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "paymentMethod": "card",
    "card": {
      "number": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2027",
      "cvv": "123"
    }
  }'

Response:

{
  "success": true,
  "data": {
    "paymentId": "pmt_xyz789",
    "invoiceId": "inv_abc123",
    "amount": 500.00,
    "status": "paid",
    "remainingBalance": 0.00,
    "paidAt": "2026-01-28T14:00:00Z",
    "transactionId": "txn_456"
  }
}

Partial Payment

Accept partial payment on invoice:

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/payment \
  -d '{
    "amount": 250.00,
    "paymentMethod": "card"
  }'

Response:

{
  "success": true,
  "data": {
    "paymentId": "pmt_partial_123",
    "invoiceId": "inv_abc123",
    "amount": 250.00,
    "totalAmount": 500.00,
    "paidAmount": 250.00,
    "remainingBalance": 250.00,
    "status": "partially_paid",
    "paidAt": "2026-01-28T14:00:00Z"
  }
}

Payment Methods

Credit Card

{
  "paymentMethod": "card",
  "card": {
    "number": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "2027",
    "cvv": "123"
  }
}

ACH/Bank Transfer

{
  "paymentMethod": "ach",
  "bankAccount": {
    "accountNumber": "123456789",
    "routingNumber": "987654321",
    "accountType": "checking"
  }
}

Saved Payment Method

{
  "paymentMethod": "saved",
  "paymentMethodId": "pm_saved_123"
}

External Payment

Record payment made outside the system:

{
  "paymentMethod": "external",
  "externalPaymentDetails": {
    "method": "check",
    "checkNumber": "12345",
    "date": "2026-01-28"
  }
}

Get Payment History

Endpoint

GET /api/v1/invoices/:invoiceId/payments

curl https://dev.auxcore.net/api/v1/invoices/inv_abc123/payments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "invoiceId": "inv_abc123",
    "totalAmount": 500.00,
    "paidAmount": 500.00,
    "remainingBalance": 0.00,
    "status": "paid",
    "payments": [
      {
        "paymentId": "pmt_1",
        "amount": 250.00,
        "method": "card",
        "status": "approved",
        "paidAt": "2026-01-28T10:00:00Z",
        "transactionId": "txn_123"
      },
      {
        "paymentId": "pmt_2",
        "amount": 250.00,
        "method": "card",
        "status": "approved",
        "paidAt": "2026-01-29T14:00:00Z",
        "transactionId": "txn_456"
      }
    ]
  }
}

Payment Status

Auto-Reconciliation

Automatically match payments to invoices:

curl -X POST https://dev.auxcore.net/api/v1/invoices/reconcile \
  -d '{
    "transactionId": "txn_abc123",
    "invoiceNumber": "INV-12345"
  }'

Matching methods:

1. Invoice number in payment reference
2. Customer ID match
3. Amount match
4. Date range match

Payment Reminders

Send payment reminders for unpaid invoices:

Endpoint

POST /api/v1/invoices/:invoiceId/remind

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/remind \
  -d '{
    "sendVia": ["email", "sms"],
    "message": "Friendly reminder: Invoice due in 3 days"
  }'

Automatic Reminders

Configure automatic reminder schedule:

{
  "reminderSchedule": [
    {
      "daysBefore": 3,
      "sendVia": ["email"]
    },
    {
      "daysBefore": 1,
      "sendVia": ["email", "sms"]
    },
    {
      "daysAfter": 1,
      "sendVia": ["email", "sms"],
      "message": "Overdue invoice reminder"
    }
  ]
}

Overpayments

Handle overpayment scenarios:

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/payment \
  -d '{
    "amount": 600.00
  }'

Response:

{
  "success": true,
  "data": {
    "paymentId": "pmt_over_123",
    "invoiceId": "inv_abc123",
    "totalAmount": 500.00,
    "paidAmount": 600.00,
    "overpaymentAmount": 100.00,
    "status": "overpaid"
  }
}

Options for overpayment:

1. Refund - Return excess to customer
2. Credit - Apply to account balance
3. Apply to next invoice - Future credit

Failed Payments

Handle payment failures:

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/payment \
  -d '{
    "amount": 500.00,
    "card": {
      "number": "4000000000000002"
    }
  }'

Response:

{
  "success": false,
  "data": {
    "paymentId": "pmt_failed_123",
    "invoiceId": "inv_abc123",
    "amount": 500.00,
    "status": "failed",
    "declineReason": "Insufficient funds",
    "attemptedAt": "2026-01-28T14:00:00Z"
  }
}

Retry Failed Payment

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/payment/retry \
  -d '{
    "paymentId": "pmt_failed_123",
    "paymentMethod": "card"
  }'

Payment Receipts

Automatically send payment receipt:

Email Receipt

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/receipt \
  -d '{
    "paymentId": "pmt_xyz789",
    "sendTo": "customer@example.com",
    "sendVia": "email"
  }'

SMS Receipt

curl -X POST https://dev.auxcore.net/api/v1/invoices/inv_abc123/receipt \
  -d '{
    "paymentId": "pmt_xyz789",
    "sendTo": "+1234567890",
    "sendVia": "sms"
  }'

Webhooks

invoice.payment_received

{
  "type": "invoice.payment_received",
  "data": {
    "invoiceId": "inv_abc123",
    "paymentId": "pmt_xyz789",
    "amount": 250.00,
    "remainingBalance": 250.00,
    "status": "partially_paid",
    "paidAt": "2026-01-28T14:00:00Z"
  }
}

invoice.paid

{
  "type": "invoice.paid",
  "data": {
    "invoiceId": "inv_abc123",
    "totalAmount": 500.00,
    "paidAmount": 500.00,
    "status": "paid",
    "paidAt": "2026-01-29T14:00:00Z"
  }
}

invoice.payment_failed

{
  "type": "invoice.payment_failed",
  "data": {
    "invoiceId": "inv_abc123",
    "paymentId": "pmt_failed_123",
    "amount": 500.00,
    "declineReason": "Insufficient funds",
    "attemptedAt": "2026-01-28T14:00:00Z"
  }
}

Payment Analytics

Track payment performance:

curl "https://dev.auxcore.net/api/v1/analytics/invoice-payments?period=30d" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "totalInvoices": 500,
    "paidInvoices": 450,
    "partiallyPaid": 30,
    "unpaid": 20,
    "paymentRate": 0.90,
    "averageDaysTo Payment": 12,
    "totalRevenue": 450000.00,
    "partialPaymentRate": 0.06
  }
}

Best Practices

✅ DO:

• Allow partial payments - Increases payment rate
• Send receipts immediately - Automated confirmation
• Track payment attempts - For customer support
• Enable reminders - Reduce overdue invoices
• Offer multiple methods - Card, ACH, etc.
• Auto-reconcile - Match payments automatically

❌ DON'T:

• Don't reject overpayments - Offer refund/credit options
• Don't ignore failed payments - Follow up promptly
• Don't skip receipts - Always confirm payment
• Don't lose payment history - Track everything
• Don't complicate payment - Make it easy

Common Scenarios

Scenario 1: Payment Plan

Customer wants to pay $500 invoice in 5 installments:

# Payment 1
curl -X POST /api/v1/invoices/inv_abc123/payment -d '{"amount": 100.00}'

# Payment 2 (2 weeks later)
curl -X POST /api/v1/invoices/inv_abc123/payment -d '{"amount": 100.00}'

# Continue until paid...

Scenario 2: Wrong Amount Paid

Customer accidentally paid wrong amount:

# They paid $600 instead of $500
# Option 1: Refund $100
curl -X POST /api/v1/transactions/txn_abc123/refund -d '{"amount": 100.00}'

# Option 2: Apply credit to account
curl -X POST /api/v1/customers/cust_123/credit -d '{"amount": 100.00}'

Scenario 3: External Payment

Customer paid via check:

curl -X POST /api/v1/invoices/inv_abc123/payment \
  -d '{
    "amount": 500.00,
    "paymentMethod": "external",
    "externalPaymentDetails": {
      "method": "check",
      "checkNumber": "12345",
      "date": "2026-01-28",
      "notes": "Deposited to bank"
    }
  }'

Next Steps

• Create invoices →
• Send invoices →
• Customize templates →

Need help? Contact support@auxvault.com