Contract Status API

Query contract or payment address deployment status.

Use the Contract Status API to inspect the payment contract or payment address state for an order.

Endpoint

GET /api/v1/orders/{orderId}/contract

Parameters

Field	Required	Default	Description
`orderId`	Yes	None	Path parameter. Stafiel order ID.
`merchantId`	Yes	None	Query parameter. Merchant ID bound to the API key.

Request Example

curl "https://api.stafiel.com/api/v1/orders/ord_your_order_id/contract?merchantId=mch_your_merchant_id" \
  -H "X-API-Key: mk_live_your_api_key" \
  -H "X-App-Client: merchant-client"

Success Response

{
  "success": true,
  "data": {
    "contractAddress": "0x2222222222222222222222222222222222222222",
    "deploymentStatus": "deployed",
    "deploymentTxHash": "0xabc123...",
    "deployedAt": "2026-05-19T12:03:00.000Z",
    "chainId": 8453,
    "chainName": "base",
    "addressVerificationStatus": "verified",
    "isInitialized": true,
    "sweepOpenAt": "2026-05-21T12:00:00.000Z",
    "sweepExtendMaxAt": "2026-05-23T12:00:00.000Z",
    "createdAt": "2026-05-19T12:00:00.000Z",
    "updatedAt": "2026-05-19T12:03:00.000Z"
  }
}

Response Fields

Field	Type	Description
`contractAddress`	string or null	Payment contract or payment address. May be predicted before deployment.
`deploymentStatus`	string	Standardized deployment status. See Deployment Statuses.
`deploymentTxHash`	string or null	Deployment transaction hash when available.
`deployedAt`	string or null	ISO 8601 deployment timestamp when available.
`chainId`	number	Numeric chain ID.
`chainName`	string	Canonical public chain label.
`addressVerificationStatus`	string	Address verification status: `verified`, `pending`, or `failed`.
`isInitialized`	boolean	Whether the payment contract or program state is initialized.
`sweepOpenAt`	string or null	Time when settlement can become available for the order.
`sweepExtendMaxAt`	string or null	Latest time to which the sweep window can be extended, when applicable.
`createdAt`	string	ISO 8601 creation timestamp.
`updatedAt`	string	ISO 8601 update timestamp.

How To Use It

Use this endpoint for operational diagnostics and support workflows. It is not required for a basic hosted checkout integration.

sweepOpenAt describes when settlement can become available. With isInitialized, it also helps diagnose refund eligibility; amount, network support, and refund history still apply.

Deployment Statuses

Status	Meaning
`not_started`	Deployment has not started.
`not_deployed`	No deployed payment contract or address is available.
`pending_deployment`	Deployment or provisioning is in progress.
`on_hold`	Deployment or provisioning is on hold.
`deployed`	Payment contract or payment address is ready.
`deployment_failed`	Deployment failed.
`deployment_cancelled`	Deployment was cancelled.

Error Responses

HTTP Status	Code	Meaning
`400`	`VALIDATION_ERROR`	Query parameter is invalid or unsupported.
`401`	`AUTH_FAILED`	API key is missing, invalid, or cannot access the requested merchant or order.
`403`	`AUTHORIZATION_ERROR`	Request is authenticated but not allowed.
`404`	`NOT_FOUND`	Order does not exist or is not visible.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests. Retry after the indicated time.