> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skinloop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate a store platform

> Add Skinloop to a hosted storefront or e-commerce platform without requiring each merchant to own a website.

## How the integration works

The platform hosts the payment integration, return pages, and webhook receiver.
Each store owner uses **their own** Skinloop merchant account and API key.
Checkouts belong to the merchant identified by that key; never share a key
between stores or expose it in browser code. Merchants do not need a storefront
domain to connect Skinloop.

This is a key-based setup, not a one-click account connection. The merchant
must configure return URLs and a webhook endpoint in their Skinloop dashboard;
the API key cannot configure these settings.

## Choose the return-page setup

**Use fixed defaults only if all of this merchant's Skinloop checkouts can
share the same return pages.** Defaults are merchant-wide, **not scoped to a
platform installation**. They affect every new checkout that omits return URL
fields, including checkouts from other stores or integrations.

| Setup | What the platform sends | What the merchant configures in Skinloop |
| - | - | - |
| Shared, fixed return pages | Omit both `successUrl` and `cancelUrl` | Save the platform's complete URLs as **Default Success URL** and **Default Cancel URL** under **Checkout Configuration**. No redirect-origin entry is needed. |
| Different return pages per checkout or integration | Send complete `successUrl` and `cancelUrl` with each checkout | Approve the platform's HTTPS origin under **Checkout Configuration → Checkout Redirect Origins**. This approves the origin, not every individual path. |

Do **not** replace working defaults used by another integration. If its
checkouts omit URL fields, its future customers could be sent to the platform's
pages. Use per-checkout URLs instead, or a shared return page that safely
handles every installation. You can override just one saved default, but the
overridden URL's origin must be approved. Existing checkout sessions retain
the return URLs saved when they were created. See
[Create a hosted checkout](https://docs.skinloop.io/checkout/create.md) for both request options.

## What the platform shows the merchant

The platform should preconfigure the Skinloop API URL. Its **secure payment
settings should ask for only two values**:

1. **Skinloop API key:** the merchant creates it in Skinloop and enters it in
   the platform.
2. **Webhook signing secret:** Skinloop displays it when the merchant creates
   the webhook endpoint; the merchant enters it in the platform.

The platform **displays**, rather than asks the merchant to enter, its own
complete HTTPS success and cancel URLs and its webhook URL. The merchant copies
these **from the platform into Skinloop** as described below. The webhook URL
is not the merchant's storefront link. Keep the API key and signing secret on
the platform's server, never in storefront HTML, URLs, logs, or client-side
code.

## Platform implementation

1. Host stable success and cancel pages on a platform-owned HTTPS domain, such
   as `https://payments.platform.example/skinloop/INSTALLATION_ID/success`
   and `https://payments.platform.example/skinloop/INSTALLATION_ID/cancel`.
   For the fixed-default setup, they must safely serve every checkout using
   that merchant's defaults. An installation ID identifies a store
   configuration; it is not an authentication credential.
2. Host a public HTTPS webhook receiver before merchants connect, for example
   `https://payments.platform.example/webhooks/skinloop/INSTALLATION_ID`.
   Route each installation to its stored signing secret. Verify the signature
   **before** trusting the event or its merchant and order fields.
3. Create checkouts on the server with that merchant's key, a unique
   `merchantOrderId`, and an idempotency key per order attempt. Omit both
   return URL fields for the fixed-default setup; otherwise send the URLs
   under the approved platform origin. Redirect the customer to the returned
   `hostedUrl`.

## Merchant setup in Skinloop

For each store installation, the merchant:

1. Creates an API key with `checkout:create` and `checkout:read` and the
   games the store accepts, then enters it in the platform's secure payment
   settings.
2. In **Checkout Configuration**, follows the return-page option above:
   saves the platform-provided complete default URLs **only if they can be
   shared across all checkouts that omit URLs**; otherwise approves the
   platform's HTTPS origin for per-checkout URLs. A shop domain is not needed.
3. In **API & Webhooks**, creates an endpoint with the platform-provided
   webhook URL and subscribes to at least `payment.completed` and
   `payment.reverted`. Skinloop shows that endpoint's `whsec_...` signing
   secret when it is created. The merchant enters it in the platform's
   secure payment settings so the platform can verify incoming requests.

## Confirm payments safely

A browser return is **not** proof of payment. Save the checkout ID and expected
merchant, order, game, amount, and currency on the platform's server. Match
each verified webhook to the right installation and order, deduplicate by event
ID, and return 2xx after durably recording it. Fulfill only after
`payment.completed` with `fulfillmentAllowed: true`, or an equivalent
authoritative completed status lookup. Never fulfill from a return URL,
`payment.pending`, or an elapsed timer.

Fixed return pages cannot identify an order by themselves. Use a safe
server-side customer session and checkout-to-order mapping; otherwise show a
generic status page and let the store's order history show the confirmed
result. Never guess which order to display.

CS2 payments can remain in a Steam hold for eight days once the hold begins.
Keep the order pending until completion; on `payment.reverted`, do not fulfill.
The webhook receiver must remain available during the hold: events arrive as
new HTTP requests, not one long-lived connection. See
[Webhooks](https://docs.skinloop.io/webhooks/overview.md) and [Checkout states](https://docs.skinloop.io/checkout/states.md).

If return URLs change, merchants using defaults must update them before new
checkouts use the new pages. For per-checkout URLs, merchants must approve a
new origin before requests use it; changing only a path under an approved
origin needs no new approval. Keep old pages available for existing checkouts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.