Creating and Managing Users via API

This guide will display API fields (required and optional), testing endpoints, and requirements for each field using the Payrix API. Successfully creating a user via the API provides use cases for a white-labeled, seamless integration of new users to your platform.

Creating a User via API

In order to have a Login ID to use via the API when creating users, you’ll need to start by creating one user first within the Portal.

Visit the Portal Dashboard
Click Users (under the Management Tab)
Click the Add User button and set the Role, Username, Password, Full Name, and Email Address.
Click on the newly created user from the User's menu
You’ll find the Login ID under “Parent Login ID” within the User sub-menu.
Use this to query the Login ID using the /logins endpoint.

Afer completing this process the first time you can then use this as a template for creating additional users with the desired roles and permissions using the API.

Required fields to create a User via API

Required Field	Field (Code)	Description
Roles	`logins.roles`	The user’s associated roles, stored as a bit field.
Username	`logins.username`	The username associated with this Login. This field is stored as a text string, all lowercase, and must be between 0 and 50 characters long
Password	`logins.password`	The password associated with this Login. This field is stored as a text string and must be between 0 and 100 characters long. Password Requirements: Your password must be: at least 8 characters long Your password must contain at least 3: uppercase letters lowercase letters numbers or symbols
First Name	`logins.first`	The first name associated with this Login.
Last Name	`logins.last`	The last name associated with this Login.
Email Address	`logins.email`	The email address associated with this Login.
Portal Access	`logins.portalAccess`	Whether or not this user should have access to portal functionality.
Entities	`logins.entities`	Stores the entity portion of a single facilitator, vendor or merchant. Common business-related details for each type of entity are stored here (like name and address) as well as management details (like which `login` the entity belongs to).

Although the API documentation lists several fields as “required”, a user can still be created via API with roles, username, password, first, last, email, portal access, entities. Frozen will default to “Not Frozen”, and inactive will default to “active”.

Optional fields to create a User via API

Optional Field	Field (Code)	Description
Middle Name	`logins.middle`	The middle name associated with this Login.
Login	`logins.login`	The identifier of the Login.
Division	`logins.division`	The division that this Login belongs to.
Parent Division	`logins.parentDivision`	The parent division that this Login belongs to. Children of this Login will inherit its parent division.
Phone Number	`logins.phone`	The phone number associated with this Login. This field is stored as a text string and must be between 10 and 15 characters long.
Fax Number	`logins.fax`	The fax number associated with this Login. This field is stored as a text string and must be between 10 and 15 characters long.
Inactive	`logins.inactive`	Whether this resource is marked as inactive.
Frozen	`logins.frozen`	Whether this resource is marked as frozen.
Confirmed	`logins.confirmed`	Whether the email associated with this Login was confirmed. This field is stored as an integer and will be set to '1' when the email is confirmed.
Allowed Resources	`login.allowedresources`	the resources and actions whitelisted for this user, stored as a string-JSON action keys: `create`, `update`, `read`, `delete` and `totals` list of resources, e.g.: `logins`, `apikeys`, `sessions` Not all action keys need to be defined, whichever are omitted will not affect the user’s access Example structure: `{“create”: ["logins","apikeys","sessions"],"update":["apikeys","sessions"]}` The values set in this field will whitelist the resources for the actions defined to the exclusion of all others
Restricted Resources	`logins.restrictedresources`	the resources and actions blacklisted for this user, stored as a string-JSON: Same structure as `allowedresources`, see above The values set in this field will blacklist the resources for the actions defined, all other actions and resources will not be affected
Address 1	`logins.address1`	The first line of the address associated with this Login. This field is stored as a text string and must be between 1 and 500 characters long.
Address 2	`logins.address2`	The second line of the address associated with this Login. This field is stored as a text string and must be between 1 and 500 characters long.
City	`logins.city`	The name of the city in the address associated with this Login. This field is stored as a text string and must be between 1 and 500 characters long.
State	`logins.state`	The state associated with this Login. If in the U.S. this is specified as the 2 character postal abbreviation for the state, if outside of the U.S. the full state name. This field is stored as a text string and must be between 2 and 100 characters long.
Zip	`logins.zip`	The ZIP code in the address associated with this Login. This field is stored as a text string and must be between 1 and 20 characters long.
Country	`logins.country`	The country associated with this Customer. Valid values for this field is the 3-letter ISO code for the country.

Additional Information

Required Fields

Roles

Roles can only be created in context to your permissions

EXPAND

Field Value	Role Value	Description
`64`	VENDOR	Handle merchants and fees
`128`	MERCHANT	Merchant role
`256`	CREATEMERCHANT	Merchant creation role
`512`	PASSWORD	Change passwords of users
`1024`	LOG	Read logs
`2048`	UNFREEZE	Unfreeze records
`4096`	MODIFYROLES	Modify login roles
`8192`	PAYMENTIDS	See hidden payment IDs
`16384`	PARAM	Add allow boarding parameter on merchant
`32768`	PARTITION	Create/modify partitions
`65536`	MCC	Allow MCC manipulation
`131072`	TXNREPORT	Allow viewing transaction reports
`262144`	DISBURSEMENT	Update disbursements
`524288`	FUNDRESERVE	Fund reserve handling
`1048576`	PLATFORMREFS	Manage platform refs
`2097152`	VERIFICATION	Handle verifications
`4194304`	FEE	Handling of fees
`8388608`	CHALLENGE	View challenges
`16777216`	RESERVETXN	Allow reserving/releasing transactions
`33554432`	SETBOARDED	Allow resetting boarded status
`67108864`	ASSESSMENT	Handle ASSESSMENT fees/assessments
`134217728`	ADJUSTMENT	Adjustments creation
`268435456`	MERCHANTFLOW	Access to MerchantChecks model
`536870912`	FACILITATORRECORD	Access to a facilitator model
`1073741824`	CONFIRMEMAIL	Confirm email of login
`2147483648`	TINSTATUS	Allow setting Tinstatus
`4294967296`	ENTITYROUTE	Manages EntityRoutes
`8589934592`	FILES	Allow reading files
`17179869184`	UNMASKPRIVATE	Allow reading full unmasked private details
`34359738368`	UNMASKBANK	Allow reading full unmasked bank details,
`68719476736`	THREADCREATE	Create MessageThreads
`137438953472`	BINQUERY	Query bin data
`274877906944`	BINCHANGE	Modify bin data
`549755813888`	SETINTERCHANGE	Set transaction interchange
`1099511627776`	ASSESSMENTVIEW	View assessments
`2199023255552`	SCHEMA	Allow access to schema versions
`4398046511104`	DIVISIONACCESS	Access to all records in the division
`8796093022208`	DIVISION	Division Role
`17592186044416`	ENTITYRETURN	Create, update and delete EntityReturns
`35184372088832`	VENDORCREATE	Create Vendor
`70368744177664`	WATCHLIST	Manage watchlists
`140737488355328`	PROFITSHARE	Profit Shares

Password

A password must have the following:

Your password must be at least 8 characters long
Your password must contain at least 3 of: uppercase letter, lowercase letter, number or symbol

Code Example:

EXPAND

CODE

        "errors": [
            {
                "field": "password",
                "code": 15,
                "severity": 2,
                "msg": "Your password must be at least 8 characters long",
                "errorCode": "password_length_error"
            },
            {
                "field": "password",
                "code": 15,
                "severity": 2,
                "msg": "Your password must contain at least 3 of: uppercase letter, lowercase letter, number or symbol",
                "errorCode": "password_complexity_error"
            }
        ]

Portal Access

0	No access to the portal
1	Has access to the portal

Entities

type - The legal business type.

The allowed values are:

0 - Sole Proprietor
1 - Corporation
2 - Limited Liability Company
3 - Partnership
4 - Association
5 - Non-Profit Organization
6 - Governmental Organization

Code Example:

EXPAND

CODE

"entities": [
        {
            "type": 6,
            "name": "Walsh and Sons LLC",
            "address1": "1234 Rivver Lane",
            "address2": null,
            "city": "Frisco",
            "state": "TX",
            "zip": "75034",
            "country": "USA",
            "phone": "995685662566",
            "fax": null,
            "email": "Entity.Email@gmail.com",
            "ein": "123456789",
            "website": "http://payrix.com",
            "tcVersion": "1.0",
            "currency": "USD",
            "accounts": [
                {
                    "primary": "1",
                    "currency": "USD",
                    "account": {
                        "method": "8",
                        "number": "90720860",
                        "routing": "021000021"
                    }
                }
            ],
            "merchant": 
                {
                    "dba": "",
                    "new": "1",
                    "mcc": "1799",
                    "status": "1",
                    "members": [
                        {
                            "title": "CEO",
                            "first": "Chad",
                            "middle": null,
                            "last": "Foster",
                            "ssn": 111111111,
                            "dob": "19850225",
                            "dl": "9331726679",
                            "dlstate": "MD",
                            "ownership": 0,
                            "email": "Jerrod_Glover@hotmail.com",
                            "fax": null,
                            "phone": "5106406131",
                            "primary": "1",
                            "address1": "83 Dan Ways",
                            "address2": null,
                            "city": "East Bettye",
                            "state": "MD",
                            "zip": "60064",
                            "country": "USA"
                        }
                    ]
                }
        }
    ]

Optional fields to create a User via API

Inactive

Available Values:

0	Active
1	Inactive

Frozen

Available Values:

0	Not frozen
1	Frozen

Confirmed

Available Values:

Boolean of 0 or 1

Allowed Resources

Naming conventions for Allowed Resources and Restricted Resources are case sensitive and must be lowercase.

allowedresources, restrictedresources

Restricted Resources

Naming conventions for Allowed Resources and Restricted Resources are case sensitive and must be lowercase.

allowedresources, restrictedresources

State

Available Values:

AL	Alabama
AK	Alaska
AZ	Arizona
AR	Arkansas
CA	California
CO	Colorado
CT	Connecticut
DE	Delaware
DC	District of Columbia
FL	Florida
GA	Georgia
HI	Hawaii
ID	Idaho
IL	Illinois
IN	Indiana
IA	Iowa
KS	Kansas
KY	Kentucky
LA	Louisiana
ME	Maine
MD	Maryland
MA	Massachusetts
MI	Michigan
MN	Minnesota
MS	Mississippi
MO	Missouri
MT	Montana
NE	Nebraska
NV	Nevada
NH	New Hampshire
NJ	New Jersey
NM	New Mexico
NY	New York
NC	North Carolina
ND	North Dakota
OH	Ohio
OK	Oklahoma
OR	Oregon
PA	Pennsylvania
RI	Rhode Island
SC	South Carolina
SD	South Dakota
TN	Tennessee
TX	Texas
UT	Utah
VT	Vermont
VA	Virginia
WA	Washington
WV	West Virginia
WI	Wisconsin
WY	Wyoming
AA	U.S. Armed Forces - Americas
AE	U.S. Armed Forces - Europe
AP	U.S. Armed Forces - Pacific
AS	American Samoa
FM	Federated States of Micronesia
GU	Guam
MH	Marshall Islands
MP	Northern Mariana Islands
PR	Puerto Rico
PW	Palau
UM	U.S. Minor Outlying Islands
VI	U.S. Virgin Islands

Country

Available Values:

ABW	Aruba
AFG	Afghanistan
AGO	Angola
AIA	Anguilla
ALA	Aland Islands
ALB	Albania
AND	Andorra
ARE	United Arab Emirates
ARG	Argentina
ARM	Armenia
ASM	American Samoa
ATA	Antarctica
ATF	French Southern Territories
ATG	Antigua and Barbuda
AUS	Australia
AUT	Austria
AZE	Azerbaijan
BDI	Burundi
BEL	Belgium
BEN	Benin
BES	Bonaire, Sint Eustatius and Saba
BFA	Burkina Faso
BGD	Bangladesh
BGR	Bulgaria
BHR	Bahrain
BHS	Bahamas
BIH	Bosnia and Herzegovina
BLM	Saint Barthélemy
BLR	Belarus
BLZ	Belize
BMU	Bermuda
BOL	Bolivia, Plurinational State of
BRA	Brazil
BRB	Barbados
BRN	Brunei Darussalam
BTN	Bhutan
BVT	Bouvet Island
BWA	Botswana
CAF	Central African Republic
CAN	Canada
CCK	Cocos (Keeling) Islands
CHE	Switzerland
CHL	Chile
CHN	China
CIV	Côte d’Ivoire
CMR	Cameroon
COD	Congo, the Democratic Republic of the
COG	Congo
COK	Cook Islands
COL	Colombia
COM	Comoros
CPV	Cape Verde
CRI	Costa Rica
CUB	Cuba
CUW	Curaçao
CXR	Christmas Island
CYM	Cayman Islands
CYP	Cyprus
CZE	Czech Republic
DEU	Germany
DJI	Djibouti
DMA	Dominica
DNK	Denmark
DOM	Dominican Republic
DZA	Algeria
ECU	Ecuador
EGY	Egypt
ERI	Eritrea
ESH	Western Sahara
ESP	Spain
EST	Estonia
ETH	Ethiopia
FIN	Finland
FJI	Fiji
FLK	Falkland Islands (Malvinas)
FRA	France
FRO	Faroe Islands
FSM	Micronesia, Federated States of
GAB	Gabon
GBR	United Kingdom
GEO	Georgia
GGY	Guernsey
GHA	Ghana
GIB	Gibraltar
GIN	Guinea
GLP	Guadeloupe
GMB	Gambia
GNB	Guinea-Bissau
GNQ	Equatorial Guinea
GRC	Greece
GRD	Grenada
GRL	Greenland
GTM	Guatemala
GUF	French Guiana
GUM	Guam
GUY	Guyana
HKG	Hong Kong
HMD	Heard Island and McDonald Islands
HND	Honduras
HRV	Croatia
HTI	Haiti
HUN	Hungary
IDN	Indonesia
IMN	Isle of Man
IND	India
IOT	British Indian Ocean Territory
IRL	Ireland
IRN	Iran, Islamic Republic of
IRQ	Iraq
ISL	Iceland
ISR	Israel
ITA	Italy
JAM	Jamaica
JEY	Jersey
JOR	Jordan
JPN	Japan
KAZ	Kazakhstan
KEN	Kenya
KGZ	Kyrgyzstan
KHM	Cambodia
KIR	Kiribati
KNA	Saint Kitts and Nevis
KOR	Korea, Republic of
KWT	Kuwait
LAO	Lao People's Democratic Republic
LBN	Lebanon
LBR	Liberia
LBY	Libya
LCA	Saint Lucia
LIE	Liechtenstein
LKA	Sri Lanka
LSO	Lesotho
LTU	Lithuania
LUX	Luxembourg
LVA	Latvia
MAC	Macao
MAF	Saint Martin (French part)
MAR	Morocco
MCO	Monaco
MDA	Moldova, Republic of
MDG	Madagascar
MDV	Maldives
MEX	Mexico
MHL	Marshall Islands
MKD	Macedonia, the former Yugoslav Republic of
MLI	Mali
MLT	Malta
MMR	Myanmar
MNE	Montenegro
MNG	Mongolia
MNP	Northern Mariana Islands
MOZ	Mozambique
MRT	Mauritania
MSR	Montserrat
MTQ	Martinique
MUS	Mauritius
MWI	Malawi
MYS	Malaysia
MYT	Mayotte
NAM	Namibia
NCL	New Caledonia
NER	Niger
NFK	Norfolk Island
NGA	Nigeria
NIC	Nicaragua
NIU	Niue
NLD	Netherlands
NOR	Norway
NPL	Nepal
NRU	Nauru
NZL	New Zealand
OMN	Oman
PAK	Pakistan
PAN	Panama
PCN	Pitcairn
PER	Peru
PHL	Philippines
PLW	Palau
PNG	Papua New Guinea
POL	Poland
PRI	Puerto Rico
PRK	Korea, Democratic People's Republic of
PRT	Portugal
PRY	Paraguay
PSE	Palestine, State of
PYF	French Polynesia
QAT	Qatar
REU	Réunion
ROU	Romania
RUS	Russian Federation
RWA	Rwanda
SAU	Saudi Arabia
SDN	Sudan
SEN	Senegal
SGP	Singapore
SGS	South Georgia and the South Sandwich Islands
SHN	Saint Helena, Ascension and Tristan da Cunha
SJM	Svalbard and Jan Mayen
SLB	Solomon Islands
SLE	Sierra Leone
SLV	El Salvador
SMR	San Marino
SOM	Somalia
SPM	Saint Pierre and Miquelon
SRB	Serbia
SSD	South Sudan
STP	Sao Tome and Principe
SUR	Suriname
SVK	Slovakia
SVN	Slovenia
SWE	Sweden
SWZ	Swaziland
SXM	Sint Maarten (Dutch part)
SYC	Seychelles
SYR	Syrian Arab Republic
TCA	Turks and Caicos Islands
TCD	Chad
TGO	Togo
THA	Thailand
TJK	Tajikistan
TKL	Tokelau
TKM	Turkmenistan
TLS	Timor-Leste
TON	Tonga
TTO	Trinidad and Tobago
TUN	Tunisia
TUR	Turkey
TUV	Tuvalu
TWN	Taiwan, Province of China
TZA	Tanzania, United Republic of
UGA	Uganda
UKR	Ukraine
UMI	United States Minor Outlying Islands
URY	Uruguay
USA	United States
UZB	Uzbekistan
VAT	Holy See (Vatican City State)
VCT	Saint Vincent and the Grenadines
VEN	Venezuela, Bolivarian Republic of
VGB	Virgin Islands, British
VIR	Virgin Islands, U.S.
VNM	Viet Nam
VUT	Vanuatu
WLF	Wallis and Futuna
WSM	Samoa
YEM	Yemen
ZAF	South Africa
ZMB	Zambia
ZWE	Zimbabwe