Invoice Payments#

Collect, record and track invoice payments, including partial payments and payment history.

Overview#

There are two ways money reaches an invoice:

• 💳 Customer pays the pay link - card, ACH or a saved card on the hosted pay page (/api/v1/public/invoices/...). The charge and the invoice update happen together.
• 📝 Merchant records a payment - money already collected elsewhere (portal collect, terminal, cash, check) is recorded against the invoice with /payment or /external-payment. These endpoints never charge anything.

Every payment is appended to the invoice's paymentHistory, and amountPaid, amountDue and status move with it:

• 📊 Partial payments - only when allowPartialPayment is true (optionally with a minimum payment)
• ✅ Fully paid - status becomes paid and paidAt is stamped when amountDue reaches 0

Admin endpoints use Authorization: Bearer YOUR_TOKEN + X-Tenant-ID (or x-api-key).

curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/payment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "paymentMethod": "card",
    "transactionId": "TXN-20261001-8F3A2C",
    "notes": "Collected at the counter"
  }'

{
  "success": true,
  "data": {
    "id": "0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10",
    "status": "partial",
    "totalAmount": "1000.00",
    "amountPaid": 500.00,
    "amountDue": 500.00,
    "paymentHistory": [
      {
        "transactionId": "TXN-20261001-8F3A2C",
        "amount": 500.00,
        "paymentMethod": "card",
        "paidAt": "2026-10-01T14:00:00.000Z",
        "notes": "Collected at the counter",
        "isExternal": false,
        "balanceAfter": 500.00,
        "actorId": "a4c2e9d1-7b3f-4e8a-9c21-5d6e7f8a9b0c",
        "actorEmail": "jane@merchant.example"
      }
    ]
  }
}

curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/payment-preflight \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 250.00 }'

{
  "success": true,
  "data": { "amount": 250.00, "amountDue": 500.00, "minimumPayment": 125.00 }
}

curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/external-payment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "paymentMethod": "Check",
    "paymentDate": "2026-10-01",
    "recordedBy": "Jane Doe",
    "reference": "CHK-1024",
    "internalNote": "Deposited to bank"
  }'

Cash
ACH
Check
Wire Transfer
External Card
Other

{
  "success": true,
  "data": {
    "id": "0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10",
    "status": "partial",
    "amountPaid": 500.00,
    "amountDue": 1000.00,
    "paymentHistory": [
      {
        "amount": 500.00,
        "paymentMethod": "Check",
        "paidAt": "2026-10-01T12:00:00.000Z",
        "notes": "CHK-1024 · Deposited to bank",
        "isExternal": true,
        "balanceAfter": 1000.00,
        "recordedBy": "Jane Doe",
        "actorId": "a4c2e9d1-7b3f-4e8a-9c21-5d6e7f8a9b0c",
        "actorEmail": "jane@merchant.example"
      }
    ]
  }
}

Payment History#

There is no separate history endpoint. GET /api/v1/invoices/:invoiceId returns paymentHistory (one entry per payment) together with amountPaid, amountDue, status, transactionId (primary transaction) and paidAt.

Payment Status#

Payment progress is reflected in the invoice status:

Customer Payments (Pay Link)#

The hosted pay page uses these public endpoints. They need no API key: possession of the invoice's linkId authorises them. A full edit rotates the linkId; the old one returns 410 LINK_ROTATED.

Get Invoice for Payment#

Returns the invoice plus merchant branding, allowedPaymentMethods (from metadata.acceptCards / metadata.acceptAch), hasSavedCard and hasSavedAch. The first open moves a sent invoice to viewed.

GET /api/v1/public/invoices/link/:linkId/fee-preview returns the customer-facing fee for an amount.

{
  "pciToken": "pci_tok_9f8e7d6c5b4a3210",
  "amount": 250.00,
  "email": "john@example.com",
  "customerName": "John Doe",
  "billingAddress": "100 Main St",
  "billingCity": "Austin",
  "billingState": "TX",
  "billingPostalCode": "78701",
  "billingCountry": "US"
}

Pay by ACH#

Body: accountHolderName, routingNumber, accountNumber, accountType, customerType, businessName, email, phone, billing address fields, consentAccepted, eSignature, optional amount, customerName and saveAch. routingNumber must be 9 digits, accountNumber 4–17 digits, accountType checking or savings, customerType personal or business (businessName required for business); consentAccepted and eSignature are required. Field errors return 400 with error.fields. While the ACH transaction is processing the invoice is pending.

Other Pay-Link Endpoints#

The saved-card OTP endpoints are limited to 10 requests per 15 minutes.

Payment Reminders#

Sends a reminder email now. See Sending & Delivery.

Note: a configurable automatic reminder schedule is not available via API.

Failed Payments#

A declined card payment on the pay link returns 400 with success: false and a message such as "Payment declined: Insufficient funds", and the invoice is left unchanged so the customer can try again. Nothing is recorded in paymentHistory.

Webhooks#

When the invoice has a webhookUrl, a successful pay-link card or ACH payment POSTs invoice.paid to it:

{
  "event": "invoice.paid",
  "invoice": { "id": "0b8e6a3c-...", "status": "partial", "amountPaid": 250.00, "amountDue": 250.00 },
  "transaction": { "transactionId": "TXN-20261002-9C1D4E", "amount": 250.00 }
}

The event is also sent for partial payments — check invoice.status. Payments recorded with /payment or /external-payment do not send it.

Best Practices#

✅ DO:#

• Allow partial payments - Increases payment rate
• Preflight before charging - when your integration decides the amount
• Record every off-platform payment with /external-payment
• Enable reminders - Reduce overdue invoices
• Offer multiple methods - Card and ACH

❌ DON'T:#

• Don't send card data to /payment - it records, it does not charge
• Don't record more than the balance - /payment does not stop you
• Don't record the same payment twice - pass transactionId

Common Scenarios#

Scenario 1: Payment Plan#

Customer wants to pay a $500 invoice in 5 installments (the invoice needs allowPartialPayment: true):

# Payment 1, after collecting $100
curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-.../payment \
  -H "Authorization: Bearer YOUR_TOKEN" -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100.00, "paymentMethod": "card", "transactionId": "TXN-20261001-1A2B3C"}'

# Continue until paid...

Scenario 2: External Payment#

Customer paid by check outside AuxCORE:

curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-.../external-payment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "paymentMethod": "Check",
    "paymentDate": "2026-10-01",
    "reference": "CHK-12345",
    "internalNote": "Deposited to bank"
  }'

Next Steps#

• Create invoices →
• Send invoices →
• Invoice appearance →

Need help? Contact support@auxcore.net