API reference

Two integrations, two surfaces. Agents call hosted MCP at https://staging.mcp.sohopay.xyz/mcp. Tool names and sequences live in the skills at https://agents.sohopay.xyz/skills/v1/ and in Payment flow. They are not REST resources in this reference. Merchants call https://staging.api.sohopay.xyz/api/v1/facilitator with a merchant JWT or an sk_live_ API key. The OpenAPI document next to this page lists those routes only.

Method and path	Purpose
`POST /facilitator/verify`	Check a version-2 credit envelope. Does not capture.
`POST /facilitator/capture`	Queue the payment and return a signed receipt. Send `Idempotency-Key`.
`GET /facilitator/settle/status/by-payment/{paymentId}`	Poll by the receipt’s `paymentId`.
`GET /facilitator/settle/status/{jobId}`	Poll by the batch confirmation job id, once one exists.
`GET /facilitator/supported`	Scheme, version, network, and asset.
`GET /facilitator/health`	Liveness.

There is no POST /facilitator/settle. Settlement is the scheduled batch.

Use this reference for anything you ship. These pages are the facilitator contract.

Overview

Endpoints

Next steps

Merchant integration

Errors

​Next steps

Merchant integration

Errors

Next steps