Skip to main content

​
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. 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 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 and Checkout states. 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.