Payments API

Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

List payments with totals

Payments newest first (by paid date), filtered by method, processor (MANUAL or STRIPE), status, date range, customer, invoice or quote, with totals over every match (not only the page): amountCents, tipCents, refundedCents of received payments, collectedCents (amounts net of refunds, tips excluded: revenue, gross of fees), netTipCents, netCents = amount + tips − refunds, and feesCents (online-payment fees the business paid: Stripe's processing fees plus any ServFlo fee). Online payments show PENDING until Stripe confirms them and FAILED when declined or abandoned. Read-only.

Permission: payments.read (Owner, Admin, Dispatcher, Technician (own jobs' invoices)); risk read (OAuth scope servflo.read).

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/payments" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Export payments as CSV

The payments list as a CSV file (the Payments page's Export CSV), with the same filters as GET /payments and every matching row (up to 10,000): payment, paid on, customer, invoice, quote, method, processor, card, reference, status, amount, tip, refunded, fees, net, recorded by, note. Amounts in dollars. Read-only.

Permission: payments.read (Owner, Admin, Dispatcher, Technician (own jobs' invoices)); risk read (OAuth scope servflo.read).

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/payments/export" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Get a payment with its refunds

One payment, its invoice or quote, who recorded it, and every refund on it. Read-only.

Permission: payments.read (Owner, Admin, Dispatcher, Technician (own jobs' invoices)); risk read (OAuth scope servflo.read).

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/payments/{paymentId}" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Record a payment on an invoice (moves money)

Money: records money the business received for this invoice (processor MANUAL; nothing is charged). amountCents must be above 0 and at most the balance due: overpayment is refused (400); add extra as tipCents. A cancelled invoice cannot take payments. When the balance reaches 0 the invoice becomes PAID with that day as its paid date; a partial payment leaves its status and reads as partially paid. Needs payments.record (owners, admins, dispatchers). The business's "Payment receipt" automation (when on) emails a receipt; notifyCustomer: false sends nothing for this payment. Get the invoice and its balanceDueCents with GET /invoices/{invoiceId} first. Returns the payment.

Permission: payments.record (Owner, Admin, Dispatcher, Technician (own jobs' invoices)); risk sensitive (OAuth scope servflo.sensitive).

Parameters

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/invoices/{invoiceId}/payments" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents":12500,"method":"CASH"}'

Response

A quote's deposit: requested, collected, outstanding

requestedCents is the deposit the approval asked for, collectedCents the deposits received net of refunds (applied to an invoice or not), outstandingCents what is left to collect, with the deposit payments. Read-only.

Permission: payments.read (Owner, Admin, Dispatcher, Technician (own jobs' invoices)); risk read (OAuth scope servflo.read).

Parameters

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/quotes/{quoteId}/deposits" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Record a deposit on an approved quote (moves money)

Money: records a deposit the customer paid on an APPROVED (or CONVERTED but not yet invoiced) quote. Deposits may add up to the approved total, never more. When the quote is invoiced (POST /quotes/{quoteId}/invoice, or invoicing the job it became) the deposits move onto that invoice and count as paid there. Returns the payment.

Permission: payments.record (Owner, Admin, Dispatcher, Technician (own jobs' invoices)); risk sensitive (OAuth scope servflo.sensitive).

Parameters

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/quotes/{quoteId}/deposits" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents":12500,"method":"CASH"}'

Response

Refund a payment (moves money back)

DESTRUCTIVE / MONEY: gives money back to the customer on this payment. At most the payment's amount plus tip, less earlier refunds, including online refunds still pending (400 otherwise); pending or failed payments cannot be refunded. The refund comes off the invoice amount first, then the tip. MANUAL payments: recorded at once (nothing is sent anywhere). STRIPE payments: refunded through Stripe to the card or bank account (the transfer to the business is reversed and the platform fee returned in proportion); the refund is PENDING until Stripe's webhook confirms it, and only then does the invoice reopen (SENT, or OVERDUE past its due date). Needs payments.refund (owners and admins; 403 for others). Find the payment with GET /payments or GET /invoices/{invoiceId}. Returns the payment with its refunds.

Parameters

Request body

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/payments/{paymentId}/refunds" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents":12500}'

Response