Skip to main content
POST
/
merchant
/
api
/
v1
/
counters
Create counter (POS terminal)
curl --request POST \
  --url http://api-sandbox.fexpayments.com/merchant/api/v1/counters \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Counter 1",
  "location": "Floor 2, Register 3",
  "webhook_url": "https://pos.example.com/webhooks/payments"
}
'
{
  "success": true,
  "counter": {
    "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
    "merchant_id": "74815c83-e47b-4dc5-aefe-abe4484dd280",
    "name": "Counter 1",
    "status": "active",
    "location": "Floor 2, Register 3",
    "keycloak_client_id": "counter-c1d2e3f4-a5b6-7890-abcd-ef1234567890",
    "webhook_url": "https://pos.example.com/webhooks/payments",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "client_id": "counter-c1d2e3f4-a5b6-7890-abcd-ef1234567890",
  "client_secret": "abc123secretvalue",
  "webhook_secret": "a3f8c2e1d4b7a9f0e2c5b8d1a4f7c0e3d6b9a2f5c8e1d4b7a0f3c6e9d2b5a8f1",
  "note": "Store client_secret and webhook_secret securely — they are only shown once."
}

Authorizations

​
Authorization
string
header
required

Keycloak JWT. Roles: admin (platform admin — can register merchants, act on behalf of any merchant), merchant (dashboard user — scoped to their own merchant_id via user attribute mapper), POS terminals use client credentials flow with merchant_id injected via protocol mapper.

Body

application/json
​
name
string
required
Example:

"Counter 1"

​
location
string
Example:

"Floor 2, Register 3"

​
webhook_url
string<uri>
Example:

"https://pos.example.com/webhooks/payments"

Response

Counter created. Save client_secret and webhook_secret immediately — they cannot be retrieved again.

​
success
boolean
Example:

true

​
counter
object

A POS terminal belonging to a merchant

​
client_id
string

Keycloak client ID for POS client_credentials flow

Example:

"counter-c1d2e3f4-a5b6-7890-abcd-ef1234567890"

​
client_secret
string

Keycloak client secret — shown only on creation, store securely

Example:

"abc123secretvalue"

​
webhook_secret
string

HMAC-SHA256 secret for verifying webhook signatures — shown only on creation, store securely

Example:

"a3f8c2e1d4b7a9f0e2c5b8d1a4f7c0e3d6b9a2f5c8e1d4b7a0f3c6e9d2b5a8f1"

​
note
string
Example:

"Store client_secret and webhook_secret securely — they are only shown once."