Checkout status

Purpose

Use GET /v1/merchant-api/checkouts/{checkoutId}/status with the merchant API key to recover the current hosted checkout. Use signed webhooks as the primary notification path and status polling for recovery. Never infer completion from the browser return URL.

Status	Terminal	Fulfillment allowed	Meaning
`created`	No	No	Hosted session exists and awaits customer activity
`initiated`	No	No	A deposit was created and dispatch started
`pending`	No	No	Provider processing has started
`active`	No	No	The provider trade is active
`hold`	No	No	The CS2 trade is in its provider hold period
`completed`	Yes	Yes	Provider-verified payment completion
`canceled`	Yes	No	Customer or provider canceled the attempt
`declined`	Yes	No	Provider declined the attempt
`failed`	Yes	No	Processing failed
`reverted`	Yes	No	A progressing or completed payment was reversed
`expired`	Yes	No	The offer deadline passed before a trade was attached
`reconciliation_required`	Automation stops	No	The outcome is ambiguous and requires an operator

The normal forward path is created → initiated → pending or active → optional hold → completed. A checkout may instead move to an unsuccessful terminal state. Observable intermediate states can be skipped. Provider state is authoritative, so do not manufacture missing transitions.

Polling schedule and stopping rules

For a hosted checkout, poll every 3 seconds for the first 30 seconds, every 5 seconds until two minutes, then every 15 seconds until the offer deadline.
Move pending or active work to a background job when the customer leaves.
For hold, stop browser polling and use webhooks plus a background status check no more often than once per minute.
For checkout-deposit status, use the returned pollAfterSeconds as the minimum interval.
Stop ordinary polling on completed, canceled, declined, failed, reverted, or pre-trade expired.
Stop automation on reconciliation_required; only an operator may resume it.

Each request uses the bounded retry policy. Do not keep an HTTP request or browser tab running for the full lifetime of a trade.

Customer messaging

Status	Customer message
`created`	“Waiting for you to choose and submit items.”
`initiated`	“Your trade is being created.”
`pending`	“Your trade was submitted and is being verified.”
`active`	“Your trade is active. Keep this order open while verification finishes.”
`hold`	“Your CS2 trade is protected during the Steam hold. We will update the order after verification.”
`completed`	“Payment confirmed. Your order is being prepared.”
`canceled`	“The checkout was canceled. You can start a new attempt.”
`declined`	“The trade was declined. Review the details before trying again.”
`failed`	“The payment could not be completed. No fulfillment was scheduled.”
`reverted`	“The payment requires review. Support has been notified.”
`expired`	“This checkout expired before a trade was attached. Start a new attempt.”
`reconciliation_required`	“We are reviewing this payment. Do not submit another payment for this order.”

These are suggested merchant UI messages, not additional API fields.

Expiry and protected trades

expiresAt is the deadline for attaching a trade to the checkout. If a checkout is still created when that deadline passes, it becomes pre-trade expired; release the reservation and allow an explicit new attempt with a new idempotency key. Once a deposit is attached, the offer deadline does not cancel the protected trade. Its deposit status capability remains valid after expiresAt, and the trade can still progress through pending, active, hold, and completed. Do not release or replace an attached trade merely because the original checkout deadline passed. For CS2, reservationRequired is true. Once hold begins, keep the order reserved and do not fulfill, credit, delete, or release it until payment.completed. Use holdUntil from the API, not a browser timer. fulfillmentAllowed is false until completion. On canceled, declined, or failed outcomes it remains false and you may release the reservation. For reverted, first determine whether fulfillment or credit already occurred; if it may have, keep the order protected and reconcile.

Confirm and enqueue

const result = await fetch(
  `${baseUrl}/v1/merchant-api/checkouts/${checkoutId}/status`,
  {
    headers: { Authorization: `Bearer ${apiKey}` },
    signal: AbortSignal.timeout(10_000)
  }
);
if (!result.ok) {
  const error = await result.json().catch(() => null);
  throw new Error(
    `status request failed: ${result.status}, ` +
    `code ${error?.error?.code ?? "unknown"}, ` +
    `request ${error?.error?.request_id ?? result.headers.get("x-request-id")}`
  );
}
const checkout = await result.json();

if (checkout.status === "completed" && checkout.fulfillmentAllowed === true) {
  // This transaction only records completion and enqueues a unique durable job.
  // It never calls an external fulfillment service.
  await recordCompletionAndEnqueue({
    checkoutId: checkout.id,
    merchantOrderId: checkout.merchantOrderId
  });
}

Conflicting and out-of-order observations

Skinloop accepts only valid provider lifecycle transitions, ignores delayed lower-state callbacks, and exposes the provider payment state when one exists. Your integration must still handle network reordering:

Authenticate webhooks before using them.
Deduplicate each webhook by event id.
Require the event type and body status to agree.
Match the webhook merchant order ID, external payment ID, requiredAmount, and currency against stored values. The webhook amount is the actual accepted skin value and can be higher than requiredAmount.
Require the actual accepted amount to be at least the required amount and verify the reported overpayment difference using integer cents.
If a webhook appears older than local state or conflicts with polling, fetch the current checkout status and use that current projection.
Never move from completed back to an in-progress state.
Treat reverted after completion as a reversal requiring reconciliation, not as a new checkout attempt.
Stop automation on any identity conflict.

`reconciliation_required` operator process

Stop polling retries, fulfillment, reservation release, and new checkout creation for the order.
Keep the order and any CS2 reservation protected.
Save the merchant order ID, checkout ID, deposit ID when available, latest request ID, webhook event IDs, and observed timestamps.
Check whether a fulfillment job exists or a destination delivery may already have occurred.
Contact Skinloop support without sending API keys or webhook secrets.
Resume only after the payment and delivery outcome are confirmed. Record the operator decision in an audit trail.

Expected result: one order is fulfilled at most once, only after completed. Polling and webhook handlers call the same enqueue operation. Implement the worker and crash recovery in Safe fulfillment. Use webhooks for durable notifications and review the state map for endpoint-specific enums.

Getting started

Hosted checkout

Player balance deposits

Store integrations

Payments and payouts

Webhooks and reliability

Resources

API reference

Purpose

Polling schedule and stopping rules

Customer messaging

Expiry and protected trades

Confirm and enqueue

Conflicting and out-of-order observations

`reconciliation_required` operator process

​Purpose

​Polling schedule and stopping rules

​Customer messaging

​Expiry and protected trades

​Confirm and enqueue

​Conflicting and out-of-order observations

​reconciliation_required operator process

Purpose

Polling schedule and stopping rules

Customer messaging

Expiry and protected trades

Confirm and enqueue

Conflicting and out-of-order observations

`reconciliation_required` operator process