Payments

Payment Statuses

Status	Description
`Pending`	Payment initiated, awaiting processing
`Approved`	Payment authorized
`Captured`	Funds captured from customer
`Settled`	Funds deposited to merchant account
`Failed`	Payment failed
`Returned`	ACH payment returned
`Refunded`	Payment refunded to customer

List All Payments

Retrieves all payments with optional filtering and pagination.

Endpoint: GET /v1/payments

Query Parameters:

Parameter	Type	Default	Description
`pagination`	boolean	false	Enable paginated response
`page`	integer	1	Page number
`page_size`	integer	100	Items per page
`status`	string	-	Filter by payment status
`plan_id`	string	-	Filter by plan ID

Use Cases:

Reconcile payments with your accounting system
Generate payment reports
Track payment processing status

Example:

curl -X GET "https://api.advancehq.com/v1/payments?pagination=true&page=1&page_size=25&status=Settled" \
  -H "Authorization: Bearer your_api_key"

Response:

{
  "data": [
    {
      "payment_id": "pay_abc123",
      "plan_id": "plan_xyz789",
      "payment_number": "PMT-2025-0001",
      "txn_amount": "5000.00",
      "txn_status": "Settled",
      "payment_type": "ach",
      "first_name": "John",
      "last_name": "Smith",
      "company": "Acme Corporation",
      "email": "[email protected]",
      "currency": "USD",
      "created_at": "2025-01-20T14:30:00Z",
      "captured_at": "2025-01-20T14:30:05Z",
      "settled_at": "2025-01-23T08:00:00Z",
      "payment_receipt_url": "https://storage.advancehq.com/receipts/pay_abc123.pdf"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total_items": 500,
    "total_pages": 20,
    "has_next": true,
    "has_previous": false
  }
}

Get Payment Details

Retrieves detailed payment information including audit history.

Endpoint: GET /v1/payments/{payment_id}

Use Cases:

Investigate payment issues
View complete payment lifecycle
Customer support inquiries

Example:

curl -X GET "https://api.advancehq.com/v1/payments/pay_abc123" \
  -H "Authorization: Bearer your_api_key"

Response:

{
  "payment_id": "pay_abc123",
  "plan_id": "plan_xyz789",
  "payment_number": "PMT-2025-0001",
  "txn_amount": "5000.00",
  "total": "5000.00",
  "txn_status": "Settled",
  "payment_type": "ach",
  "payment_routing": "021000021",
  "first_name": "John",
  "last_name": "Smith",
  "company": "Acme Corporation",
  "email": "[email protected]",
  "currency": "USD",
  "approved": "true",
  "refunded": "false",
  "created_at": "2025-01-20T14:30:00Z",
  "captured_at": "2025-01-20T14:30:05Z",
  "settled_at": "2025-01-23T08:00:00Z",
  "payment_receipt_url": "https://storage.advancehq.com/receipts/pay_abc123.pdf",
  "audit_list": [
    {
      "status": "Pending",
      "message": "Payment initiated",
      "timestamp": "2025-01-20T14:30:00Z"
    },
    {
      "status": "Approved",
      "message": "Payment authorized",
      "timestamp": "2025-01-20T14:30:02Z"
    },
    {
      "status": "Captured",
      "message": "Funds captured",
      "timestamp": "2025-01-20T14:30:05Z"
    },
    {
      "status": "Settled",
      "message": "Funds deposited",
      "timestamp": "2025-01-23T08:00:00Z"
    }
  ]
}

Refund Payment

Refunds a captured or settled payment.

Endpoint: POST /v1/payments/{payment_id}/refund

Use Cases:

Process customer refund requests
Correct billing errors
Handle policy cancellations

Note: Only payments with status Captured or Settled can be refunded.

Example:

curl -X POST "https://api.advancehq.com/v1/payments/pay_abc123/refund" \
  -H "Authorization: Bearer your_api_key"

Response:

{
  "payment_id": "pay_abc123",
  "txn_status": "Refunded",
  "refunded": "true",
  "txn_amount": "5000.00"
}

Create Payment Request

Creates a standalone payment link not tied to a specific plan.

Endpoint: POST /v1/payments/payment-request

Use Cases:

Collect ad-hoc payments
Request deposits or down payments
Custom payment collection

Request Body:

Field	Type	Required	Description
`amount`	number/string	Yes	Payment amount
`payment_expiration`	datetime	No	Link expiration date
`recipient_email`	string	No	Customer email
`send_email_to_recipient`	boolean	No	Auto-send payment link email
`details`	string	No	Payment description
`allowed_payment_methods`	array	No	`checkout_ach`, `checkout_credit_card`
`user_metadata`	object	No	Custom metadata for your records

Example:

curl -X POST "https://api.advancehq.com/v1/payments/payment-request" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500.00",
    "recipient_email": "[email protected]",
    "send_email_to_recipient": true,
    "details": "Policy deposit for Quote #Q-2025-001",
    "payment_expiration": "2025-02-01T23:59:59Z",
    "allowed_payment_methods": ["checkout_credit_card"],
    "user_metadata": {
      "quote_id": "Q-2025-001",
      "customer_id": "CUST-123"
    }
  }'

Response:

{
  "payment_request_id": "preq_abc123",
  "amount": "500.00",
  "payment_request_url": "https://app.advancehq.com/request/abc123",
  "processing_fees_ach": "0.00",
  "processing_fees_credit_card": "15.00",
  "paid": false,
  "paid_at": null,
  "status": "pending",
  "recipient_email": "[email protected]",
  "details": "Policy deposit for Quote #Q-2025-001",
  "payment_expiration": "2025-02-01T23:59:59Z",
  "allowed_payment_methods": ["checkout_credit_card"],
  "user_metadata": {
    "quote_id": "Q-2025-001",
    "customer_id": "CUST-123"
  },
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

List Payment Requests

Retrieves all payment requests.

Endpoint: GET /v1/payments/payment-requests

Example:

curl -X GET "https://api.advancehq.com/v1/payments/payment-requests" \
  -H "Authorization: Bearer your_api_key"