# Contract Status API

> Query contract or payment address deployment status.

Canonical: https://stafiel.org/documentation/developer-integration/contract-status-api
Version: v1.0.0

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](#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.