Complete pairing and provision store credentials

Called by the store plugin (HMAC auth) after the merchant installs the plugin and the admin has triggered pairing from the console. The plugin supplies its one-time pairing code plus platform-specific store API credentials scoped to Sarvex’s needs. Sarvex validates the credentials, provisions signing keys, encrypts and persists the credentials server-side, and marks the connector healthy.

The store_credentials payload is platform-specific and optional in the wire envelope (a deployment where credentials are provisioned out-of-band may omit it), but live checkout and write-back require credentials to be present.

Credential boundary: store_credentials carries integration credentials (REST API keys, webhook secrets) — not payment credentials. Payment credentials are never handled here; see the payment-credential boundary invariant.

POST/connectors/pairing/complete

Authorization

X-Sarvex-SignatureAPI key · headerrequired

HMAC-SHA256 signature over the raw request body plus the X-Sarvex-Timestamp and X-Sarvex-Sequence headers, keyed by the per-connector signing secret issued at pairing. Used only by the store plugin for /connector/*. Replays (seen sequence) are rejected with 409.

Request body

requiredapplication/json

connector_idstringrequired

The connector ID returned by POST /connectors at begin-pairing.

pairing_codestringrequired

One-time pairing code issued to the console operator.

store_credentialsstore_credentials_woocommerce | store_credentials_magento

Platform-specific store API credentials. The shape is discriminated by the platform recorded on the connector. Required for live checkout and write-back; may be omitted for profile-only deployments.

Show properties

One of:

store_credentials_woocommerce

store_base_urlstring<uri>required

Public storefront URL (e.g. https://mystore.com).

consumer_keystringrequired

WooCommerce REST API v3 OAuth consumer key.

consumer_secretstringrequired

WooCommerce REST API v3 OAuth consumer secret.

webhook_secretstringrequired

Webhook signature verification key.

store_currencystring

ISO 4217 currency code (default USD).

matches ^[A-Z]{3}$

store_credentials_magento

base_urlstring<uri>required

Magento instance base URL (e.g. https://mystore.magentosite.cloud).

admin_userstringrequired

Magento admin API username.

admin_passwordstringrequired

Magento admin API password.

store_codestringrequired

Magento store code (e.g. default).

store_currencystringrequired

ISO 4217 currency code the store operates in.

matches ^[A-Z]{3}$

webhook_secretstringrequired

Webhook signature verification secret.

Responses

200

Pairing completed; connector is healthy.

connector_idstring

store_idstring

statusstring

Allowed:healthy

400

Request body failed validation.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

detailsobject | null

401

Missing or invalid credentials.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

detailsobject | null

422

Invalid or expired pairing code, or credential validation failed.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

detailsobject | null

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

API keyRemember on this deviceInclude my values in samples

Bodyapplication/json

connector_idstring*The connector ID returned by POST /connectors at begin-pairing.pairing_codestring*One-time pairing code issued to the console operator.store_credentialsstringPlatform-specific store API credentials. The shape is discriminated by the platform recorded on the connector. Required for live checkout and write-back; may be omitted for profile-only deployments.

Request

curl -X POST "https://api.sarvex.example.com/v1/connectors/pairing/complete" \
  -H "X-Sarvex-Signature: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connector_id": "string",
  "pairing_code": "string",
  "store_credentials": {
    "store_base_url": "http://example.com",
    "consumer_key": "string",
    "consumer_secret": "string",
    "webhook_secret": "string",
    "store_currency": "string"
  }
}'

const response = await fetch("https://api.sarvex.example.com/v1/connectors/pairing/complete", {
  method: "POST",
  headers: {
    "X-Sarvex-Signature": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: "{\n  \"connector_id\": \"string\",\n  \"pairing_code\": \"string\",\n  \"store_credentials\": {\n    \"store_base_url\": \"http://example.com\",\n    \"consumer_key\": \"string\",\n    \"consumer_secret\": \"string\",\n    \"webhook_secret\": \"string\",\n    \"store_currency\": \"string\"\n  }\n}"
});

import requests

response = requests.post(
    "https://api.sarvex.example.com/v1/connectors/pairing/complete",
    headers={
        "X-Sarvex-Signature": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    data="{\n  \"connector_id\": \"string\",\n  \"pairing_code\": \"string\",\n  \"store_credentials\": {\n    \"store_base_url\": \"http://example.com\",\n    \"consumer_key\": \"string\",\n    \"consumer_secret\": \"string\",\n    \"webhook_secret\": \"string\",\n    \"store_currency\": \"string\"\n  }\n}",
)

Response

{
  "connector_id": "string",
  "store_id": "string",
  "status": "healthy"
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}