Creating and Managing Users via API

Owned by Jason Key (Deactivated)
Last updated: Mar 30, 2022 by Miles Graves
9 min read

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.

  1. Visit the Portal Dashboard

  2. Click Users (under the Management Tab)

  3. Click the Add User button and set the Role, Username, Password, Full Name, and Email Address.

  4. Click on the newly created user from the User's menu

  5. You’ll find the Login ID under “Parent Login ID” within the User sub-menu.

  6. 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

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

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

Field Value

Role Value

Description

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

Code Example:

        "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

Code Example:

"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

Restricted Resources


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