Receive a customer payment (Apideck MCP)

When the user wants to record a payment against an existing invoice, prefer apideck-receive-customer-payment over stitching accounting-invoices-get + accounting-payments-create manually. The workflow tool fetches the invoice, reads its outstanding balance, builds the right allocation with type: "invoice", and surfaces structured errors with failingStep.

When this is the right tool

User intent	Tool
"Customer paid invoice 4", "Apply $500 to invoice 12 from ACME", "Record receipt for invoice 99"	apideck-receive-customer-payment ✓
"Pay vendor bill X"	apideck-pay-bill (AP — accounts payable, different unified endpoint)
"Create an unallocated customer prepayment"	accounting-payments-create directly (no allocation)
"Show me unpaid invoices"	accounting-invoices-list with filter[status]=open

IMPORTANT RULES

• CONFIRM before calling. Receive-payment is mutating and not idempotent — calling twice creates two payments on the connected service. Always show the user the invoice total, currency, deposit account, and customer, and wait for explicit confirmation before invoking.
• PASS payment_method capitalized for QuickBooks: "Check", "CreditCard", "Cash". Lower-case fails JSON parsing. Other connectors accept lower-case ("check", "ach", "wire").
• OMIT amount to settle the full outstanding balance. The workflow defaults to the invoice's balance (outstanding), not the gross total, so partial-paid invoices don't get over-settled. Only pass amount when the user explicitly wants a partial payment.
• DON'T confuse with apideck-pay-bill. Customer payments (someone owes you) → apideck-receive-customer-payment → accounting-payments-create. Vendor bills (you owe someone) → apideck-pay-bill → accounting-bill-payments-create. The unified APIs split AR and AP into separate endpoints; the wrong one will be rejected by the connector with confusing error messages (e.g. QuickBooks: VendorRef missing when there's a customer on the other side).
• SET x-apideck-service-id when the consumer has multiple accounting connections.

Argument map

Arg	Required	Default	Notes
invoice_id	yes	—	From accounting-invoices-list.
account_id	yes	—	The deposit account that received the payment. From accounting-ledger-accounts-list. Often a bank or undeposited-funds account.
amount	no	invoice's outstanding balance	Pass smaller for a partial payment.
transaction_date	no	today (YYYY-MM-DD)	Some connectors reject future dates.
payment_method	no	—	QB requires capitalized.
reference	no	—	Memo / external reference.
x-apideck-service-id	no	first accounting connection	E.g. "xero", "quickbooks".

Result shape

Success

{
  "invoice_id": "inv-42",
  "payment_id": "pay-77",
  "amount": 250.50,
  "currency": "EUR",
  "transaction_date": "2026-04-26",
  "invoice_total": 250.50,
  "partial": false,
  "service_id": "xero"
}

partial: true indicates an under-payment; tell the user a follow-up payment is needed for the rest.

Failure (with isError: true)

{
  "invoice_id": "inv-42",
  "amount": 100,
  "currency": "USD",
  "error": "accounting-payments-create failed: ...",
  "failingStep": "accounting-payments-create",
  "upstream": { ... }
}

failingStep values:

• accounting-invoices-get — invoice ID wrong or connector lost the record
• validate-amount — invoice has zero outstanding balance (already paid)
• accounting-payments-create — payment write failed; check upstream

Worked example

User: "ACME paid invoice inv-42 for $250.50 by check. Apply it to our bank account."

1. The user already gave you the invoice id. Find the deposit account: accounting-ledger-accounts-list filtered to bank — say "acc-bank".
2. Confirm: "Recording $250.50 payment from ACME on invoice inv-42 to bank account acc-bank via Xero, payment method check. Confirm?"
3. On confirmation:

   {
     "name": "apideck-receive-customer-payment",
     "arguments": {
       "invoice_id": "inv-42",
       "account_id": "acc-bank",
       "payment_method": "check",
       "x-apideck-service-id": "xero"
     }
   }
   

4. Surface payment_id to the user.

Common failure modes

Symptom	Cause	Fix
failingStep: validate-amount	Invoice already fully paid	Confirm with user; pass explicit amount only if recording an over-payment is intentional
Moneybird returns 404 from /accounting/payments	Moneybird models customer payments as financial_mutations, not payments	Connector coverage gap; surface the limitation, fall back to the Proxy API
QB rejects with parse error	payment_method lower-case	Pass "Check" (capitalized) for QB
UrlElicitationRequiredError	Connection expired/missing	Surface consent URL, retry after OAuth

Related

• apideck-mcp — front-door skill
• apideck-mcp-pay-bill — AP mirror (paying a vendor bill)
• Workflow source: src/gen/workflows/receivePayment.ts