Payments

Payments represent individual financial transactions collected against a plan or payment request. They are created automatically by the system when a customer pays through the checkout — you don't create payments directly. Your role is to monitor them, filter them for reconciliation, and initiate refunds when needed.

Payment Lifecycle

Every payment moves through a predictable sequence:

Pending → Approved → Captured → Settled

• Pending — Payment initiated. For ACH, this is when the customer submits bank details. For credit card, when the charge is submitted.
• Approved — Authorization confirmed by the payment processor.
• Captured — Funds reserved and ready for settlement. This is the point after which a refund can be issued.
• Settled — Funds deposited to the merchant account. This is the final state for a successful payment.

ACH payments can additionally move to Returned if the bank rejects the transfer (insufficient funds, invalid account, etc.). A returned payment requires separate handling — typically collecting payment again via a different method.

When a payment is refunded, the status becomes Refunded (full refund) or Partially Refunded (partial refund where an outstanding settled balance remains).

Payment Types

The payment_type on a payment record reflects how it was collected.

Finding and Filtering Payments

GET /v1/payments

The payments list endpoint supports rich filtering for reconciliation workflows:

• Filter by status — Use ?status=Settled to pull only settled payments. Multiple values are accepted: ?status=Settled&status=Captured.
• Date range — Use start_date and end_date (ISO 8601) to scope to a settlement window.
• Payment method — Filter by payment_method=ach or credit_card to separate by channel.
• Filter by plan — Use ?plan_id={plan_id} to retrieve only the payments collected against a specific plan. This is the recommended way to see a plan's payments — each payment in the response also carries its own plan_id. An unknown or non-existent plan simply returns an empty list.
• Filter by payment request — Use ?payment_request_id={payment_request_id} to scope to a single payment request.
• Search — Use search_term to find payments by merchant name or amount.
• Sort — sort_by=settled_at with sort_order=asc is useful for building ordered reconciliation exports.

Filters can be combined — for example, GET /v1/payments?plan_id={plan_id}&status=Settled returns just the settled payments for one plan.

For large datasets, enable pagination with ?pagination=true&page=1&page_size=100 to process results in pages.

To see all payments for a specific customer, use GET /v1/payments/insured/{insured_id}.

For dashboard counts broken down by status, use GET /v1/payments/count.

Exporting Payments

You can export your payments as a CSV file directly through the API — the same export available from the Payments screen in the dashboard, now available programmatically. This is useful for pulling a payment ledger into a spreadsheet or your own accounting system for reconciliation.

The export supports the same filtering as the payments list, so you can scope it to a date range, status, payment method, or search term and only export the payments you need. Each row is a single payment with its amounts, fee breakdown (including fees paid by the insured versus fees you absorbed), net amount received, and lifecycle timestamps. The export only ever contains your own account's payments.

Refunds

POST /v1/payments/{payment_id}/refund

Only payments with status Captured or Settled can be refunded. A refund of a Captured payment reverses before settlement; a refund of a Settled payment initiates a return transfer.

Full refund — omit the amount field or send an empty body {}:

curl -X POST "https://api.advancehq.com/v1/payments/pay_abc123/refund" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

Partial refund — send amount as a whole-dollar integer (e.g. 50 for $50.00):

curl -X POST "https://api.advancehq.com/v1/payments/pay_abc123/refund" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50 }'

After a partial refund, the original payment moves to Partially Refunded status — the remaining settled balance is still on the books. A second refund will settle the rest and move it to Refunded. The relationship between refunds and original payments is tracked via refunded_payment_id and original_payment_id on the payment object.

Payment Audit History

Each payment record from GET /v1/payments/{payment_id} includes an audit_list — a chronological log of every status transition with a timestamp and message. This is the primary tool for investigating payment issues: you can see exactly when and why a payment moved from Pending to Approved to Captured, or where it stalled.

Payment Requests

Payment requests are standalone payment links not tied to a plan. Use them when you need to collect payment for something that doesn't fit the plan model — a deposit, an ad-hoc fee, or a payment outside your standard billing flow.

POST /v1/payments/payment-request

Key behaviors:

• A payment request generates its own payment_request_url to send to the customer.
• Set payment_expiration to control how long the link is valid (defaults to 30 days).
• Use allowed_payment_methods to restrict to checkout_ach and/or checkout_credit_card.
• Attach user_metadata (arbitrary key-value pairs) to link the request to your own system's records — quote ID, customer ID, etc.
• If the customer already has an insured record, pass insured_id to associate the request with them. This enables filtering payment requests by insured via GET /v1/payments/payment-requests?insured_id=....
• Use send_email_to_recipient: true to have Advance automatically email the payment link to recipient_email.

Once paid, the payment request moves to paid: true and paid_at is set.

Retrieve all payment requests with GET /v1/payments/payment-requests (supports filtering by status, insured_id, and paid), or a specific one by GET /v1/payments/payment-request/{payment_request_id}.