Send the key

Put the key in the Authorization header of every request. Keys look like swpk_staging_… or swpk_production_…; the prefix names the environment the key was issued by, and a key only works against that environment's host. The platform API lives at /v1/… directly on the host, with no /api prefix.

curl https://swpcore.shopwired.io/v1/payments?merchant_id=swpm_8f3k2m&limit=1 \
  -H "Authorization: Bearer swpk_production_7Hq2…" \
  -H "User-Agent: ShopWired-Platform/1.0"

Identify your integration

Every platform API request must include a non-empty User-Agent header. Use a stable value that identifies your integration and, where practical, its release, for example ShopWired-Platform/1.0. Requests without this header are rejected with HTTP 403 and may return a plain response instead of the standard JSON error object.

API clients and keys

Your platform (plat_…) owns one or more API clients (apic_…). Each client has its own key, scopes, optional IP allowlist and rate limit, so you can give a reporting integration read-only scopes and keep writing scopes on the service that needs them.

Clients and keys are issued by SWP Core operators, not created through the API. Ask for one client per integration with the scopes it needs; new clients start with the minimal hosted onboarding scopes unless you ask for more, and existing clients never gain scopes silently.

The full key is returned exactly once, when the client is created or the key is rotated. After that only api_key_prefix is visible, because SWP Core stores a hash of the key rather than the key itself. If you lose a key, ask for a rotation: the new key is shown once and the old one stops working straight away, so plan the cut-over.

{
  "id": "apic_3k9d2p",
  "object": "api_client",
  "platform_id": "plat_7n1x4d",
  "environment": "production",
  "api_key_prefix": "swpk_production_7Hq2",
  "scopes": [
    "hosted_onboarding:read",
    "hosted_onboarding:write",
    "payments:read",
    "payments:write",
    "webhooks:manage"
  ],
  "allowed_ip_ranges": [
    "203.0.113.0/24"
  ],
  "rate_limit": 600,
  "rate_limit_window_ms": 60000,
  "rotated_at": null,
  "created_at": "2026-05-21T09:00:00Z"
}

Scopes

A request is rejected with 401 unauthorized when the key is missing, invalid or lacks the scope the endpoint needs. Each reference page names its required scope. Keep money-moving write scopes and webhooks:manage on separate clients from general read access.

IP allowlists and rate limits

An API client can carry allowed_ip_ranges, up to 50 IP addresses or CIDR ranges; requests from anywhere else are refused before they reach an endpoint, and whole-internet ranges are rejected. Each client also has a rate_limit over a rate_limit_window_ms, shared across every API instance. When you exceed it the response is 429 rate_limited with a Retry-After header; back off for at least that long before retrying. There are no rate-limit headers on successful responses.

Base URLs

Every platform endpoint in these docs is relative to one of those hosts, for example POST https://swpcore.shopwired.io/v1/account_links. There is no /api prefix on the platform API; use only the /v1/… routes documented here.

What differs

Hosted onboarding sessions are environment-matched: a link created with a staging key opens a staging onboarding journey on the staging host, so a mobile app that talks to a staging backend gets the matching session automatically.

Seeding staging merchants

When you create a staging account you can pass test_data_profile on POST /v1/accounts to pre-fill a plausible business, so you can reach the payment step without typing a company's details every time. The field is ignored in production.

Going to production

• Ask for a production API client with the scopes your integration actually uses; the key is shown once, so store it in your secrets manager straight away.
• Register production webhook endpoints and store their whsec_… secrets; staging endpoints do not carry over.
• Onboard your first production merchant through hosted onboarding and confirm readiness.ready_for_payments before you enable checkout for them.
• Confirm the card-reader models enabled for your production account before you offer device setup.

How it works

Send a unique Idempotency-Key header (a UUID is ideal) on requests that create or change something. If the request reaches SWP Core but the response never reaches you, send it again with the same key. On endpoints that support replay you get the stored response back, and the header x-swp-idempotency-replayed tells you it was a replay.

curl -X POST 'https://swpcore.shopwired.io/v1/payments/pay_7c1q9m/refunds?merchant_id=swpm_8f3k2m' \
  -H "Authorization: Bearer swpk_production_7Hq2…" \
  -H "User-Agent: ShopWired-Platform/1.0" \
  -H "Idempotency-Key: 5f4d6b7a-2e6c-4b1f-9a2e-refund-1" \
  -H "Content-Type: application/json" \
  -d '{ "amount_minor": "1099", "currency": "GBP" }'

What the key covers

A key is scoped to your platform, the API client, the merchant and the operation, so the same key on two different endpoints does not collide. SWP Core also fingerprints the request: the target, query, If-Match and body are hashed together. Reusing a key with a different body is rejected with 409 idempotency_conflict rather than silently returning the old result.

The raw key is never stored, logged, returned or forwarded to a processor. Replay records carry ids like idemop_…, are kept for at least 24 hours, and mutations return theirs in the X-Swp-Operation-Id header so you can poll the operation.

Which endpoints replay

Replay is adopted endpoint by endpoint rather than assumed, and each reference page says whether the endpoint requires the header. Today that is: creating, confirming and cancelling payment sessions; capturing and cancelling payments; refunds and refund step-up; accepting and challenging disputes; creating, activating, deactivating and duplicating payment links; requesting payouts; boarding, recovering and operating terminals and saving terminal settings; Tap to Pay activations; creating report runs and schedules. GET requests never need a key.

The error object

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "details": [
      {
        "path": [
          "amount_minor"
        ],
        "code": "invalid_string"
      }
    ]
  }
}

Recovery categories

Endpoints that return asynchronous operation failures may include a category. These categories describe what to do next; they are not guaranteed on every HTTP error.

Common codes

Handling errors well

• Branch on code. Use category as extra guidance when the endpoint returns it; messages can change.
• When retryable is present, follow it. Otherwise retry 429 and temporary 5xx responses with exponential backoff and the same Idempotency-Key.
• For timeout on a payment or terminal operation, read the operation before retrying so you do not double-charge.
• Log the response request_id or X-Request-Id when present, along with the HTTP status and error code.

Request parameters

The list envelope

{
  "object": "list",
  "url": "/v1/payments?merchant_id=swpm_8f3k2m",
  "has_more": true,
  "next_cursor": "pay_5n2v8k",
  "previous_cursor": null,
  "data": [
    {
      "id": "pay_7c1q9m",
      "object": "payment",
      "status": "captured"
    },
    {
      "id": "pay_5n2v8k",
      "object": "payment",
      "status": "authorised"
    }
  ]
}

Walking a list

let cursor = null;
do {
  const url = new URL("https://swpcore.shopwired.io/v1/payments");
  url.searchParams.set("merchant_id", "swpm_8f3k2m");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("starting_after", cursor);
  const page = await (await fetch(url, { headers })).json();
  for (const payment of page.data) process(payment);
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

<?php
$cursor = null;
do {
  $query = ["merchant_id" => "swpm_8f3k2m", "limit" => 100];
  if ($cursor) $query["starting_after"] = $cursor;
  $page = $swp->get("/v1/payments", $query);
  foreach ($page["data"] as $payment) process($payment);
  $cursor = $page["has_more"] ? $page["next_cursor"] : null;
} while ($cursor);

Money

Money fields use amount_minor, a decimal string in the currency's minor unit, alongside an uppercase ISO 4217 currency. £10.99 is { "amount_minor": "1099", "currency": "GBP" }. Some responses group those fields inside a named object such as amount; the endpoint schema shows where they sit. Strings avoid floating-point rounding and keep large amounts exact.

Time

Timestamps are UTC ISO 8601 strings with a trailing Z, for example 2026-05-21T09:00:00Z. Webhook envelopes and account links also use unix seconds for created and expires_at.

Ids

Every object has a prefixed id that tells you its type at a glance: merchants are swpm_…, payments pay_…, refunds payref_…, terminals term_…, events evt_…. The glossary lists them all. Processor ids such as pi_…, ch_… or acct_… are never accepted or returned.

Versions and If-Match

Mutable objects carry an integer version starting at 1. Send If-Match: {version} on updates when you need to be sure nobody changed the object since you read it; a mismatch returns 409 conflict and the current object.

Asynchronous operations

Anything that has to wait on a processor, such as a terminal collection, a payout or a report run, returns 202 Accepted with an operation object rather than blocking. Poll it, or subscribe to its events.

{
  "id": "termop_2m8x1q",
  "object": "terminal_operation",
  "merchant_id": "swpm_8f3k2m",
  "operation_type": "collect_payment",
  "status": "in_progress",
  "failure": null,
  "created_at": "2026-05-21T09:00:00Z",
  "updated_at": "2026-05-21T09:00:04Z",
  "version": 3
}

How it fits together

Your server creates the merchant's account and requests a short-lived hosted link. The merchant completes the journey on ShopWired Pay pages, including business details, identity verification, ownership, trading profile and payout bank account. When they return, read the account's readiness and enable payments only when it confirms that they can trade.

Step by step

1. 1

   Create the account

   Call POST /v1/accounts from your server with a merchant_reference for the store. Calling it again with the same reference returns the same account, so it is safe to retry. Pass prefill if you already hold the business details; it is applied on first creation only.

   Create the accountCopy

   {
     "merchant_reference": "store-1042",
     "client_reference_id": "shopwired:store:1042",
     "prefill": {
       "business": {
         "business_name": "Northgate Cycles Ltd",
         "company_number": "12345678",
         "country_of_registration": "GB",
         "website": "https://northgatecycles.example"
       }
     }
   }

2. 2

   Create an account link

   Call POST /v1/account_links with type account_onboarding. The url in the response is single use and expires after five minutes, so create it at the moment the merchant clicks, never at page load.

   Create the link

   cURLNode.jsPHP

   Copy

   curl -X POST 'https://swpcore.shopwired.io/v1/account_links' \
     -H "Authorization: Bearer swpk_production_7Hq2…" \
     -H "User-Agent: ShopWired-Platform/1.0" \
     -H "Content-Type: application/json" \
     -d '{
       "account": "swpm_8f3k2m",
       "type": "account_onboarding"
     }'

   Response200 OK

   {
     "object": "account_link",
     "created": 1779354600,
     "expires_at": 1779354900,
     "url": "https://swpcore.shopwired.io/hosted-onboarding/sessions/hobs_2x7c1q",
     "swp_account_id": "swpm_8f3k2m",
     "onboarding_application_id": "onba_4d9v0p",
     "processor_submission": {
       "submit_to": [
         "stripe"
       ],
       "wait_for": [
         "stripe"
       ],
       "wait_timeout_seconds": 30
     }
   }

   For normal onboarding, omit processor_submission. SWP Core applies the processors enabled for the environment. Use the processor-selection fields only when your integration has an agreed reason to override that default.
3. 3

   Send the merchant to the hosted flow

   On the web, redirect the browser. In an app, open the URL in a secure system browser sheet, never a generic embedded WebView. Return and refresh pages are SWP-hosted; if you want the merchant to land back on your own site afterwards, pass platform_return_url and platform_refresh_url together, on your API client's allowlist.

   Open the link

   WebiOSAndroid

   Copy

   // 1. Your server creates the link (never the browser)
   async function beginOnboarding(req, res) {
     const state = await createAndStoreOnboardingState({
       storeId: req.store.id,
       swpAccountId: req.store.swpAccountId,
     });
     const link = await swpFetch("/v1/account_links", {
       account: req.store.swpAccountId,
       type: "account_onboarding",
       return_nonce: state,
       // Core adds nonce=<return_nonce> to this URL exactly once.
       platform_return_url: "https://partner.example/onboarding/done",
       platform_refresh_url: "https://partner.example/onboarding/refresh",
     });
   
     // 2. Send the merchant to the hosted flow
     res.redirect(303, link.url);
   }
   
   app.post("/onboarding/start", beginOnboarding);
   // Refresh URLs are browser navigations, so they must accept GET.
   app.get("/onboarding/refresh", beginOnboarding);
   
   app.get("/onboarding/done", async (req, res) => {
     // The nonce resolves to the account stored before onboarding began.
     const state = await consumeOnboardingState(req.query.nonce);
     if (!state) return res.status(400).send("Invalid or expired onboarding return");
   
     // Never use req.query.swp_account_id or another browser-supplied id here.
     const account = await swpFetch(`/v1/accounts/${encodeURIComponent(state.swpAccountId)}`);
     res.render("onboarding-result", { account });
   });

   Never put an API key in a website or app. Generate and store the return state on your server, then reject a return whose nonce does not match. Return URLs must not be mobile deep links either; open the hosted return page and let it hand the browser on to platform_return_url.
4. 4

   Handle the return

   The hosted return page carries a status query parameter with swp_account_id, onboarding_application_id, an opaque hosted_onboarding_session reference and your nonce, then sends the browser on to your platform_return_url if you set one. Resolve the nonce to the account id your server stored before onboarding began, then read that account with GET /v1/accounts/{account}. Never select the account from swp_account_id, onboarding_application_id or another browser parameter. Treat every browser parameter as a hint and enable payments only when the server-to-server account response says readiness.ready_for_payments is true.

   completed

   Onboarding finished. Check readiness before enabling payments.

   pending_review

   Submitted. A processor is still reviewing the account.

   requires_more_information

   The merchant needs to supply more information. Create a new link.

   expired

   The link expired before it was used. Create a new one.

   GET /v1/accounts/swpm_8f3k2m200 OKCopy

   {
     "id": "swpm_8f3k2m",
     "object": "account",
     "swp_account_id": "swpm_8f3k2m",
     "onboarding_application_id": "onba_4d9v0p",
     "status": "onboarded",
     "readiness": {
       "state": "ready_for_payments",
       "submitted": true,
       "provider_submission_finished": true,
       "pending_review": false,
       "action_required": false,
       "restricted": false,
       "rejected": false,
       "approved": true,
       "ready_for_payments": true,
       "ready_for_payouts": false,
       "blocking_reasons": [
         "Payout bank account pending verification"
       ]
     },
     "details_submitted": true,
     "charges_enabled": true,
     "payouts_enabled": false,
     "capabilities": {
       "card_payments": "active",
       "in_person_payments": "active",
       "payouts": "pending"
     },
     "requirements": {
       "currently_due": [],
       "eventually_due": [],
       "past_due": [],
       "pending_verification": [
         "payout_bank_account"
       ],
       "disabled_reason": null,
       "errors": [],
       "items": []
     },
     "processor_submission": {
       "submit_to": [
         "stripe"
       ],
       "wait_for": [
         "stripe"
       ],
       "wait_timeout_seconds": 30,
       "response_wait": {
         "status": "satisfied",
         "wait_for": [
           "stripe"
         ],
         "pending_processors": [],
         "received_processors": [
           "stripe"
         ],
         "timed_out_processors": [],
         "timeout_seconds": 30,
         "started_at": "2026-05-21T09:13:40Z",
         "expires_at": "2026-05-21T09:14:10Z",
         "completed_at": "2026-05-21T09:13:52Z"
       }
     },
     "processor_accounts": [
       {
         "processor": "stripe",
         "processor_account_id": "acct_…",
         "status": "approved",
         "provider_status": null,
         "capabilities": {
           "card_payments": "active",
           "payouts": "pending"
         },
         "requirements_currently_due": []
       }
     ],
     "provider_outcomes": []
   }

   blocking_reasons explains why either readiness flag is false. In this example it applies only to payouts: payments are ready, while the payout bank account is still pending verification.
5. 5

   Listen for webhooks

   Subscribe to hosted_onboarding.session.completed and hosted_onboarding.session.failed, then account.updated, account.requirements_updated and account.capabilities_updated. An account.updated event is also sent when a processor account mapping first appears or changes, even if status and readiness stay the same; its account object includes processor_accounts[]. Processing can continue after the browser returns, so account events may arrive later even when you asked the link to wait. Read the account again whenever one arrives. Before going live, follow the linked Receive webhooks guide for raw-body signature verification, the five-minute timestamp tolerance, event-id de-duplication, out-of-order delivery and retry behaviour.

   Webhook deliveryCopy

   POST /webhooks/swp HTTP/1.1
   swp-event-id: evt_01j9x3v8q2
   swp-event-type: hosted_onboarding.session.completed
   swp-timestamp: 1779354888
   swp-signature: t=1779354888,v1=5f1c…
   
   { "id": "evt_01j9x3v8q2", "object": "event", "type": "hosted_onboarding.session.completed",
     "created": 1779354888,
     "data": { "object": { "swp_account_id": "swpm_8f3k2m", "status": "completed" } } }

Other hosted journeys

The same endpoint opens three more journeys by changing type:

{
  "account": "swpm_8f3k2m",
  "type": "account_update",
  "return_nonce": "stored_or_signed_platform_state",
  "platform_return_url": "https://partner.example/account/settings",
  "platform_refresh_url": "https://partner.example/account/settings/edit"
}

After onboarding

Requirements can appear later: a processor may ask for a document or a new director's details. Watch account.requirements_updated; when requirements.currently_due is not empty, create an account_update link (or send the merchant to the remediation link in the event) and let SWP Core collect what is needed.

Before you start

• The merchant's account must show readiness.ready_for_payments: true; see Accounts.
• Your checkout return_url must be on your API client's allowlist.
• You need an API client with payments:read and payments:write, and a webhook endpoint subscribed to payment.* events.

Step by step

1. 1

   Create the payment session

   When the customer reaches the payment step, create a session from your server with the amount in minor units, the ecommerce channel, your order references and the return_url. Use the checkout attempt id as the Idempotency-Key so a retried request cannot create two sessions.

   Create the session

   cURLNode.jsPHP

   Copy

   curl -X POST 'https://swpcore.shopwired.io/v1/payment-sessions' \
     -H "Authorization: Bearer swpk_production_7Hq2…" \
     -H "User-Agent: ShopWired-Platform/1.0" \
     -H 'Idempotency-Key: checkoutAttemptId' \
     -H "Content-Type: application/json" \
     -d '{
       "merchant_id": "swpm_8f3k2m",
       "channel": "ecommerce",
       "amount_minor": "4999",
       "currency": "GBP",
       "reference": "CHECKOUT-1001",
       "references": {
         "order_reference": "ORDER-1001",
         "order_id": "1001"
       },
       "customer": {
         "reference": "cust_1042",
         "email": "sam@example.com"
       },
       "return_url": "https://shop.example/checkout/return"
     }'

   Response201 Created

   {
     "id": "swpps_5n2v8k",
     "object": "payment_session",
     "payment_id": "pay_7c1q9m",
     "status": "requires_payment_method",
     "client_action": {
       "type": "secure_payment_component"
     },
     "expires_at": "2026-08-11T10:30:00Z"
   }

2. 2

   Render the secure payment component

   Hand the session id to the browser and mount the component. It collects card details inside an isolated frame and gives you back an opaque confirmation_artifact; your page never sees the card number. The component handles 3-D Secure and wallet prompts itself where it can.

   BrowserCopy

   // The session id is not a secret, but the API key still never leaves your server
   const component = SwpPayments.mount("#payment", {
     paymentSessionId: "swpps_5n2v8k",
     onReady: () => payButton.disabled = false,
   });
   
   payButton.addEventListener("click", async () => {
     const artifact = await component.collect();          // opaque confirmation_artifact
     const result = await fetch("/checkout/confirm", {   // your backend, step 3
       method: "POST",
       body: JSON.stringify({ artifact }),
     }).then((r) => r.json());
     if (result.status === "requires_customer_action") await component.handleAction(result);
   });

3. 3

   Confirm the session

   Post the artifact from your server with POST /v1/payment-sessions/{id}/confirm. If the response is requires_customer_action, let the component finish the action and confirm again with continue_after_action: true. A captured or authorised status means the money is committed; a failed status carries the reason in failure.

   Confirm

   cURLNode.jsPHP

   Copy

   curl -X POST 'https://swpcore.shopwired.io/v1/payment-sessions/swpps_5n2v8k/confirm' \
     -H "Authorization: Bearer swpk_production_7Hq2…" \
     -H "User-Agent: ShopWired-Platform/1.0" \
     -H 'Idempotency-Key: checkoutAttemptId-confirm' \
     -H "Content-Type: application/json" \
     -d '{
       "confirmation_artifact": {
         "token": "opaque-component-output"
       }
     }'

   Response200 OK

   {
     "object": "payment_session_confirmation",
     "payment_session_id": "swpps_5n2v8k",
     "payment_id": "pay_7c1q9m",
     "status": "captured",
     "client_action": null,
     "failure": null
   }

4. 4

   Complete the order from the webhook

   The browser can close at any moment, so treat the confirm response as a hint and the payment.captured (or payment.authorised for manual capture) event as the truth. Read the payment and drive your order state from order_completion_signal: paid, authorised_not_paid, pending or unsuccessful.

   payment.capturedCopy

   {
     "id": "evt_02k1m9z4",
     "object": "event",
     "type": "payment.captured",
     "data": {
       "object": {
         "id": "pay_7c1q9m",
         "object": "payment",
         "status": "captured",
         "order_completion_signal": "paid",
         "amount_minor": "4999",
         "currency": "GBP",
         "order_reference": "ORDER-1001"
       }
     }
   }

Authorise now, capture later

Create the session with capture_mode: "manual" to hold the funds and capture when you dispatch, with POST /v1/payments/{paymentId}/capture. You can capture the full amount or a smaller one once; the remainder is released. Cancel an authorisation you will not use with POST /v1/payments/{paymentId}/cancel. Authorisations expire, so watch payment.* events and the m-auth-expiring reminder the merchant receives.

When it goes wrong

Card readers

1. 1

   Give the merchant a location

   Readers belong to a location (a shop). Create one with POST /v1/terminal-locations, or call POST /v1/terminal-locations/default to get a default location without asking the merchant for an address.

2. 2

   Board the reader

   List GET /v1/terminal-device-models?country=GB to learn the boarding_method for the model, ask the user for the pairing code shown on the reader (or the one-time password), and call POST /v1/terminal-boarding-sessions. A 201 is definitive; a 202 is still pairing, so poll the session or wait for terminal.boarding.succeeded.

   Board an S700

   cURLNode.jsPHP

   Copy

   curl -X POST 'https://swpcore.shopwired.io/v1/terminal-boarding-sessions' \
     -H "Authorization: Bearer swpk_production_7Hq2…" \
     -H "User-Agent: ShopWired-Platform/1.0" \
     -H 'Idempotency-Key: boardingId' \
     -H "Content-Type: application/json" \
     -d '{
       "merchant_id": "swpm_8f3k2m",
       "terminal_location_id": "termloc_3d8s1q",
       "model_code": "s700",
       "display_name": "Front till",
       "boarding_method": "pairing_code",
       "boarding_credential": "apple-banana-cherry"
     }'

   Response201 Created

   {
     "id": "termboard_5p2x8k",
     "object": "terminal_boarding_session",
     "status": "succeeded",
     "terminal_id": "term_9f2k7m"
   }

3. 3

   Create a card-present payment session

   For each sale create a session with channel card_present (single amount) or till (line items, tips, split tender), the terminal_id, and the commercial_context and amount_breakdown in-person channels require. The session is returned as created with no client_action; the reader does the collecting.

   Create the session

   cURLNode.jsPHP

   Copy

   curl -X POST 'https://swpcore.shopwired.io/v1/payment-sessions' \
     -H "Authorization: Bearer swpk_production_7Hq2…" \
     -H "User-Agent: ShopWired-Platform/1.0" \
     -H 'Idempotency-Key: saleId' \
     -H "Content-Type: application/json" \
     -d '{
       "merchant_id": "swpm_8f3k2m",
       "channel": "card_present",
       "amount_minor": "2450",
       "currency": "GBP",
       "terminal_id": "term_9f2k7m",
       "reference": "TILL-0093",
       "amount_breakdown": {
         "subtotal_minor": "2450",
         "tip_minor": "0"
       },
       "commercial_context": {
         "staff_reference": "sam",
         "register_reference": "front-till"
       }
     }'

   Response201 Created

   {
     "id": "swpps_4w1r9c",
     "object": "payment_session",
     "payment_id": "pay_6t3p1k",
     "channel": "card_present",
     "terminal_id": "term_9f2k7m",
     "status": "created",
     "client_action": null,
     "expires_at": null
   }

4. 4

   Run the collect operation

   Bind the session to the reader with POST /v1/terminal-operations and operation_type collect_payment. The API answers 202; the reader wakes up and asks for a card. Poll GET /v1/terminal-operations/{id} every second or two, or follow terminal.operation.* events, and show the customer-facing state in your app.

   Collect on the reader

   cURLNode.jsPHP

   Copy

   curl -X POST 'https://swpcore.shopwired.io/v1/terminal-operations' \
     -H "Authorization: Bearer swpk_production_7Hq2…" \
     -H "User-Agent: ShopWired-Platform/1.0" \
     -H 'Idempotency-Key: saleId-collect' \
     -H "Content-Type: application/json" \
     -d '{
       "merchant_id": "swpm_8f3k2m",
       "terminal_id": "term_9f2k7m",
       "operation_type": "collect_payment",
       "payment_session_id": "swpps_4w1r9c",
       "refund_id": null
     }'

   Response202 Accepted

   {
     "id": "termop_2m8x1q",
     "object": "terminal_operation",
     "operation_type": "collect_payment",
     "status": "in_progress",
     "version": 2
   }

5. 5

   Finish, cancel or recover

   On succeeded the payment is captured; print or email the receipt. If the customer walks away, POST /v1/terminal-operations/{id}/cancel. If the outcome is unknown or the reader stops responding, do not create another operation: check GET /v1/terminals/{id}/readiness, and if recovery.available is true offer a single Recover reader button that calls POST /v1/terminals/{id}/recover. SWP Core verifies what happened and converges the payment; a sale that actually went through is never recorded as cancelled.

Tap to Pay on iPhone

1. 1

   Ask whether it is available

   GET /v1/tap-to-pay/configuration?merchant_id=… returns status ready or unavailable with a reason, activation_required, and which SDK the app should load (stripe_terminal_ios or adyen_pos_mobile_ios). Show Tap to Pay as unavailable rather than guessing; the Adyen SDK needs iOS 18.4 or later.

2. 2

   Activate the installation once

   POST /v1/tap-to-pay/activations with a stable app_instance_id returns a ttpinst_… id and the opaque client_session_data the SDK needs. Activation also ensures the merchant's default location exists.

3. 3

   Take the payment

   Create a session with channel tap_to_pay and the tap_to_pay_installation_id, start collection with POST /v1/payment-sessions/{id}/tap-to-pay, hand the returned collection to the SDK, and report the SDK's result with POST …/tap-to-pay/{collectionId}/result. Preauthorisations are not available on Tap to Pay.

Register an endpoint

Create an endpoint with the HTTPS URL to deliver to and the event types you want. The response includes the signing secret exactly once; store it with your other secrets. Private, loopback and cloud-metadata addresses are refused, and redirects are not followed.

curl -X POST 'https://swpcore.shopwired.io/v1/webhook_endpoints' \
  -H "Authorization: Bearer swpk_production_7Hq2…" \
  -H "User-Agent: ShopWired-Platform/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://partner.example/webhooks/swp",
    "enabled_events": [
      "payment.captured",
      "payment.refund.succeeded",
      "hosted_onboarding.session.completed",
      "account.requirements_updated"
    ]
  }'

const response = await fetch("https://swpcore.shopwired.io/v1/webhook_endpoints", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.SWP_API_KEY,
    "User-Agent": "ShopWired-Platform/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://partner.example/webhooks/swp",
    "enabled_events": [
      "payment.captured",
      "payment.refund.succeeded",
      "hosted_onboarding.session.completed",
      "account.requirements_updated"
    ]
  }),
});
const endpoint = await response.json();

<?php
$response = $http->request("POST", "https://swpcore.shopwired.io/v1/webhook_endpoints", [
  "headers" => [
    "Authorization" => "Bearer " . getenv("SWP_API_KEY"),
    "User-Agent" => "ShopWired-Platform/1.0",
  ],
  "json" => [
    "url" => "https://partner.example/webhooks/swp",
    "enabled_events" => ["payment.captured", "payment.refund.succeeded", "hosted_onboarding.session.completed", "account.requirements_updated"],
  ],
]);
$endpoint = json_decode($response->getBody(), true);

{
  "id": "whend_9q2m7c",
  "object": "webhook_endpoint",
  "api_client_id": "apic_3k9d2p",
  "url": "https://partner.example/webhooks/swp",
  "enabled_events": [
    "payment.captured",
    "payment.refund.succeeded",
    "hosted_onboarding.session.completed",
    "account.requirements_updated"
  ],
  "status": "active",
  "secret": "whsec_4Kq9…",
  "created_at": "2026-05-21T09:00:00Z"
}

What a delivery looks like

POST /webhooks/swp HTTP/1.1
content-type: application/json
user-agent: SWP-Core-Webhooks/1.0
swp-event-id: evt_01j9x3v8q2
swp-delivery-id: whdel_7f2k1m
swp-event-type: payment.captured
swp-timestamp: 1779357600
swp-signature: t=1779357600,v1=3c9e1f…

{
  "id": "evt_01j9x3v8q2",
  "object": "event",
  "type": "payment.captured",
  "created": 1779357600,
  "data": {
    "object": {
      "id": "pay_7c1q9m",
      "object": "payment",
      "status": "captured",
      "amount": {
        "amount_minor": "1099",
        "currency": "GBP"
      },
      "merchant_id": "swpm_8f3k2m"
    }
  },
  "previous_attributes": {
    "status": "authorised"
  }
}

Verify the signature

Compute HMAC-SHA256 over "{swp-timestamp}.{raw body}" with your endpoint secret, hex-encode it and compare with the v1 value in constant time. Reject anything older than 300 seconds to stop replays. Use the raw request bytes; re-serialising the JSON changes the signature.

import { createHmac, timingSafeEqual } from "node:crypto";

app.post("/webhooks/swp", express.raw({ type: "application/json" }), (req, res) => {
  const ts = req.get("swp-timestamp");
  const sig = req.get("swp-signature").split(",").find((p) => p.startsWith("v1=")).slice(3);
  const expected = createHmac("sha256", process.env.SWP_WEBHOOK_SECRET)
    .update(ts + "." + req.body.toString("utf8"))
    .digest("hex");

  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
  const valid = expected.length === sig.length && timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
  if (!fresh || !valid) return res.status(400).end();

  const event = JSON.parse(req.body);
  if (await alreadyHandled(event.id)) return res.status(200).end(); // swp-event-id de-duplicates
  await handle(event);
  res.status(200).end();
});

<?php
$raw = file_get_contents("php://input");
$ts = $_SERVER["HTTP_SWP_TIMESTAMP"];
parse_str(str_replace(",", "&", $_SERVER["HTTP_SWP_SIGNATURE"]), $parts);
$expected = hash_hmac("sha256", $ts . "." . $raw, getenv("SWP_WEBHOOK_SECRET"));

$fresh = abs(time() - (int) $ts) <= 300;
if (!$fresh || !hash_equals($expected, $parts["v1"])) {
  http_response_code(400);
  exit;
}

$event = json_decode($raw, true);
if (!already_handled($event["id"])) handle($event);
http_response_code(200);

Retries, ordering and replay

• Respond with any 2xx within a few seconds. Do the real work after you have acknowledged, on a queue.
• Timeouts, connection failures and 408, 409, 425, 429 and 5xx responses are retried: after 1 minute, 5 minutes, 30 minutes and then every 2 hours, up to 5 attempts. Other 4xx responses are not retried, and a 3xx is recorded as a failure rather than followed.
• Each attempt keeps the same swp-event-id, so de-duplicate on it; swp-delivery-id identifies the delivery.
• Events can arrive out of order. Treat each one as "this object changed" and read the object with the API when order matters.
• A delivery that keeps failing ends up dead_lettered. Fix the endpoint, then replay it with POST /v1/webhook_deliveries/{id}/replay, or replay the whole event with POST /v1/webhook_events/{id}/replay (optionally only to endpoints that failed).
• If operators disable an endpoint, its deliveries are recorded as disabled_endpoint and can be replayed once it is back.

Test it

POST /v1/webhook_endpoints/{id}/test sends a signed webhook_endpoint.test event straight away and returns the delivery result, so you can check verification before anything real happens. Every delivery and attempt is visible with GET /v1/webhook_events/{id}/deliveries and GET /v1/webhook_deliveries/{id}/attempts, including the status code your server returned and a snippet of its body.

1. 1

   Create the link as a draft

   Send the items excluding VAT with a VAT mode and rate per item; SWP Core calculates the totals. usage_type reusable keeps the page open for many customers; single_use closes it after one payment. checkout_options controls what the page asks for and the button label (pay, book or donate).

   Create a draft

   cURLNode.jsPHP

   Copy

   curl -X POST 'https://swpcore.shopwired.io/v1/payment-links' \
     -H "Authorization: Bearer swpk_production_7Hq2…" \
     -H "User-Agent: ShopWired-Platform/1.0" \
     -H 'Idempotency-Key: linkId' \
     -H "Content-Type: application/json" \
     -d '{
       "merchant_id": "swpm_8f3k2m",
       "definition_type": "itemised",
       "title": "Bike service",
       "billing_mode": "one_time",
       "currency": "GBP",
       "usage_type": "reusable",
       "vat_calculation_method": "per_line_item",
       "items": [
         {
           "name": "Full service",
           "unit_amount_excluding_vat_minor": "4999",
           "quantity": 1,
           "allow_quantity_adjustment": false,
           "vat": {
             "mode": "add_vat",
             "rate": "20"
           }
         }
       ],
       "checkout_options": {
         "confirmation_message": "Thanks. We will be in touch to book your slot.",
         "collect_billing_addresses": false,
         "require_phone_number": true,
         "allow_promotion_codes": false,
         "allow_business_tax_ids": false,
         "save_payment_details": false,
         "call_to_action": "book"
       }
     }'

   Response201 Created

   {
     "id": "swplink_8d2k1q",
     "object": "payment_link",
     "status": "draft",
     "url": "https://swpcore.shopwired.io/pay/swplink_8d2k1q",
     "total_amount_including_vat_minor": "5999",
     "pricing_status": "ready"
   }

2. 2

   Activate it

   POST /v1/payment-links/{id}/activate with an empty body. The merchant needs an approved card_payments capability; otherwise you get 409 payment_setup_incomplete. Activation is atomic and makes no processor calls, so it is instant.

3. 3

   Share the URL

   The url is stable for the life of the link. Put it in an email, an SMS, or a QR code on a counter card. The page collects the customer's details according to checkout_options and shows confirmation_message afterwards.

4. 4

   Watch for payments

   Each payment raises payment_link.payment_created and the usual payment.* events, with channel payment_link on the payment. GET /v1/payment-links/{id}/payments lists them.

5. 5

   Deactivate, duplicate or let it expire

   POST …/deactivate stops the page; history is kept. POST …/duplicate copies the definition into a fresh draft when you want a new version. Set expires_at on links that should close themselves, such as event tickets.

Using a link with your own checkout

If you render your own payment page but want the merchant to manage prices as a link, POST /v1/payment-links/{id}/payment-sessions creates an ordinary ecommerce session from the link. Fixed-amount links reject amount_minor; variable-amount links require it within the link's bounds. From there it is the same flow as Accept a payment.

Last updated: 14 October 2026, 04:17 BST (UK time).

Embedded Payments is currently enabled in staging. The production API has this capability disabled; wait for production activation before using it for a live checkout.

Replace https://core.example.com in the examples with the Core API base URL supplied for your environment.

How the integration works

1. 1

   Create or resume from your server

   For each payment-page render, call POST /v1/embedded-payments/sessions with the same stable order reference, trusted amount and exact HTTPS checkout origin. Keep your API key on the server. A new Idempotency-Key may be used for a new render; Core still resumes the same order payment.

2. 2

   Render your checkout

   For a payable response, put only the browser object into the page. Render one empty payment container, your own Pay button, an initial loader, and a message area.

3. 3

   Initialize and submit

   Load the classic script or ES module. Its creation promise resolves after the selected provider card component is ready; then hide your initial loader. Your button calls submit(). The SDK handles provider actions and its own in-container processing overlay.

4. 4

   Finish from server evidence

   Use onPaymentCompleted to navigate to your result page, not to mark the order paid. Mark it paid idempotently from a verified Core payment read showing authorisation or a signed payment.authorised webhook; track capture separately.

Create or resume the payment context

The server request requires a persistent integration API client with payments:write, merchant access, Idempotency-Key, and a non-empty User-Agent. Core takes capture mode from the merchant configuration; the browser does not choose the provider or capture mode. Set optional completion_mode to authorisation if your order-paid decision is based on verified payment.authorised and you want the checkout to complete before capture. Existing integrations default to capture. The full field and response contract is in Embedded Payments API.

curl -X POST https://core.example.com/v1/embedded-payments/sessions \
  -H 'Authorization: Bearer swpk_example' \
  -H 'Idempotency-Key: checkout-order-41082-render-1' \
  -H 'User-Agent: ExampleCheckout/1.0' \
  -H 'Content-Type: application/json' \
  -d '{"merchant_id":"swpm_example","order":{"reference":"ORDER-41082","amount_minor":"4999","currency":"GBP","country_code":"GB"},"completion_mode":"authorisation","allowed_origin":"https://checkout.example.com","return_url":"https://checkout.example.com/orders/41082/result?recovery=opaque"}'

A payable response contains browser: { session_id, client_secret, client_secret_expires_at }. processing contains retry_after_ms; show a pending state and retry safely. completed contains payment_id and completion_signal; recover the order from trusted server state. Do not put the entire server response or your API key into the page.

Classic-script entry point

<div id="payment"></div>
<button id="pay" type="button" disabled>Pay</button>
<script src="https://core.example.com/embedded-payments/assets/v0.1.0-preview2/embedded-payments.global.js"></script>
<script src="/your-checkout-integration.js"></script>

const gateway = await window.ShopWiredPay.EmbeddedPayments.create({
  session: BROWSER_SESSION,
  container: '#payment',
  onError: (error) => showPaymentError(error.message),
  onPaymentCompleted: () => window.location.assign(ORDER_RESULT_URL)
});
document.querySelector('#pay').disabled = false;
document.querySelector('#pay').addEventListener('click', () => gateway.submit());
// Call gateway.destroy() before permanently removing the payment view.

ES-module entry point

import { createEmbeddedPayments } from
  'https://core.example.com/embedded-payments/assets/v0.1.0-preview2/embedded-payments.mjs';
const gateway = await createEmbeddedPayments({
  session: BROWSER_SESSION,
  container: document.querySelector('#payment'),
  onError: (error) => showPaymentError(error.message),
  onPaymentCompleted: () => window.location.assign(ORDER_RESULT_URL)
});

Both entry points have the same options and methods. A rejected creation promise is an initialization failure and does not also call onError. Once creation resolves, submit() reports payment errors through onError. The host owns the initial loader and Pay button; the SDK owns the overlay inside its payment container.

Checkout origin and provider readiness

allowed_origin is the exact HTTPS origin where the component runs, including a non-default port if present—not the full page URL or the return URL. Derive it from trusted server configuration, not a browser-controlled header. Core binds its short-lived browser credential to this origin. When Adyen is selected, Core checks and, when necessary, registers that origin against the credential associated with the selected client key. Registration or provider readiness can fail; keep your initial loader until creation resolves and show a safe error if it rejects.

Provider returns and order recovery

Core consumes provider GET or POST return details on its own opaque return URL, then sends the browser with HTTP 303 to the return_url saved for that payment attempt. Your result URL should recover the intended order even if a different tab or browser session is current. It receives no provider details from Core and must not assume the redirect means the payment succeeded. If the outcome is still uncertain, show a pending state while verified status or a signed webhook converges.

Completion, capture, and webhooks

• Mark the order paid on a verified, signed payment.authorised event. This event is emitted for Embedded Payments under both automatic and manual capture. With completion_mode: authorisation, automatic-capture checkout also completes on authorisation with authorised_not_paid until capture settles; Core still handles capture. With manual capture the browser completion signal is likewise authorised_not_paid. The browser signal alone is not order-paid evidence.
• payment.captured records capture and does not need to be awaited to mark the order paid. If automatic capture is the first provider evidence Core sees, Core persists and emits authorisation before capture. These events may be delivered or retried independently; process them idempotently.
• Handle payment.failed as a failed payment attempt, not necessarily a terminal failure for the order; the customer may retry. Never mark an order paid solely because the browser invoked a callback or returned from 3-D Secure.
• A declined attempt can be retried in the same order session. An uncertain attempt retains the order claim while Core reconciles it; do not start a separate payment for the same sale.

Refunds

1. 1

   Check what is refundable

   Read the payment: refund_available says whether a refund would be accepted and refundable_amount_minor is the ceiling. A payment can be refunded in several parts until that reaches zero.

2. 2

   Create the refund with a key

   Send the amount, currency and supported reason, with a fresh Idempotency-Key. You get 202 and a payref_… object in requested; SWP Core submits it for processing asynchronously. If the response is lost, repeat the same request and key: you get the same refund back, never a second one.

   Refund part of a payment

   cURLNode.jsPHP

   Copy

   curl -X POST 'https://swpcore.shopwired.io/v1/payments/pay_7c1q9m/refunds?merchant_id=swpm_8f3k2m' \
     -H "Authorization: Bearer swpk_production_7Hq2…" \
     -H "User-Agent: ShopWired-Platform/1.0" \
     -H 'Idempotency-Key: refundId' \
     -H "Content-Type: application/json" \
     -d '{
       "amount_minor": "1000",
       "currency": "GBP",
       "reason": "customer_request",
       "reference": "ORDER-1001-R1"
     }'

   Response202 Accepted

   {
     "id": "payref_3m9x2c",
     "object": "payment_refund",
     "status": "requested",
     "amount_minor": "1000",
     "currency": "GBP",
     "refund_kind": "partial"
   }

3. 3

   Follow it to the end

   Subscribe to payment.refund.submitted, payment.refund.succeeded and payment.refund.failed, or poll GET /v1/refunds/{id}. Money usually reaches the customer's card three to five working days after submission. A requires_manual_review refund is with SWP operators; nothing you send will move it faster.

Disputes

1. 1

   Learn about it from the event

   payment.dispute.created carries the dispute with its reason, amount_minor, due_at and funds_status. The disputed amount is usually withdrawn from the balance at once; payment.dispute.funds_withdrawn confirms it.

2. 2

   Read the actions, not the status

   GET /v1/disputes/{id} returns actions with accept, challenge, edit_evidence and add_evidence, each available or blocked with a reason such as evidence_required or deadline_passed. Render your buttons from those flags.

3. 3

   Build the evidence draft

   Ask for an upload authorisation per file (POST …/evidence-assets/upload-authorizations, PDF, PNG or JPEG up to 5 MiB), upload the bytes, then save the draft with PUT …/evidence-draft, If-Match on its version and an Idempotency-Key. The detail's evidence_requirements tells you which fields the reason needs and what is still missing.

4. 4

   Challenge or accept before the deadline

   POST …/challenge with the draft version submits it; POST …/accept concedes. Both return 202 with an operation to poll. After the deadline the case closes as expired and nothing more can be sent.

5. 5

   Record the outcome

   payment.dispute.won reinstates the funds; payment.dispute.lost leaves them with the customer. fees on the detail records any dispute fee assessed.