Merchant settings

Read and update a merchant's own settings and profile from the Dashboard, and manage the people who have access to it.

These endpoints back the Dashboard's settings screen for a single merchant: its profile and configuration, plus the team members who can sign in and act on its behalf.

Membership here is what the x-merchant-id header checks on every other Dashboard call — add or remove a member and you change who can manage this merchant's catalog, connectors, and orders.

These endpoints power the Tokeflow Dashboard UI. They are session-authenticated (JWT bearer) — the token comes from signing in to the Dashboard, not from an sk_/pk_ API key. Requests also carry the x-merchant-id header identifying the merchant in context, and the signed-in user must be a member with access to it.

The merchant object

Returned by the list and retrieve endpoints on this page.

Field	Type	Description
`id`	string	—
`organization_id`	string	—
`organization`	object	—
`name`	string	—
`slug`	string	—
`external_reference`	string \| null	—
`business_registration_number`	string \| null	—
`mcc`	string \| null	—
`phone_number`	string \| null	—
`address_line1`	string \| null	—
`address_line2`	string \| null	—
`city`	string \| null	—
`state`	string \| null	—
`postal_code`	string \| null	—
`country_code`	string \| null	—
`website`	string \| null	—
`status`	string	—
`created_at`	string	(ISO 8601 UTC).
`updated_at`	string	(ISO 8601 UTC).
`webhook_configs`	array	—
`memberships`	array	—
`customers`	array	—

Endpoints

GET`/api/v1/merchant/profile`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Get merchant profile.

Example request

curl https://api.tokeflow.com/api/v1/merchant/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Example response — 200

{
  "id": "obj_1a2b3c4d",
  "organization_id": "org_4b21e7c3",
  "organization": {
    "id": "obj_1a2b3c4d",
    "name": "Acme Store",
    "slug": "acme-store",
    "status": "active",
    "business_registration_number": "string",
    "mcc": "string",
    "country_code": "BR",
    "external_reference": "string",
    "phone_number": "+5511987654321",
    "address_line1": "string",
    "address_line2": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "created_at": "2026-01-15T12:30:00.000Z",
    "updated_at": "2026-01-15T12:30:00.000Z",
    "memberships": [
      {
        "id": "obj_1a2b3c4d",
        "organization_id": "org_4b21e7c3",
        "user_id": "string",
        "role": "owner",
        "created_at": "2026-01-15T12:30:00.000Z",
        "updated_at": "2026-01-15T12:30:00.000Z",
        "organization": {},
        "user": {
          "id": "obj_1a2b3c4d",
          "email": "jane@example.com",
          "name": "Acme Store",
          "auth_provider": "string",
          "auth_subject_id": "string",
          "password_hash": "string",
          "last_login_at": "2026-01-15T12:30:00.000Z",
          "must_change_password": true,
          "refresh_token_hash": "string",
          "failed_login_attempts": 1,
          "locked_until": "2026-01-15T12:30:00.000Z",
          "created_at": "2026-01-15T12:30:00.000Z",
          "updated_at": "2026-01-15T12:30:00.000Z",
          "memberships": [
            {}
          ]
        }
      }
    ],
    "merchants": [
      {}
    ],
    "branding": {
      "id": "obj_1a2b3c4d",
      "organization_id": "org_4b21e7c3",
      "organization": {},
      "custom_url": "https://example.com/webhooks/tokeflow",
      "site_title": "string",
      "favicon": "string",
      "logo_light_mode": "string",
      "logo_dark_mode": "string",
      "collapsible_logo_light_mode": "string",
      "collapsible_logo_dark_mode": "string",
      "theme_primary_color": "#1c1c1c",
      "theme_secondary_color": "#1c1c1c",
      "show_name_with_logo": true,
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z"
    }
  },
  "name": "Acme Store",
  "slug": "acme-store",
  "external_reference": "string",
  "business_registration_number": "string",
  "mcc": "string",
  "phone_number": "+5511987654321",
  "address_line1": "string",
  "address_line2": "string",
  "city": "string",
  "state": "string",
  "postal_code": "string",
  "country_code": "BR",
  "website": "string",
  "status": "active",
  "created_at": "2026-01-15T12:30:00.000Z",
  "updated_at": "2026-01-15T12:30:00.000Z",
  "webhook_configs": [
    {
      "id": "obj_1a2b3c4d",
      "merchant_id": "mrc_8a3f12d9",
      "merchant": {},
      "url": "https://example.com/webhooks/tokeflow",
      "secret": {},
      "description": "Human-readable description",
      "event_filter": [
        "transaction.created"
      ],
      "is_active": true,
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z",
      "deleted_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "memberships": [
    {
      "id": "obj_1a2b3c4d",
      "merchant_id": "mrc_8a3f12d9",
      "user_id": "string",
      "role": "owner",
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z",
      "merchant": {},
      "user": {
        "id": "obj_1a2b3c4d",
        "organization_id": "org_4b21e7c3",
        "email": "jane@example.com",
        "name": "Acme Store",
        "auth_provider": "string",
        "auth_subject_id": "string",
        "password_hash": "string",
        "invitation_token": "string",
        "invitation_expires_at": "2026-01-15T12:30:00.000Z",
        "is_active": true,
        "last_login_at": "2026-01-15T12:30:00.000Z",
        "must_change_password": true,
        "refresh_token_hash": "string",
        "failed_login_attempts": 1,
        "locked_until": "2026-01-15T12:30:00.000Z",
        "created_at": "2026-01-15T12:30:00.000Z",
        "updated_at": "2026-01-15T12:30:00.000Z",
        "organization": {
          "id": "obj_1a2b3c4d",
          "name": "Acme Store",
          "slug": "acme-store",
          "status": "active",
          "business_registration_number": "string",
          "mcc": "string",
          "country_code": "BR",
          "external_reference": "string",
          "phone_number": "+5511987654321",
          "address_line1": "string",
          "address_line2": "string",
          "city": "string",
          "state": "string",
          "postal_code": "string",
          "created_at": "2026-01-15T12:30:00.000Z",
          "updated_at": "2026-01-15T12:30:00.000Z",
          "memberships": [
            {}
          ],
          "merchants": [
            {}
          ],
          "branding": {}
        },
        "memberships": [
          {}
        ]
      }
    }
  ],
  "customers": [
    {
      "id": "obj_1a2b3c4d",
      "merchant_id": "mrc_8a3f12d9",
      "merchant": {},
      "email": "jane@example.com",
      "name": "Acme Store",
      "phone": "+5511987654321",
      "document_type": "12345678909",
      "document_number": "12345678909",
      "metadata": {},
      "billing_address": {},
      "created_at": "2026-01-15T12:30:00.000Z",
      "updated_at": "2026-01-15T12:30:00.000Z",
      "deleted_at": "2026-01-15T12:30:00.000Z"
    }
  ]
}

PATCH`/api/v1/merchant/profile`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Once the merchant is enrolled for network tokens, the fields sent at enrollment (name, website, mcc and the address) are fixed at the card networks and can no longer be changed — attempting to returns 409.

Request fields

Field	Type	Required	Description
`name`	string	No	—
`business_registration_number`	string	No	—
`mcc`	string	No	—
`country_code`	string	No	—
`phone_number`	string	No	—
`address_line1`	string	No	—
`address_line2`	string	No	—
`city`	string	No	—
`state`	string	No	ISO 3166-2 subdivision code without the country prefix ("SP", not "BR-SP"). Checked against `country_code` when both are sent.
`postal_code`	string	No	—
`website`	string	No	—

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/merchant/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John's Store",
    "business_registration_number": "12345678000199",
    "mcc": "5732",
    "country_code": "BR",
    "phone_number": "+55 11 99999-0000",
    "address_line1": "Av Paulista, 1000",
    "address_line2": "Apt 10",
    "city": "S\u00e3o Paulo",
    "state": "SP",
    "postal_code": "01310-100",
    "website": "https://johnsstore.com.br"
  }'

Example response — 200

{}

POST`/api/v1/merchant/team/invitations`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Provisions a merchant_users row scoped to this organization (or reuses an existing one) and attaches a membership for this merchant. Sends an invitation email so the recipient can set a password.

Request fields

Field	Type	Required	Description
`email`	string	Yes	—
`role`	string	Yes	One of `owner`, `admin`, `viewer`.

Example request

curl -X POST https://api.tokeflow.com/api/v1/merchant/team/invitations \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "role": "owner"
  }'

Example response — 201

{}

GET`/api/v1/merchant/team/members`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

List team members.

Query parameters

Field	Type	Required	Description
`page`	number	No	Page number (1-indexed). Default `1`, min `1`.
`limit`	number	No	Number of items per page. Default `20`, min `1`, max `100`.

Example request

curl -G https://api.tokeflow.com/api/v1/merchant/team/members \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

DELETE`/api/v1/merchant/team/members/:id`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Remove team member.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/team/members/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

PATCH`/api/v1/merchant/team/members/:id`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Update team member role.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Request fields

Field	Type	Required	Description
`role`	string	Yes	One of `owner`, `admin`, `viewer`.

Example request

curl -X PATCH https://api.tokeflow.com/api/v1/merchant/team/members/obj_1a2b3c4d \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "owner"
  }'

POST`/api/v1/merchant/team/members/:id/resend`

Merchant

Auth: Dashboard session (JWT bearer). Merchant membership required.

Resend a pending team invitation.

Path parameters

Field	Type	Required	Description
`id`	string	Yes	—

Example request

curl -X POST https://api.tokeflow.com/api/v1/merchant/team/members/obj_1a2b3c4d/resend \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Example response — 200

{
  "membership_id": "mem_7b2f9c14",
  "user_id": "string",
  "email": "jane@example.com",
  "name": "Acme Store",
  "role": "owner",
  "joined_at": "2026-01-15T12:30:00.000Z",
  "status": "active",
  "invitation_expires_at": "2026-01-15T12:30:00.000Z"
}

Errors

Errors use the standard envelope. The most common cases here:

HTTP	Meaning
`400`	Invalid parameters or a state that does not allow this operation.
`401`	Missing, expired, or invalid Dashboard session token.
`403`	Authenticated, but the signed-in user lacks access to this entity.
`404`	The record does not exist or is not visible to this entity.

Merchant settings

The merchant object

Endpoints

GET/api/v1/merchant/profile

PATCH/api/v1/merchant/profile

POST/api/v1/merchant/team/invitations

GET/api/v1/merchant/team/members

DELETE/api/v1/merchant/team/members/:id

PATCH/api/v1/merchant/team/members/:id

POST/api/v1/merchant/team/members/:id/resend

Errors

Related

On this page

GET`/api/v1/merchant/profile`

PATCH`/api/v1/merchant/profile`

POST`/api/v1/merchant/team/invitations`

GET`/api/v1/merchant/team/members`

DELETE`/api/v1/merchant/team/members/:id`

PATCH`/api/v1/merchant/team/members/:id`

POST`/api/v1/merchant/team/members/:id/resend`