Set a store's payment-handler configuration

Enable handlers and supply their processor/gateway parameters. Secret material is write-only (accepted here, never returned). A store cannot pass validation with checkout enabled but no configured handler.

PUT/stores/{store_id}/payment-config

Authorization

AuthorizationBearer token (JWT) · headerrequired

JWT issued by the external IdP via the OAuth 2.0 authorization-code flow (Kinde in production; a simulator in test). The client obtains it and sends it as a Bearer token on every authenticated call. Sarvex's services verify it — issuer, audience, signature (IdP JWKS), expiry — and read identity and tenant from its claims. Sarvex does not issue or revoke these tokens. merchant_id/store_id are read from the verified claims (and the merchant→store mapping), never from the URL. The operator scope is required for /operator/*. Operators acting on a specific merchant pass the X-Operate-As header, which is recorded in the audit log.

Path parameters

store_idstringrequired

A store the caller's merchant owns. Authorized server-side against the principal; not a free-form tenant selector.

Request body

requiredapplication/json

handlersobject[]

Show properties

Array of object

handler_idstringrequired

enabledbooleanrequired

parametersobject

Processor/gateway parameters; secret fields are write-only and never echoed back.

Responses

200

Updated configuration.

store_idstring

handlersobject[]

Show properties

Array of object

handler_idstring

namestring

enabledboolean

configuredboolean

All required parameters/secrets present.

config_statusstring

Allowed:not_startedincompleteready

422

Request body failed validation.

errorobjectrequired

Show properties

codestringrequired

messagestringrequired

detailsobject | null

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (JWT)Remember on this deviceInclude my values in samples

Parameters

store_idpath*A store the caller's merchant owns. Authorized server-side against the principal; not a free-form tenant selector.

Bodyapplication/json

Request body

Request

curl -X PUT "https://api.sarvex.example.com/v1/stores/string/payment-config" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "handlers": [
    {
      "handler_id": "google_pay",
      "enabled": true,
      "parameters": {}
    }
  ]
}'

const response = await fetch("https://api.sarvex.example.com/v1/stores/string/payment-config", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"handlers\": [\n    {\n      \"handler_id\": \"google_pay\",\n      \"enabled\": true,\n      \"parameters\": {}\n    }\n  ]\n}"
});

import requests

response = requests.put(
    "https://api.sarvex.example.com/v1/stores/string/payment-config",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"handlers\": [\n    {\n      \"handler_id\": \"google_pay\",\n      \"enabled\": true,\n      \"parameters\": {}\n    }\n  ]\n}",
)

Response

{
  "store_id": "string",
  "handlers": [
    {
      "handler_id": "google_pay",
      "name": "com.google.pay",
      "enabled": true,
      "configured": true,
      "config_status": "not_started"
    }
  ]
}

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