Payment Arrangements

Payment Arrangements allow you to split a payment into scheduled installments. Create an arrangement with a total amount, upfront payment, and installment schedule. The customer pays the upfront amount via a secure link, their card is captured, and HL Hunt automatically charges the remaining installments on schedule.

POST
/v1/arrangements

Create an Arrangement

Create a new payment arrangement with an installment schedule. Returns the arrangement object including a payment_url for the customer to pay the upfront amount. Amounts are in cents (e.g., 400000 = $4,000.00). Required fields: title, total_amount, upfront_amount, installment_count, frequency (DAILY, WEEKLY, BI_WEEKLY, MONTHLY, CUSTOM). When frequency is CUSTOM, interval_days is required (e.g., interval_days=3 charges every 3 days). Optional: block_on_failure (default true — set false to skip failed installments and keep charging the rest), max_failed_installments (default 2 — threshold before the plan defaults), start_date, customer_id, customer_name, customer_email, metadata. Example — debt collection custom plan: $1/day for 100 days with skip-to-next mode: total_amount=10400, upfront_amount=104, frequency=CUSTOM, interval_days=1, installment_count=100, block_on_failure=false

curl -X POST https://api.hlhunt.org/v1/arrangements \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website Development",
    "description": "Custom website - 4 monthly payments",
    "total_amount": 400000,
    "upfront_amount": 100000,
    "installment_count": 3,
    "frequency": "MONTHLY",
    "customer_name": "John Smith",
    "customer_email": "john@example.com",
    "start_date": "2026-09-01"
  }'

# Debt collection — $1/day for 100 days (custom frequency):
curl -X POST https://api.hlhunt.org/v1/arrangements \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Debt repayment — Case #4821",
    "total_amount": 10400,
    "upfront_amount": 104,
    "frequency": "CUSTOM",
    "interval_days": 1,
    "installment_count": 100,
    "block_on_failure": false,
    "customer_email": "debtor@example.com"
  }'
GET
/v1/arrangements

List Arrangements

Returns a paginated list of payment arrangements. Use ?status= to filter (draft, pending, active, paused, completed, canceled). Use ?customer_id= to filter by customer. Use ?limit= and ?offset= for pagination.

curl "https://api.hlhunt.org/v1/arrangements?status=active&limit=25" \
  -H "Authorization: Bearer sk_live_your_api_key"
GET
/v1/arrangements/:id

Retrieve an Arrangement

Retrieve a single arrangement by ID. Returns the full arrangement object including all installments and their statuses.

curl https://api.hlhunt.org/v1/arrangements/arr_abc123 \
  -H "Authorization: Bearer sk_live_your_api_key"
PATCH
/v1/arrangements/:id

Update an Arrangement

Update an arrangement. Two modes: (1) Metadata update — update title, description, notes, or customer info. Only DRAFT or PENDING arrangements can be metadata-updated. (2) Plan update — update installment_amount, frequency, or interval_days on an ACTIVE or PAUSED arrangement. This re-schedules all unpaid installments from their earliest due date (paid installments are immutable). Useful when a debtor renegotiates mid-plan.

curl -X PATCH https://api.hlhunt.org/v1/arrangements/arr_abc123 \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Updated Project", "customer_email": "new@example.com" }'
POST
/v1/arrangements/:id/send

Send to Customer

Transitions the arrangement from DRAFT to PENDING and notifies the customer via email with the payment link.

curl -X POST https://api.hlhunt.org/v1/arrangements/arr_abc123/send \
  -H "Authorization: Bearer sk_live_your_api_key"
POST
/v1/arrangements/:id/cancel

Cancel an Arrangement

Cancel the arrangement and void all remaining pending installments. Cannot cancel completed or already-canceled arrangements.

curl -X POST https://api.hlhunt.org/v1/arrangements/arr_abc123/cancel \
  -H "Authorization: Bearer sk_live_your_api_key"
POST
/v1/arrangements/:id/pause

Pause an Arrangement

Temporarily pause auto-charging. Only active arrangements can be paused.

curl -X POST https://api.hlhunt.org/v1/arrangements/arr_abc123/pause \
  -H "Authorization: Bearer sk_live_your_api_key"
POST
/v1/arrangements/:id/resume

Resume a Paused Arrangement

Resume a paused arrangement. Charging will continue from the next pending installment.

curl -X POST https://api.hlhunt.org/v1/arrangements/arr_abc123/resume \
  -H "Authorization: Bearer sk_live_your_api_key"
POST
/v1/arrangements/:id/payment-method

Update Payment Method

Swap the card on file used for future installment charges. The payment instrument must belong to the same merchant and have a vaulted card. Works on ACTIVE, PAUSED, or PENDING arrangements. Emits the arrangement.payment_method_updated webhook.

curl -X POST https://api.hlhunt.org/v1/arrangements/arr_abc123/payment-method \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method_id": "pi_xyz789" }'