Tap to Pay 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.

Tap to Pay: whether this business can take cards in person

Whether cards can be taken in person on a phone (Tap to Pay on iPhone and Android, through Stripe Terminal) and whether this caller may charge a customer's saved card. Read-only; makes nothing at Stripe. The technician app shows its Tap to Pay button only when available is true (and the phone supports it).

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

Example

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

Response

Tap to Pay: start taking a card for an invoice (moves money)

Money: starts a card payment the customer taps on the technician's phone. Writes a PENDING payment (processor STRIPE, channel TAP_TO_PAY, payment.started) and a card_present PaymentIntent on the business's Stripe account for amountCents (default the balance due; less is allowed, at least 100) plus tipCents when the business takes tips. The phone collects the card with the Stripe Terminal SDK; Stripe's webhook settles the payment and the invoice (payment.recorded). An earlier unfinished Tap to Pay on this invoice is cancelled. 409 when the business can't take cards, 400 when nothing is due. Technicians: their own jobs' invoices.

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}/tap-to-pay" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents":12500,"tipCents":12500}'

Response

Tap to Pay: start taking a quote deposit by card (moves money)

Money: starts a card deposit the customer taps on the phone, on an APPROVED (or CONVERTED, not yet invoiced) quote. Writes a PENDING deposit payment (channel TAP_TO_PAY) and a card_present PaymentIntent on the business's Stripe account for amountCents (default the deposit the approval asked for; deposits may add up to the approved total). Stripe's webhook settles it; the deposit moves onto the invoice when the quote is invoiced. Technicians: the quotes they sold.

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}/tap-to-pay" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amountCents":12500}'

Response

Tap to Pay: cancel an unfinished attempt

The customer didn't tap, or the person stopped: cancels the PaymentIntent at Stripe and marks the PENDING Tap to Pay payment FAILED (payment.failed, reason tap_cancelled). Takes no money and refunds nothing; a payment Stripe already took is left for its webhook to settle. Technicians: payments they started.

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

Parameters

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/payments/{paymentId}/tap-to-pay/cancel" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

A card payment taken in person: where it stands

The status of a Tap to Pay or saved-card payment (PENDING until Stripe settles it, SUCCEEDED, FAILED with a reason in words), its amount and the card (Visa •••• 4242). The app polls this after a tap. Read-only. Technicians: payments they took.

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}/in-person" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

The customer's saved card for an invoice, and whether it can be charged

The card the invoice's customer saved on the business's Stripe account (for memberships, from their portal), as brand, last four and expiry, and whether this caller may charge it now (allowed, else refusal in words: technicians need the owner's "Let technicians charge saved cards" switch; expired cards and bank accounts can't). Read-only. Technicians: their own jobs' invoices.

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/invoices/{invoiceId}/saved-card" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

Charge the customer's saved card for an invoice (moves money)

Money: charges the card the invoice's customer saved (GET /invoices/{invoiceId}/saved-card first) off-session on the business's Stripe account, for amountCents (default the balance due). Only after the person confirmed the amount with the customer. attemptKey is made once per confirmation: a retry with the same key charges once and returns the same payment. Writes a payment (channel SAVED_CARD, payment.started), settled from Stripe's answer: SUCCEEDED (payment.recorded) or FAILED with the reason (declined, expired, the bank asked the customer to confirm). Technicians only when the owner turned on "Let technicians charge saved cards" (409 otherwise). An AI caller always needs the person's approval in ServFlo.

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}/charge-saved-card" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"attemptKey":"string"}'

Response

Text or email the customer a receipt for a card payment

Sends to the customer: a receipt for a Tap to Pay or saved-card payment that went through (amount, card, invoice or quote, PAY-n), by text (SMS) or EMAIL, through the engagement engine and its consent rules. Sent once per payment and channel (a repeat returns the first). 409 while the payment is still PENDING. In-person card payments don't trigger the automatic receipt; this is how the customer gets one. Technicians: payments they took.

Permission: invoices.send (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/payments/{paymentId}/receipt" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"SMS"}'

Response