First checkout

Step	What to do
1. Save the order	Store its USD-cent amount and a unique idempotency key before calling Skinloop.
2. Create a checkout	Call Create checkout with `checkout:create`. Save the returned checkout ID.
3. Redirect	Send the customer to the returned `hostedUrl`, without changing it.
4. Confirm payment	Verify a signed webhook, or read the status with `checkout:read`.
5. Deliver once	Queue duplicate-safe fulfillment only for `completed` and `fulfillmentAllowed: true`.

1. Persist the order before creating a checkout

Create your local order first. Store integer USD cents, a monotonically increasing attempt number, and the exact idempotency key used for that attempt:

CREATE TABLE merchant_orders (
  merchant_order_id TEXT PRIMARY KEY,
  customer_email TEXT NOT NULL,
  amount_minor BIGINT NOT NULL CHECK (amount_minor > 0),
  currency TEXT NOT NULL CHECK (currency = 'USD'),
  checkout_attempt INTEGER NOT NULL CHECK (checkout_attempt > 0),
  checkout_idempotency_key TEXT NOT NULL UNIQUE,
  checkout_id TEXT UNIQUE,
  checkout_expires_at TIMESTAMPTZ,
  checkout_hold_until TIMESTAMPTZ,
  payment_status TEXT NOT NULL DEFAULT 'created',
  reservation_status TEXT NOT NULL DEFAULT 'reserved',
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

INSERT INTO merchant_orders (
  merchant_order_id,
  customer_email,
  amount_minor,
  currency,
  checkout_attempt,
  checkout_idempotency_key
) VALUES (
  'order_123',
  '[email protected]',
  4999,
  'USD',
  1,
  'skinloop:checkout:v1:order_123:1'
);

Persisting the key first makes recovery safe. If your process stops after Skinloop creates the checkout but before your update commits, retry with the same request and key. Skinloop returns the original checkout instead of creating another one.

2. Create and persist the hosted checkout

This server function reads the expected order, calls the real hosted-checkout endpoint, validates the returned identity, and stores the checkout ID before it returns the redirect URL:

import { Pool } from "pg";

const db = new Pool({ connectionString: process.env.DATABASE_URL });
const baseUrl = process.env.SKINLOOP_API_BASE_URL;
const apiKey = process.env.SKINLOOP_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Skinloop configuration is missing");

type HostedCheckout = {
  id: string;
  merchantOrderId: string;
  amount: { value: number; currency: "USD" };
  allowedGames: ("cs2" | "rust")[];
  hostedUrl: string;
  status: string;
  expiresAt: string;
  reservationRequired: boolean;
  fulfillmentAllowed: boolean;
  holdUntil: string | null;
};

async function createOrderCheckout(merchantOrderId: string) {
  const local = await db.query(
    `SELECT merchant_order_id, customer_email, amount_minor, currency,
            checkout_id, checkout_idempotency_key
       FROM merchant_orders
      WHERE merchant_order_id = $1`,
    [merchantOrderId]
  );
  const order = local.rows[0];
  if (!order) throw new Error("order not found");

  const response = await fetch(`${baseUrl}/v1/merchant-api/checkouts`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Idempotency-Key": order.checkout_idempotency_key,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      merchantOrderId: order.merchant_order_id,
      customerEmail: order.customer_email,
      amount: { value: Number(order.amount_minor), currency: order.currency },
      allowedGames: ["cs2", "rust"],
      successUrl: "https://merchant.example/paid",
      cancelUrl: "https://merchant.example/canceled",
      expiresInSeconds: 3600
    }),
    signal: AbortSignal.timeout(10_000)
  });

  if (!response.ok) {
    const requestId = response.headers.get("x-request-id");
    throw new Error(`Skinloop create failed: HTTP ${response.status}, request ${requestId}`);
  }

  const checkout = await response.json() as HostedCheckout;
  if (
    !/^cs_[A-Za-z0-9_-]{32,}$/.test(checkout.id) ||
    checkout.merchantOrderId !== order.merchant_order_id ||
    checkout.amount.value !== Number(order.amount_minor) ||
    checkout.amount.currency !== order.currency ||
    typeof checkout.hostedUrl !== "string"
  ) {
    throw new Error("Skinloop checkout identity conflict");
  }

  const saved = await db.query(
    `UPDATE merchant_orders
        SET checkout_id = $2,
            checkout_expires_at = $3,
            payment_status = $4,
            updated_at = now()
      WHERE merchant_order_id = $1
        AND (checkout_id IS NULL OR checkout_id = $2)
    RETURNING merchant_order_id`,
    [merchantOrderId, checkout.id, checkout.expiresAt, checkout.status]
  );
  if (saved.rowCount !== 1) throw new Error("local checkout identity conflict");

  return checkout;
}

201 means Skinloop created the checkout. 200 means the same idempotent request recovered an existing checkout. Handle both identically.Expose this through an authenticated route in your own application. The browser calls your route; it never calls Skinloop with the merchant key.

3. Redirect the customer

Redirect to the exact hostedUrl returned by your server. Do not construct or modify it:

const response = await fetch("/api/orders/order_123/checkout", {
  method: "POST",
  credentials: "include"
});
if (!response.ok) throw new Error("checkout could not be started");

const { hostedUrl } = await response.json();
window.location.assign(hostedUrl);

The success and cancellation URLs are navigation only. Show a “confirming payment” state there while your server waits for a signed webhook or reads the checkout status.

4. Confirm authoritative completion

Use the signed webhook receiver as the primary path. After authenticating the event, look up the local order with data.merchantOrderId, verify data.requiredAmount and data.currency exactly against the stored order, and call the same recordCompletionAndEnqueue operation shown below. data.amount is the actual accepted skin value and can be greater than data.requiredAmount; require it to be at least the required amount and verify data.overpaymentAmount equals the difference. Convert all three decimal strings to integer cents without binary floating point.Use status polling as recovery when a webhook is delayed. The real status endpoint returns the same hosted-checkout projection:

const IN_PROGRESS = new Set([
  "created", "initiated", "pending", "active", "hold"
]);
const TERMINAL_FAILURES = new Set([
  "canceled", "declined", "failed", "expired"
]);

async function refreshCheckout(merchantOrderId: string) {
  const local = await db.query(
    `SELECT merchant_order_id, amount_minor, currency, checkout_id
       FROM merchant_orders
      WHERE merchant_order_id = $1`,
    [merchantOrderId]
  );
  const order = local.rows[0];
  if (!order?.checkout_id) throw new Error("stored checkout not found");

  const response = await fetch(
    `${baseUrl}/v1/merchant-api/checkouts/${encodeURIComponent(order.checkout_id)}/status`,
    {
      headers: { Authorization: `Bearer ${apiKey}` },
      signal: AbortSignal.timeout(10_000)
    }
  );
  if (!response.ok) {
    const requestId = response.headers.get("x-request-id");
    throw new Error(`Skinloop status failed: HTTP ${response.status}, request ${requestId}`);
  }

  const checkout = await response.json() as HostedCheckout;
  if (
    checkout.id !== order.checkout_id ||
    checkout.merchantOrderId !== order.merchant_order_id ||
    checkout.amount.value !== Number(order.amount_minor) ||
    checkout.amount.currency !== order.currency
  ) {
    throw new Error("Skinloop status identity conflict");
  }

  if (
    checkout.status === "completed" &&
    checkout.fulfillmentAllowed === true
  ) {
    await recordCompletionAndEnqueue({
      checkoutId: checkout.id,
      merchantOrderId: checkout.merchantOrderId
    });
    return "fulfillment_queued";
  }

  if (checkout.status === "reconciliation_required") {
    await markOrderForReconciliation(checkout.merchantOrderId, checkout.id);
    return "manual_reconciliation";
  }

  if (checkout.status === "reverted") {
    await markOrderForReconciliation(checkout.merchantOrderId, checkout.id);
    return "payment_reverted";
  }

  if (TERMINAL_FAILURES.has(checkout.status)) {
    await recordTerminalFailureAndReleaseReservation(
      checkout.merchantOrderId,
      checkout.id,
      checkout.status
    );
    return "terminal_failure";
  }

  if (IN_PROGRESS.has(checkout.status)) {
    await recordProgressAndKeepReservation(
      checkout.merchantOrderId,
      checkout.id,
      checkout.status,
      checkout.holdUntil
    );
    return "still_processing";
  }

  throw new Error(`unknown checkout status: ${checkout.status}`);
}

The three state helpers above can be implemented as guarded updates. Requiring the stored checkout ID prevents a result from one attempt from changing another attempt:

async function recordProgressAndKeepReservation(
  merchantOrderId: string,
  checkoutId: string,
  status: string,
  holdUntil: string | null
) {
  const result = await db.query(
    `UPDATE merchant_orders
        SET payment_status = $3,
            reservation_status = 'reserved',
            checkout_hold_until = $4,
            updated_at = now()
      WHERE merchant_order_id = $1 AND checkout_id = $2
    RETURNING merchant_order_id`,
    [merchantOrderId, checkoutId, status, holdUntil]
  );
  if (result.rowCount !== 1) throw new Error("checkout does not match order");
}

async function recordTerminalFailureAndReleaseReservation(
  merchantOrderId: string,
  checkoutId: string,
  status: string
) {
  const result = await db.query(
    `UPDATE merchant_orders
        SET payment_status = $3,
            reservation_status = 'released',
            updated_at = now()
      WHERE merchant_order_id = $1 AND checkout_id = $2
    RETURNING merchant_order_id`,
    [merchantOrderId, checkoutId, status]
  );
  if (result.rowCount !== 1) throw new Error("checkout does not match order");
}

async function markOrderForReconciliation(
  merchantOrderId: string,
  checkoutId: string
) {
  const result = await db.query(
    `UPDATE merchant_orders
        SET payment_status = 'reconciliation_required',
            reservation_status = 'reserved',
            updated_at = now()
      WHERE merchant_order_id = $1 AND checkout_id = $2
    RETURNING merchant_order_id`,
    [merchantOrderId, checkoutId]
  );
  if (result.rowCount !== 1) throw new Error("checkout does not match order");

  await alertOperations({ merchantOrderId, checkoutId });
}

Poll with bounded exponential backoff and jitter, or use a scheduled recovery job. Do not run an unbounded request loop in the customer’s browser. Webhooks and polling can observe completion concurrently, so both must call the same enqueue operation.

5. Schedule duplicate-safe fulfillment

recordCompletionAndEnqueue must update the order and insert one durable job in the same local database transaction. The complete implementation is in Safe fulfillment. Its unique checkout_id, merchant_order_id, and idempotency_key constraints make a duplicate webhook or simultaneous status poll return the existing job.The fulfillment worker runs separately after the handler commits. It sends the same stable destination idempotency key on every attempt:

skinloop:fulfillment:v1:<merchantOrderId>:<checkoutId>

Never call the external fulfillment destination from the webhook request, status poller, success page, or checkout-creation route.

6. Handle every non-success outcome

Status	Local action	Start a new checkout?
`created`, `initiated`, `pending`, `active`	Keep the order reserved and wait	No
`hold`	Keep the CS2 order reserved until a later authoritative state; use `holdUntil` for display and operations	No
`completed` with `fulfillmentAllowed: true`	Commit completion and the unique fulfillment job together	No
`canceled`, `declined`, `failed`	Record the terminal result and release the reservation	Only after an explicit customer retry
`reverted`	Stop automation and reconcile, especially if fulfillment or credit may already have occurred	No
`expired`	Record expiration and release the pre-trade reservation	Only after an explicit customer retry
`reconciliation_required`	Stop automation, keep the order protected, alert an operator, and contact Skinloop support with the checkout and request IDs	No

For a customer retry after a safe terminal result, increment checkout_attempt, persist a new idempotency key, and then create a new checkout. Never replace a pending, active, hold, completed, or reconciliation-required checkout.If the fulfillment destination times out after it may have delivered the order, do not create another checkout or blindly deliver again. Query the destination with the same idempotency key. If its result cannot be determined, set the fulfillment job to needs_reconciliation and require manual review.

End-to-end result

The integration is complete when:

refreshing or retrying checkout creation recovers the same Skinloop checkout,
the customer is redirected only to the returned hostedUrl,
redirects never mark an order paid,
only an authenticated completed result with fulfillmentAllowed: true enqueues fulfillment,
webhook delivery and polling converge on one fulfillment job,
safe terminal failures release the reservation, and
ambiguous payment or delivery outcomes stop for reconciliation instead of risking a duplicate order.

Getting started

Hosted checkout

Player balance deposits

Store integrations

Payments and payouts

Webhooks and reliability

Resources

API reference

Integration steps

Prerequisites

Complete integration example

1. Persist the order before creating a checkout

2. Create and persist the hosted checkout

3. Redirect the customer

4. Confirm authoritative completion

5. Schedule duplicate-safe fulfillment

6. Handle every non-success outcome

End-to-end result

​Integration steps

​Prerequisites

​Complete integration example

​1. Persist the order before creating a checkout

​2. Create and persist the hosted checkout

​3. Redirect the customer

​4. Confirm authoritative completion

​5. Schedule duplicate-safe fulfillment

​6. Handle every non-success outcome

​End-to-end result

Integration steps

Prerequisites

Complete integration example

1. Persist the order before creating a checkout

2. Create and persist the hosted checkout

3. Redirect the customer

4. Confirm authoritative completion

5. Schedule duplicate-safe fulfillment

6. Handle every non-success outcome

End-to-end result