Create Merchant User

POST 
/v1/acquirer/merchants/:merchant_id/users

Create a dashboard user for a merchant and send them an invitation email. The email must be unique within the merchant.

Required permission: merchant_users_create.

Request

Path Parameters

merchant_id stringrequired

Acquirer-assigned merchant identifier (the merchant_id field of the merchant, not its internal UUID).

application/json

Body

required

name stringrequired

Full display name.

email emailrequired

Login email. Must be unique within the merchant.

description string

Optional free-text note (role, team, etc.).

permissions string[]

Permission strings to assign. See the permissions endpoint for the available values.

Responses

201

The created user. An invitation email is queued.

application/json

Schema

Schema

id uuidrequired

A 36-character UUIDv7 identifier.

active booleanrequired

false while the user is disabled.

merchant_id uuidrequired

A 36-character UUIDv7 identifier.

email emailrequired
name stringrequired
description stringnullable
permissions string[]required
two_factor_enabled boolean
created_by_user_id uuid

A 36-character UUIDv7 identifier.

disabled_by_user_id uuid

A 36-character UUIDv7 identifier.

disabled_at date-time

ISO 8601 UTC timestamp with time zone designator.

invited_by_id uuid

A 36-character UUIDv7 identifier.

invited_by_type stringnullable

Possible values: [AcquirerUser, MerchantUser, StaffUser, AcquirerApiKey, null]

invitation_sent_at date-time

ISO 8601 UTC timestamp with time zone designator.

invitation_accepted_at date-time

ISO 8601 UTC timestamp with time zone designator.

password_expires_at date-time

ISO 8601 UTC timestamp with time zone designator.

must_reset_password_at date-time

ISO 8601 UTC timestamp with time zone designator.

password_reset_at date-time

ISO 8601 UTC timestamp with time zone designator.

created_at date-timerequired

ISO 8601 UTC timestamp with time zone designator.

updated_at date-timerequired

ISO 8601 UTC timestamp with time zone designator.

Example (from schema)

{
  "id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
  "active": true,
  "merchant_id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
  "email": "[email protected]",
  "name": "string",
  "description": "string",
  "permissions": [
    "orders_read",
    "agreements_read"
  ],
  "two_factor_enabled": true,
  "created_by_user_id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
  "disabled_by_user_id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
  "disabled_at": "2025-01-15T14:30:00Z",
  "invited_by_id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
  "invited_by_type": "AcquirerUser",
  "invitation_sent_at": "2025-01-15T14:30:00Z",
  "invitation_accepted_at": "2025-01-15T14:30:00Z",
  "password_expires_at": "2025-01-15T14:30:00Z",
  "must_reset_password_at": "2025-01-15T14:30:00Z",
  "password_reset_at": "2025-01-15T14:30:00Z",
  "created_at": "2025-01-15T14:30:00Z",
  "updated_at": "2025-01-15T14:30:00Z"
}

401

Authentication failed.

application/json

Schema

Schema

message stringrequired

Example (from schema)

{
  "message": "Missing authentication information"
}

403

The API key lacks the required permission.

application/json

Schema

Schema

message stringrequired

Example (from schema)

{
  "message": "Unauthorized"
}

404

The referenced resource does not exist or belongs to another acquirer.

application/json

Schema

Schema

message stringrequired

Example (from schema)

{
  "message": "The Order you are looking for was not found."
}

422

Validation error.

application/json

Schema

Schema

message stringrequired

errors

object

required

property name*

string[]

Array [

string

]

Example (from schema)

{
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "This field is missing."
    ]
  }
}

Loading...