POSTpartial

Complete a filing payment

An enrolled platform credential or account OAuth authenticates the host. Creation requires the filing item capability; subsequent calls use the host-bound checkout ID. The person must already have accepted the filing and separately approved its exact fee. Payment does not accept arbitration. Only one full-price USD filing is supported. Retries continue the same durable checkout. Unknown provider outcomes require reconciliation.

/api/agentic/checkout_sessions/{id}/completecompleteAgenticFilingCheckout

Authentication and authority

Use one listed account-session, scoped OAuth, or partner credential alternative. Account tokens retain the approving account’s authority. Cookie-authenticated writes require same-origin authorization. Alternatives are OR; schemes in one alternative are AND.

AgenticPlatformKey

Merchant-issued, rotatable platform credential for one enrolled agent host. Every private checkout request also requires its bound item capability.

AccountOAuth

Account tokens authorize only their approving account and case scope. S256 PKCE is mandatory on the code flow. Explicit reacceptance is required after Rules/disclosure changes.

Parameters

Name	Location	Requirement	Schema
`API-Version`	header	Required	`{"const":"2026-04-17"}`
`id`	path	Required	`{"type":"string"}`
`Filing-Payment-Handle` Optional original item capability. If supplied, it must match the checkout. The checkout ID and authenticated enrolled host identify the existing payment authority.	header	Optional	`{"type":"string","pattern":"^fph_[A-Za-z0-9_-]{43}$","example":"fph_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}`
`Idempotency-Key`	header	Required	`{"type":"string","minLength":1,"maxLength":200}`

Request body

Required request body.

application/json

{
  "$ref": "#/components/schemas/AgenticCheckoutComplete",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "payment_data": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "handler_id": {
          "const": "stripe"
        },
        "instrument": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "type": {
              "const": "card"
            },
            "credential": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "type": {
                  "const": "spt"
                },
                "token": {
                  "type": "string",
                  "writeOnly": true,
                  "pattern": "^spt_[A-Za-z0-9_]{1,256}$",
                  "example": "spt_synthetic"
                }
              },
              "required": [
                "type",
                "token"
              ]
            }
          },
          "required": [
            "type",
            "credential"
          ]
        }
      },
      "required": [
        "handler_id",
        "instrument"
      ]
    }
  },
  "required": [
    "payment_data"
  ]
}

Responses

200

Completed payment and fulfilled order. Unresolved payments return 409; retrieve the checkout for owner continuation.

application/json

{
  "$ref": "#/components/schemas/AgenticCheckoutSessionWithOrder",
  "allOf": [
    {
      "$ref": "#/components/schemas/AgenticCheckoutSession",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "ready_for_payment",
            "in_progress",
            "completed",
            "canceled",
            "requires_escalation"
          ]
        },
        "currency": {
          "const": "usd"
        },
        "line_items": {
          "type": "array",
          "minItems": 1,
          "maxItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "id": {
                "type": "string"
              },
              "item": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "id": {
                    "type": "string"
                  }
                },
                "required": [
                  "id"
                ]
              },
              "name": {
                "type": "string"
              },
              "quantity": {
                "const": 1
              },
              "unit_amount": {
                "type": "integer",
                "minimum": 50
              },
              "totals": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AgenticCheckoutTotal",
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "subtotal",
                        "total"
                      ]
                    },
                    "display_text": {
                      "type": "string"
                    },
                    "amount": {
                      "type": "integer",
                      "minimum": 50
                    }
                  },
                  "required": [
                    "type",
                    "display_text",
                    "amount"
                  ]
                }
              }
            },
            "required": [
              "id",
              "item",
              "name",
              "quantity",
              "unit_amount",
              "totals"
            ]
          }
        },
        "totals": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/AgenticCheckoutTotal",
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "subtotal",
                  "total"
                ]
              },
              "display_text": {
                "type": "string"
              },
              "amount": {
                "type": "integer",
                "minimum": 50
              }
            },
            "required": [
              "type",
              "display_text",
              "amount"
            ]
          }
        },
        "fulfillment_options": {
          "type": "array",
          "maxItems": 0,
          "example": [],
          "items": {}
        },
        "messages": {
          "type": "array",
          "maxItems": 0,
          "example": [],
          "items": {}
        },
        "links": {
          "type": "array",
          "maxItems": 0,
          "example": [],
          "items": {}
        },
        "protocol": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "version": {
              "const": "2026-04-17"
            }
          },
          "required": [
            "version"
          ]
        },
        "capabilities": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "payment": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "handlers": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "id": {
                        "const": "stripe"
                      },
                      "name": {
                        "const": "dev.acp.tokenized.card"
                      },
                      "config": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "merchant_id": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "merchant_id"
                        ]
                      },
                      "version": {
                        "const": "2026-04-17"
                      },
                      "spec": {
                        "type": "string",
                        "format": "uri"
                      },
                      "requires_delegate_payment": {
                        "const": true
                      },
                      "requires_pci_compliance": {
                        "const": false
                      },
                      "psp": {
                        "const": "stripe"
                      },
                      "config_schema": {
                        "type": "string",
                        "format": "uri"
                      },
                      "instrument_schemas": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    },
                    "required": [
                      "id",
                      "name",
                      "config",
                      "version",
                      "spec",
                      "requires_delegate_payment",
                      "requires_pci_compliance",
                      "psp",
                      "config_schema",
                      "instrument_schemas"
                    ]
                  }
                }
              },
              "required": [
                "handlers"
              ]
            }
          },
          "required": [
            "payment"
          ]
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        },
        "continue_url": {
          "type": "string",
          "format": "uri"
        },
        "order": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "id": {
              "type": "string"
            },
            "checkout_session_id": {
              "type": "string"
            },
            "permalink_url": {
              "type": "string",
              "format": "uri"
            },
            "adjustments": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "id",
                  "type",
                  "status",
                  "occurred_at",
                  "amount",
                  "currency"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "type": {
                    "const": "refund"
                  },
                  "status": {
                    "const": "completed"
                  },
                  "occurred_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "amount": {
                    "type": "integer",
                    "minimum": 50
                  },
                  "currency": {
                    "const": "usd"
                  }
                }
              }
            }
          },
          "required": [
            "id",
            "checkout_session_id",
            "permalink_url"
          ]
        }
      },
      "required": [
        "id",
        "status",
        "currency",
        "line_items",
        "totals",
        "fulfillment_options",
        "messages",
        "links",
        "protocol",
        "capabilities",
        "expires_at",
        "continue_url"
      ]
    },
    {
      "type": "object",
      "required": [
        "order"
      ],
      "properties": {
        "status": {
          "const": "completed"
        }
      }
    }
  ]
}

400

Missing idempotency key or unsupported protocol version.

application/json

{
  "$ref": "#/components/schemas/AgenticCheckoutError",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "invalid_request",
        "processing_error",
        "service_unavailable"
      ]
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "type",
    "code",
    "message"
  ]
}

401

Authentication required.

application/json

{
  "$ref": "#/components/schemas/AgenticCheckoutError",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "invalid_request",
        "processing_error",
        "service_unavailable"
      ]
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "type",
    "code",
    "message"
  ]
}

403

Current payment authority required.

application/json

{
  "$ref": "#/components/schemas/AgenticCheckoutError",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "invalid_request",
        "processing_error",
        "service_unavailable"
      ]
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "type",
    "code",
    "message"
  ]
}

409

Payment attempt exists or reconciliation is in progress.

application/json

{
  "$ref": "#/components/schemas/AgenticCheckoutError",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "invalid_request",
        "processing_error",
        "service_unavailable"
      ]
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "type",
    "code",
    "message"
  ]
}

422

Unsupported terms or changed idempotency payload.

application/json

{
  "$ref": "#/components/schemas/AgenticCheckoutError",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "invalid_request",
        "processing_error",
        "service_unavailable"
      ]
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "type",
    "code",
    "message"
  ]
}

503

Payment outcome unavailable; retry safely.

application/json

{
  "$ref": "#/components/schemas/AgenticCheckoutError",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "invalid_request",
        "processing_error",
        "service_unavailable"
      ]
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "type",
    "code",
    "message"
  ]
}

Example response

Successful response

{
  "id": "id_test",
  "status": "completed",
  "currency": "usd",
  "line_items": [
    {
      "id": "id_test",
      "item": {
        "id": "id_test"
      },
      "name": "Maya Chen",
      "quantity": 1,
      "unit_amount": 50,
      "totals": [
        {
          "type": "subtotal",
          "display_text": "Test-environment procedural message.",
          "amount": 50
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Test-environment procedural message.",
      "amount": 50
    }
  ],
  "fulfillment_options": [],
  "messages": [],
  "links": [],
  "protocol": {
    "version": "2026-04-17"
  },
  "capabilities": {
    "payment": {
      "handlers": [
        {
          "id": "stripe",
          "name": "dev.acp.tokenized.card",
          "config": {
            "merchant_id": "merchant_id_test"
          },
          "version": "2026-04-17",
          "spec": "https://partner.test.example/callbacks/peoples-court",
          "requires_delegate_payment": true,
          "requires_pci_compliance": false,
          "psp": "stripe",
          "config_schema": "https://partner.test.example/callbacks/peoples-court",
          "instrument_schemas": [
            "https://partner.test.example/callbacks/peoples-court"
          ]
        }
      ]
    }
  },
  "expires_at": "2026-08-09T12:00:00.000Z",
  "continue_url": "https://partner.test.example/callbacks/peoples-court",
  "order": {
    "id": "id_test",
    "checkout_session_id": "checkout_session_id_test",
    "permalink_url": "https://partner.test.example/callbacks/peoples-court"
  }
}

Errors

Read the response status and stable error code. See errors and rate limits for recovery. Refresh the resource before resolving a state or digest conflict.

Idempotency and retries

For throttling, honor Retry-After when present. Back off on retryable server failures.
Send a unique Idempotency-Key. An exact retry returns the stored result; reusing the key with a different request fails.
The request is accepted only when its credential, authority, case state, and resource preconditions are satisfied.

Use https://peoplescourt.ai with the test credential issued for your integration.

cURL

curl --request POST \
  --url 'https://peoplescourt.ai/api/agentic/checkout_sessions/id_test/complete' \
  --header 'Authorization: Bearer pk_test_replace_me' \
  --header 'API-Version: 2026-04-17' \
  --header 'Idempotency-Key: idem_test_12345678' \
  --header 'Content-Type: application/json' \
  --data '{
  "payment_data": {
    "handler_id": "stripe",
    "instrument": {
      "type": "card",
      "credential": {
        "type": "spt",
        "token": "spt_synthetic"
      }
    }
  }
}'

TypeScript / fetch

const input = {
  "payment_data": {
    "handler_id": "stripe",
    "instrument": {
      "type": "card",
      "credential": {
        "type": "spt",
        "token": "spt_synthetic"
      }
    }
  }
};

const response = await fetch("https://peoplescourt.ai/api/agentic/checkout_sessions/id_test/complete", {
  method: "POST",
  headers: {
    "Authorization": "Bearer pk_test_replace_me",
    "API-Version": "2026-04-17",
    "Idempotency-Key": "idem_test_12345678",
    "Content-Type": "application/json"
  },
  body: JSON.stringify(input),
});
if (!response.ok) throw await response.json();
const result = await response.json();

Python

import requests

response = requests.post(
    "https://peoplescourt.ai/api/agentic/checkout_sessions/id_test/complete",
    headers={
      "Authorization": "Bearer pk_test_replace_me",
      "API-Version": "2026-04-17",
      "Idempotency-Key": "idem_test_12345678",
      "Content-Type": "application/json"
    },
    json={"payment_data": {"handler_id": "stripe", "instrument": {"type": "card", "credential": {"type": "spt", "token": "spt_synthetic"}}}},
    timeout=30,
)
response.raise_for_status()
result = response.json()