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

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

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

Related

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