Settlement Detail

Overview

The Settlement Detail endpoint returns Stripe settlement information for completed encounters, including transfer status, per-provider payout breakdown, and reconciliation status with AEOB matching. This is the authoritative source for tracking Stripe Connect transfers and verifying that funds have been properly distributed to all providers associated with an encounter.

info

This endpoint provides settlement and reconciliation details specific to Stripe transfers. Use it to verify fund delivery and match against AEOB data.

Endpoint

GET /v1/settlement/{encounter_id}/

Authentication Required: Yes (X-API-Key header) Rate Limit: 200 requests per minute per API key

Request

Path Parameters

Parameter	Type	Required	Description
`encounter_id`	string	Yes	Unique encounter identifier (e.g., `ENC-2024-098765`)

Example Request

GET /v1/settlement/ENC-2024-098765/

Response

Success Response (200 OK)

Complete settlement and reconciliation information.

{
  "settlement_id": "SETTLE-2024-098765-001",
  "encounter_id": "ENC-2024-098765",
  "stripe_transfer_id": "tr_1Oz9rZA1g7yLGa7e0xYzFxVK",
  "status": "COMPLETED",
  "total_amount": 1900.00,
  "payouts": [
    {
      "sequence": 1,
      "provider_npi": "1234567890",
      "provider_name": "Dr. John Smith",
      "provider_role": "SURGEON",
      "stripe_payout_id": "po_1Oz9sAA1g7yLGa7e0xYzFxVL",
      "amount": 1710.00,
      "payout_status": "COMPLETED",
      "payout_date": "2024-02-19T18:30:00Z",
      "expected_arrival": "2024-02-20T23:59:59Z",
      "stripe_fee": 45.00,
      "net_to_provider": 1665.00
    },
    {
      "sequence": 2,
      "provider_npi": "1111111111",
      "provider_name": "Sharp Healthcare Facility",
      "provider_role": "FACILITY",
      "stripe_payout_id": "po_1Oz9sAA1g7yLGa7e0xYzFxVM",
      "amount": 190.00,
      "payout_status": "COMPLETED",
      "payout_date": "2024-02-19T18:30:00Z",
      "expected_arrival": "2024-02-20T23:59:59Z",
      "stripe_fee": 4.75,
      "net_to_provider": 185.25
    }
  ],
  "reconciliation_status": "MATCHED",
  "aeob_match": {
    "aeob_reference": "AEOB-2024-098765",
    "aeob_amount": 1900.00,
    "settlement_amount": 1900.00,
    "variance": 0.00,
    "match_status": "EXACT"
  },
  "initiated_at": "2024-02-18T09:15:00Z",
  "completed_at": "2024-02-19T18:30:00Z",
  "refund_details": null,
  "disputes": []
}

Not Yet Settled (202 Accepted)

Encounter adjudicated but not yet funded.

{
  "encounter_id": "ENC-2024-098765",
  "status": "PENDING",
  "message": "Encounter adjudicated but funding not yet approved",
  "adjudication_complete": true,
  "funding_approved": false
}

Not Found (404 Not Found)

{
  "error": "Encounter not found or has no settlement record",
  "encounter_id": "ENC-INVALID"
}

Response Fields Explained

Settlement Metadata

Field	Type	Description
`settlement_id`	string	Unique settlement record identifier for audit trail
`encounter_id`	string	Associated encounter identifier
`stripe_transfer_id`	string	Master Stripe transfer ID (may encompass multiple payouts)
`status`	string	PENDING, INITIATED, COMPLETED, FAILED, REFUNDED
`total_amount`	number	Total amount transferred (before Stripe fees)
`initiated_at`	string	ISO 8601 timestamp when transfer was initiated
`completed_at`	string	ISO 8601 timestamp when transfer completed

Payout Object

Each provider gets a separate payout entry:

Field	Type	Description
`sequence`	integer	Order of payout (for multi-provider encounters)
`provider_npi`	string	Provider NPI receiving funds
`provider_name`	string	Human-readable provider name
`provider_role`	string	FACILITY, SURGEON, ANESTHESIA, PATHOLOGY
`stripe_payout_id`	string	Stripe payout ID for this provider
`amount`	number	Amount transferred to provider (before Stripe fee)
`payout_status`	string	PENDING, COMPLETED, FAILED, RETURNED
`stripe_fee`	number	Stripe processing fee charged
`net_to_provider`	number	Amount provider actually receives (amount - stripe_fee)
`payout_date`	string	ISO 8601 date payout was processed
`expected_arrival`	string	ISO 8601 date funds expected in provider account

AEOB Reconciliation

Field	Type	Description
`aeob_reference`	string	Patient/provider AEOB document ID
`aeob_amount`	number	Benefit amount shown on AEOB
`settlement_amount`	number	Actual settlement amount transferred
`variance`	number	Difference (should be 0.00 for matched)
`match_status`	string	EXACT, VARIANCE, MISSING_AEOB

Examples

cURL

curl -X GET "https://api.turquoise.health/tpa-api/v1/settlement/ENC-2024-098765/" \
  -H "X-API-Key: YOUR_API_KEY"

Python (Basic Settlement Check)

import requests

api_key = "YOUR_API_KEY"
encounter_id = "ENC-2024-098765"

response = requests.get(
    f"https://api.turquoise.health/tpa-api/v1/settlement/{encounter_id}/",
    headers={"X-API-Key": api_key}
)

if response.status_code == 200:
    data = response.json()

    print(f"Settlement ID: {data['settlement_id']}")
    print(f"Status: {data['status']}")
    print(f"Total Amount: ${data['total_amount']:.2f}")

    print(f"\nPayouts:")
    for payout in data["payouts"]:
        print(f"\n  {payout['provider_name']} ({payout['provider_npi']})")
        print(f"    Gross: ${payout['amount']:.2f}")
        print(f"    Stripe Fee: ${payout['stripe_fee']:.2f}")
        print(f"    Net to Provider: ${payout['net_to_provider']:.2f}")
        print(f"    Status: {payout['payout_status']}")

    if data.get("aeob_match"):
        aeob = data["aeob_match"]
        print(f"\nAEOB Reconciliation:")
        print(f"  Match Status: {aeob['match_status']}")
        print(f"  AEOB Amount: ${aeob['aeob_amount']:.2f}")
        print(f"  Settlement Amount: ${aeob['settlement_amount']:.2f}")
        print(f"  Variance: ${aeob['variance']:.2f}")

elif response.status_code == 202:
    print("Settlement not yet initiated. Funding must be approved first.")
else:
    print(f"Error: {response.status_code}")

Python (Multi-Provider Verification)

import requests

def verify_multi_provider_settlement(encounter_id, api_key):
    """
    Verify that all providers in a settlement received their share.
    """
    response = requests.get(
        f"https://api.turquoise.health/tpa-api/v1/settlement/{encounter_id}/",
        headers={"X-API-Key": api_key}
    )

    if response.status_code != 200:
        print(f"Cannot retrieve settlement: {response.status_code}")
        return False

    data = response.json()

    print(f"Settlement Verification Report")
    print(f"Settlement ID: {data['settlement_id']}")
    print(f"Total Distribution: ${data['total_amount']:.2f}")
    print(f"=== Provider Payouts ===\n")

    total_gross = 0
    total_fees = 0
    total_net = 0

    for payout in data["payouts"]:
        gross = payout["amount"]
        fee = payout["stripe_fee"]
        net = payout["net_to_provider"]

        total_gross += gross
        total_fees += fee
        total_net += net

        print(f"NPI {payout['provider_npi']}: {payout['provider_name']}")
        print(f"  Role: {payout['provider_role']}")
        print(f"  Gross: ${gross:.2f}")
        print(f"  Fee:   ${fee:.2f}")
        print(f"  Net:   ${net:.2f}")
        print(f"  Status: {payout['payout_status']}")
        print()

    print(f"=== Totals ===")
    print(f"Total Gross:  ${total_gross:.2f}")
    print(f"Total Fees:   ${total_fees:.2f}")
    print(f"Total Net:    ${total_net:.2f}")

    # Verify math
    all_complete = all(p["payout_status"] == "COMPLETED" for p in data["payouts"])
    total_matches = abs(total_gross - data["total_amount"]) < 0.01

    print(f"\n=== Verification ===")
    print(f"All Payouts Complete: {'✓' if all_complete else '✗'}")
    print(f"Total Matches Settlement: {'✓' if total_matches else '✗'}")

    return all_complete and total_matches

Python (Wait for Settlement Completion)

import requests
import time

def wait_for_settlement(encounter_id, api_key, max_wait=300):
    """
    Poll until settlement is complete (blocking).
    """
    headers = {"X-API-Key": api_key}
    elapsed = 0
    poll_interval = 5

    while elapsed < max_wait:
        response = requests.get(
            f"https://api.turquoise.health/tpa-api/v1/settlement/{encounter_id}/",
            headers=headers
        )

        if response.status_code == 200:
            data = response.json()

            if data["status"] == "COMPLETED":
                print(f"Settlement completed!")
                print(f"Stripe Transfer: {data['stripe_transfer_id']}")
                return data

            print(f"Settlement status: {data['status']}")

        elif response.status_code == 202:
            print("Funding not yet approved")

        time.sleep(poll_interval)
        elapsed += poll_interval
        poll_interval = min(poll_interval + 5, 30)

    print(f"Timeout waiting for settlement (>{max_wait}s)")
    return None

# Usage
settlement = wait_for_settlement("ENC-2024-098765", "YOUR_API_KEY")

Python (AEOB Reconciliation Report)

import requests
from datetime import datetime

def generate_aeob_reconciliation_report(encounters, api_key):
    """
    Generate a reconciliation report comparing AEOB and settlement data.
    """
    headers = {"X-API-Key": api_key}
    report = []

    for encounter_id in encounters:
        response = requests.get(
            f"https://api.turquoise.health/tpa-api/v1/settlement/{encounter_id}/",
            headers=headers
        )

        if response.status_code != 200:
            continue

        data = response.json()
        aeob = data.get("aeob_match", {})

        report.append({
            "encounter_id": encounter_id,
            "settlement_id": data["settlement_id"],
            "aeob_reference": aeob.get("aeob_reference", "MISSING"),
            "aeob_amount": aeob.get("aeob_amount", 0),
            "settlement_amount": aeob.get("settlement_amount", 0),
            "variance": aeob.get("variance", 0),
            "match_status": aeob.get("match_status", "MISSING"),
            "completed_at": data.get("completed_at")
        })

    # Print report
    print("AEOB Reconciliation Report")
    print("=" * 80)
    print(f"Generated: {datetime.now().isoformat()}")
    print()

    matched = sum(1 for r in report if r["match_status"] == "EXACT")
    total = len(report)

    print(f"Summary: {matched}/{total} encounters match AEOB")
    print()

    for r in report:
        status_icon = "✓" if r["match_status"] == "EXACT" else "✗"
        print(f"{status_icon} {r['encounter_id']}")
        print(f"   AEOB: ${r['aeob_amount']:.2f} | Settlement: ${r['settlement_amount']:.2f} | Variance: ${r['variance']:.2f}")

    return report

Stripe Fee Structure

info

Stripe fees are calculated per provider per payout. Each provider typically incurs:

Transaction fee: 2.2% of transferred amount
Flat fee: $0.30 per payout

Example for $1,000 transfer:

Fee: ($1,000 × 0.022) + $0.30 = $22.30
Net to provider: $977.70

Settlement Status Values

Status	Meaning
`PENDING`	Encounter adjudicated but funding not yet approved
`INITIATED`	Stripe transfer created and queued for processing
`COMPLETED`	Funds successfully transferred and in provider accounts
`FAILED`	Transfer failed (network issue, invalid account, etc.)
`REFUNDED`	Transfer was reversed and funds returned

AEOB Matching Rules

EXACT — AEOB amount matches settlement amount exactly
VARIANCE — Amounts differ by more than $0.01 (investigate discrepancy)
MISSING_AEOB — No AEOB found in payer system (may not be issued yet)

warning

If match_status is VARIANCE, investigate immediately. Common causes:

Double billing detected and corrected
Late term termination adjustments
Interim payment then final adjudication
Payer system delay in AEOB generation

Contact payer support with the AEOB reference if variance cannot be explained.

Overview​

Endpoint​

Request​

Path Parameters​

Example Request​

Response​

Success Response (200 OK)​

Not Yet Settled (202 Accepted)​

Not Found (404 Not Found)​

Response Fields Explained​

Settlement Metadata​

Payout Object​

AEOB Reconciliation​

Examples​

cURL​

Python (Basic Settlement Check)​

Python (Multi-Provider Verification)​

Python (Wait for Settlement Completion)​

Python (AEOB Reconciliation Report)​

Stripe Fee Structure​

Settlement Status Values​

AEOB Matching Rules​