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.

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}.