Enrollment Service ¶

The enrollment service provides a series of endpoints to enroll guests in a merchant program, possibly creating virtual cards or activating physical cards, and editing that enrollment information later.

Those endpoints are:

Creates	Activates	Registers	Set Account Fields*	Set Related Guest Fields	Endpoint
					`POST enrollment/createAndEdit.json`
					`POST enrollment/createAndRegister.json`
					`POST enrollment/createAndRegisterWithCardNumber.json`
					`POST enrollment/createEClubAndRegister.json`
					`POST enrollment/activateAndEdit.json`
					`POST enrollment/activateAndRegister.json`
					`POST enrollment/addAccountPerk.json`
					`POST enrollment/addAddressForUser.json`
					`DELETE enrollment/deleteAddressForUser.json`
					`DELETE enrollment/user.json`
					`DELETE enrollment/userByPrintedCardNumber.json`
					`POST enrollment/editAddressForUser.json`
					`POST enrollment/editUser.json`
					`POST enrollment/editAccount.json`
					`POST enrollment/editEClubAccount.json`
					`POST enrollment/register.json`
					`POST enrollment/editExternalAccounts.json`
					`GET enrollment/eClubEnrollmentConfig.json`
					`GET enrollment/enrollmentConfig.json`
					`POST enrollment/editRelatedGuest.json`
					`POST enrollment/addRelatedGuests.json`
					`DELETE enrollment/relatedGuest.json`
					`POST enrollment/validateRelatedGuest.json`
					`POST enrollment/smsEnroll.json`
					`POST enrollment/editSmsEnroll.json`

* Customer number, perks, and external account number

Topics

Enrollment Service

User Fields and Account Fields ¶

Most of the endpoints take one or two compound parameters: setUserFields and setAccountFields. setUserFields can contain a number of demographic fields such as first name or last name to set for the cardholder in the Paytronix system. These fields are associated with the user who might have one or more accounts although typically a user has only a single account associated with them. setAccountFields similarly contains fields that are set at the account level, usually identified by card number.

Both parameters may be specified in two different styles – string where each value is a plain string which will then be converted by the service into the appropriate type, and typed where the values must be the appropriate JSON type. When possible, use the typed style. The string style is provided to facilitate simple web forms where all the validation should be performed by the Paytronix server.

Set, Clear or Keep Style Fields ¶

Many fields in setUserFields and setAccountFields have type List[String] or similar and are optional. For such a field, you can send one of three forms, depending on the desired effect:

"field": null or not sending the field at all: The enrollment service will not alter the existing value of this field for the cardholder. For example, if the cardholder was previously updated with firstName "John" and the request does not mention firstName or sends "firstName": null then the cardholder will be left with firstName "John". Similarly, if the cardholder had no firstName set, it will remain with no firstName set.
"field": [] or "field": [null]: The enrollment service will clear the field for the cardholder. For example, if the cardholder had firstName "John" previously set then the firstName field will be cleared, assuming that no other error occurs.
"field": ["value"]: The enrollment service will set the field to the given value assuming no other error occurs and the given value is valid for the field. For example, if the cardholder has firstName "John" previously set and the request specifies "firstName": ["Bob"] then the cardholder will have their firstName overwritten with "Bob'.

The above does not apply to Secondary Address endpoints or Related Guest endpoints, as those have explicit add/edit/delete calls.

SetUserFields¶

JSON Parameters:

style (String) – (required) Either strings or typed. Indicates whether the rest of the fields are typed or not. If not, the same fields are present but they all have type String instead of their actual type. Use typed unless there is a particular requirement.
optIn (Boolean) – (optional) Opt-in true indicates the user wishes to receive emails materials from time to time, false means they do not wish to. If blank, the system auto sets this value to true on the users account.
salutation (List[String]) – (optional) Allowed values are Mr., Ms., Mrs., Dr., and Rev. See Set, Clear or Keep Style Fields
firstName (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 30 characters. See Set, Clear or Keep Style Fields
lastName (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 30 characters. See Set, Clear or Keep Style Fields
companyName (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 50 characters. See Set, Clear or Keep Style Fields
email (List[String]) – (optional) If a value is provided, it must be non-empty, no longer than 100 characters, and a well formatted email address. [ ] ( ) < > \\ " and control characters are not allowed anywhere in the email address. There must be exactly one @ in a valid email address. The part after the @ must be a series of . separated segments, and cannot be either led by or trailed by a . See Set, Clear or Keep Style Fields
addressLabel (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. See Set, Clear or Keep Style Fields
address1 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. See Set, Clear or Keep Style Fields
address2 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. See Set, Clear or Keep Style Fields
city (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 50 characters. See Set, Clear or Keep Style Fields
stateProvince (List[String]) – (optional) If a value is provided, must be a valid two-letter state or province code for the country. If the country is not specified, US is assumed. See Set, Clear or Keep Style Fields
postalCode (List[String]) – (optional) If a value is provided, must be a valid postal code for the given country and state/province. See Set, Clear or Keep Style Fields
country (List[String]) – (optional) Allowed values are US and CA See Set, Clear or Keep Style Fields
phone (List[String]) – (optional) Validated using Phone Number Validation. See Phone Number Validation
fax (List[String]) – (optional) If a value is provided, it must be exactly 10 numeric digits. See Set, Clear or Keep Style Fields
mobilePhone (List[String]) – (optional) Validated using Phone Number Validation. See Phone Number Validation
dateOfBirth (List[Date]) – (optional) If a value is provided, the date must be before the date the request is received, and after 1753-01-01 See Set, Clear or Keep Style Fields
anniversaryDate (List[Date]) – (optional) If a value is provided, the date must be before the date the request is received, and after 1753-01-01 See Set, Clear or Keep Style Fields
custom1 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field. See Set, Clear or Keep Style Fields
custom2 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field. See Set, Clear or Keep Style Fields
custom3 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field. See Set, Clear or Keep Style Fields
custom4 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field. See Set, Clear or Keep Style Fields
custom5 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field. See Set, Clear or Keep Style Fields
custom6 (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 100 characters. For some programs, additional validation may apply to this field. See Set, Clear or Keep Style Fields
username (List[String]) – A value must be provided for endpoints that register, and the value must be at least 6 characters, no longer than 60 characters, not having leading or trailing whitespace, and be unique among cardholders of the merchant. Cannot be specified for users that are not yet registered, unless the endpoint is one that performs registration. See Set, Clear or Keep Style Fields
password (List[String]) – A value must be provided for endpoints that register, and the value must be at least 6 characters. Cannot be specified for users that are not yet registered, unless the endpoint is one that performs registration. See Set, Clear or Keep Style Fields
textCampaignOptIn (Boolean) – (optional) Opt-in true indicates the user wishes to receive marketing materials from time to time via text message (SMS), false means they do not wish to. Do not send this if the Paytronix merchant does not use Paytronix for SMS, as it will not be persisted unless SMS is configured and enabled first.
nickname (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 30 characters. See Set, Clear or Keep Style Fields
avatarCode (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 30 characters. See Set, Clear or Keep Style Fields
referrerEmail (List[String]) – (optional) If a value is provided, it contains the email address of an existing user who referred this new user and must be no longer than 100 characters. The referrer will not receive their reward if this value is not provided during registration. See Set, Clear or Keep Style Fields
referralCode (List[String]) – (optional) If a value is provided, it contains the encrypted code of a bulk referral. The referrer will not receive their reward if this value is not provided during registration. Do not provide both referrerEmail and referralCode. See Set, Clear or Keep Style Fields

Complete example which sets most fields, clears the value of custom1 and custom2, and leaves the current value of custom3 and custom4 unchanged:

{
    "style": "typed",
    "optIn": true,
    "salutation": ["Mr."],
    "firstName": ["Test"],
    "lastName": ["User"],
    "companyName": ["Paytronix Systems, Inc."],
    "email": ["[email protected]"],
    "addressLabel": ["Home"],
    "address1": ["307 Waverley Oaks Rd."],
    "address2": ["Suite 309"],
    "city": ["Waltham"],
    "stateProvince": ["MA"],
    "postalCode": ["02452"],
    "country": ["US"],
    "phone": ["6176493300"],
    "fax": ["6178120725"],
    "mobilePhone": ["9995551212"],
    "dateOfBirth": ["1980-01-01"],
    "anniversaryDate": ["2005-01-01"],
    "custom1": [],
    "custom2": [],
    "custom3": null,
    "custom5": ["A custom value"],
    "custom6": ["A custom value"],
    "username": ["testuser"],
    "password": ["test1234"],
    "nickname": "tester",
    "avatarCode": ["QA_BADGE_004"],
    "referrerEmail": ["[email protected]"],
    "referralCode": ["JB2IUG_iubdbk2cwelkcI4HNILV5vGliugGIndcNUWDIUYG"]
}

SetAccountFields¶

JSON Parameters:

style (String) – (required) Either strings or typed. Indicates whether the rest of the fields are typed or not. If not, the same fields are present but they all have type String instead of their actual type. Use typed unless there is a particular requirement.
customerNumber (List[String]) – (optional) If a value is provided, it must be non-empty and no longer than 30 characters. See Set, Clear or Keep Style Fields
perks (List[Object]) – (optional) See SetPerk. Note that this performs a SET operation to the perks array, rather than an ADD.
externalAccounts (List[Object]) – (optional) See SetExternalAccount
favoriteStore (List[Object]) – (optional) See SetFavoriteStore
favoriteStores (List[Object]) – (optional) Takes a list of json objects, each containing a “code” key with the value being a store code string corresponding to a store that exists within the given merchant. NOTE: If an input store is the same store as the primary favorite store above, it will remain the primary favorite store and not be added here.

Example:

{
    "style": "typed",
    "customerNumber": ["123456"],
    "perks": [
        { "code": 1, "label": "Gluten Free" },
        { "code": 2, "label": "Prefers Breakfast Rewards" }
    ],
    "perksModifiedDate": ["2012-05-01"],
    "externalAccounts": [
        {
            "integration": "xhDE_Ea4QhsfC8h3pUtHJnLZ9lRXYgysJVXnR4XNO0",
            "accountCode": "123456"
        }
    ],
    "favoriteStore": [{"code": "123"}],
    "favoriteStores": [
      {
          "code": "27"
      },
      {
         "code": "32"
      },
      {
         "code": "36"
      }
   ]
}

SetPerk¶

JSON Parameters:
	code (Integer) – (required) Paytronix-assigned perk code to set. label (String) – (required) Paytronix-assigned human-readable perk label to set.

SetExternalAccount¶

JSON Parameters:

integration (String) – (required) Identifies the scope of the external account, e.g. Facebook, or iOS. Contact Paytronix to understand what the possible values are.
accountCode (String) – (required) Unique identifier for the external account within the scope of the integration.
appIdentifier (String) – (optional) This field is required for Mobile Push and Apple SSO.
accessToken (String) – (optional) An OAuth access token for the external account so that actions can be taken on behalf of the user by the Paytronix system. Used with Facebook accounts, for example.
integrationDetail (String) – (optional) Additional detail about the integration setting the external account, such as version number.

AddressInformation¶

JSON Parameters:

addressId (Integer) – (optional) Unique id referring to existing address record. (required) for calls to edit or delete address
label (String) – (required) Label for the address. Maximum of 30 characters.
address1 (String) – (optional) First line of the address. Maximum of 100 characters.
address2 (String) – (optional) Second line of the address. Maximum of 100 characters.
city (String) – (optional) Maximum of 50 characters.
stateProvince (String) – (optional) A valid two character state or province abbreviation.
postalCode (String) – (optional) A valid United States zip code or Canadian postal code.
country (String) – (optional) A valid country code.

SetFavoriteStore¶

JSON Parameters:
	code (String) – (required) A Paytronix store code.

RelatedGuestFieldsInput¶

JSON Parameters:
	salutation (String) – (optional) One of `Mr.`, `Ms.`, `Mrs.`, `Dr.`, and `Rev.` firstName (String) – (optional) Maximum of 30 characters lastName (String) – (optional) Maximum of 30 characters email (String) – (optional) Maximum of 100 characters dateOfBirth (String) – (optional) Related guest’s date of birth in `yyyy-mm-dd` format.

Phone Number Validation ¶

Phone Number validation in UserInputFields depends on the country the phone number is from. The country for which validation is applied is derived from the fields for Country, StateProvince, PostalCode, the existingAddress passed in separately, and then the country that the “Corp” store exists in, in that order.

All phone number validation allows any of the characers “+()./_- ” (that includes a <space> character). These will be stripped out before the next step is applied. Any phone number with any characters other than these that are not numeric will be deemed invalid.

US Phone Numbers:: A US Phone Number is valid if the numeric part is 10 digits and doesn’t begin with a ‘1’ or a ‘0’, or 11 digits and begins with a ‘1’
UK Phone Numbers:: A UK Phone Number is valid if the numeric part begins with a ‘0’ and is either 8, 10, or 11 digits long
Singaporean Phone Numbers:: An SG Phone Number is valid if the numeric part is exactly 8 digits long

Field Validation Errors ¶

Code	Description
`cannot_be_set_unless_registered`	Cannot be set unless the user is registered.
`exceeded_max_related_guests`	The user has maximum number allotted for related guests.
`invalid_can_postal_format`	Canadian postal code was formatted incorrectly.
`invalid_date`	Invalid date format, too far in the past or in the future.
`invalid_email`	Invalid email address.
`invalid_enumeration`	Value is not an allowed option for this field.
`invalid_field`	Field cannot be sent for this operation.
`invalid_format`	Non-specific formatting error in the value.
`invalid_negative`	Non-negative value required.
`invalid_negative_or_zero`	Positive value required.
`invalid_non_numeric`	Must be numeric.
`invalid_numeric`	Must not be entirely numeric.
`invalid_positive`	Non-positive value required.
`invalid_positive_or_zero`	Negative value required.
`invalid_postal_province_combo`	Canadian postal code was not valid for the province.
`invalid_username_length`	Username must be 6-16 characters.
`invalid_username_numeric`	Username cannot be all numeric.
`invalid_username_underscore`	Username cannot have leading underscores.
`invalid_username_whitespace`	Username cannot have leading or trailing spaces.
`invalid_value`	Non-specific error with the value.
`invalid_zip_format`	US ZIP Code was formatted incorrectly.
`invalid_zip_state_combo`	US ZIP code was not valid for the state.
`non_null_field`	Value should not be present (e.g. prohibited by other settings).
`non_existent_related_guests`	Value passed in for relatedGuestCode was invalid.
`null_field`	Value is required.
`overflow`	Must less than or equal to some maximum number.
`password_no_alpha`	Password must have at least 1 alphabetic character.
`password_no_nonalpha`	Password must have at least 1 non-alphabetic character (digit or punctuation).
`too_long`	Value was too long.
`too_short`	Value was too short.
`underflow`	Must greater than or equal to some minimum number.
`username_exists`	This username already exists. Please choose another.
`email_exists`	Email address already exists. Please use another email address.

Enforcing Field Uniqueness ¶

Most endpoints take a parameter enforceUniqueFields, which is a list of field names that the enrollment service should check the uniqueness of against the existing cardholders in the program before committing any changes. After checking that the inputs for the request are generally valid, the enrollment service will go through each field named in enforceUniqueFields and look for any existing cardholders in the program which have the same value as the request.

For example, if a request like this was sent:

{
    ...
    "enforceUniqueFields": ["phone", "email"],
    ...
    "setUserFields": {
        ...
        "phone": "9995551212",
        "email": "[email protected]",
        ...
    },
    ...
}

The service will first check if any existing cardholder has the phone 9995551212. If no match is found, then it will then check if any existing cardholder has the email example@paytronix.com. Only in the case where all fields are cleared will the service go ahead and perform the requested action. If a conflicting cardholder is found, then a uniqueness conflict result will be returned.

Only the following fields can be specified in enforceUniqueFields:

externalAccountIdentifier
customerNumber
email
name (matches firstName and lastName)
phone
fax
mobilePhone

Endpoints ¶

Create an Account and Set Fields ¶

POST enrollment/createAndEdit.json¶

Creates and activates a new virtual card and then sets various demographic information (first name, last name, etc) for it, but does not register it. username and password in setUserFields cannot be used.

The following authentication methods are supported for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program to enroll the user in.
activationStoreCode (String) – (optional) Paytronix store code where the activation transaction should be performed. Defaults to pxweb
enforceUniqueFields (List[String]) – (required) See Enforcing Field Uniqueness
setUserFields (Object) – (required) See SetUserFields
setAccountFields (Object) – (required) See SetAccountFields

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "cardTemplateCode": 0,
    "activationStoreCode": "pxweb",
    "enforceUniqueFields": ["mobilePhone"],
    "setUserFields": { ... },
    "setAccountFields": { ... }
}

See Common Enrollment Service Response for detail about the responses for this endpoint.

Create and Register an Account ¶

POST enrollment/createAndRegister.json¶

Creates, activates, and then registers a new virtual card with the given demographic information. Username and password are required in setUserFields.

The following authentication methods are supported for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program to enroll the user in.
activationStoreCode (String) – (optional) Paytronix store code where the activation transaction should be performed. Defaults to pxweb
enforceUniqueFields (List[String]) – (required) See Enforcing Field Uniqueness
setUserFields (Object) – (required) See SetUserFields
setAccountFields (Object) – (required) See SetAccountFields

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "cardTemplateCode": 0,
    "activationStoreCode": "pxweb",
    "enforceUniqueFields": ["mobilePhone"],
    "setUserFields": { ... },
    "setAccountFields": { ... }
}

See Common Enrollment Service Response for details of the responses for this endpoint.

Create and Register an Account with CardNumber ¶

POST enrollment/createAndRegisterWithCardNumber.json¶

Creates, activates, and then registers the passed in virtual card with the given demographic information. Username and password are required in setUserFields. Note for this endpoint, only cardNumbers that belong to cardBatch “Reverse Enrollment with card” will be accepted.

The following authentication methods are supported for this endpoint:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) Card Number that needs to be activated (needs to belong to “Reverse Enrollment with card” card batch)
cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program to enroll the user in.
activationStoreCode (String) – (optional) Paytronix store code where the activation transaction should be performed. Defaults to pxweb
enforceUniqueFields (List[String]) – (required) See Enforcing Field Uniqueness
setUserFields (Object) – (required) See SetUserFields
setAccountFields (Object) – (required) See SetAccountFields

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "printedCardNumber": "601325887998001"
    "cardTemplateCode": 0,
    "activationStoreCode": "pxweb",
    "enforceUniqueFields": ["mobilePhone"],
    "setUserFields": { ... },
    "setAccountFields": { ... }
}

See Common Enrollment Service Response for details of the responses for this endpoint.

Create and Register an account for an eClub Program ¶

POST enrollment/createEClubAndRegister.json¶

Creates, activates and then registers a new virtual eClub card with the given demographic information. Email is required in the setUserFields.

The following authentication methods are supported for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the eClub program to enroll the user in.
activationStoreCode (String) – (optional) Paytronix store code where the activation transaction should be performed. The activation store defaults to pxweb if this field isn’t set.
enforceUniqueFields ((List[String])) – (required) See Enforcing Field Uniqueness in.
setUserFields (Object) – (required) See SetUserFields in.
setAccountFields (Object) – (required) See SetAccountFields in.

Example:

{
   "authentication": "anonymous",
   "merchantId": 123,
   "cardTemplateCode": 0,
   "activationStoreCode": "pxweb",
   "enforceUniqueFields": [],
   "setUserFields":{ ... },
   "setAccountFields": { ... }
}

See Common Enrollment Service Response for details of the responses for this endpoint.

Activate a Card and Set Fields ¶

POST enrollment/activateAndEdit.json¶

Activates a preexisting card and then sets demographic information for the cardholder, but does not register it. username and password in setUserFields cannot be used.

The following authentication methods are supported for this endpoint:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) The card of the user.
activationStoreCode (String) – (optional) Paytronix store code where the activation transaction should be performed. Defaults to pxweb
enforceUniqueFields (List[String]) – (required) See Enforcing Field Uniqueness
setUserFields (Object) – (required) See SetUserFields
setAccountFields (Object) – (required) See SetAccountFields

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "printedCardNumber": "6000100000001985",
    "activationStoreCode": "pxweb",
    "enforceUniqueFields": ["mobilePhone"],
    "setUserFields": { ... },
    "setAccountFields": { ... }
}

See Common Enrollment Service Response for details of the responses for this endpoint.

Activate and Register an Account ¶

POST enrollment/activateAndRegister.json¶

Activates a preexisting card and then registers it with the given demographic information. username and password are required in setUserFields.

The following authentication methods are supported for this endpoint:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) The card of the user.
activationStoreCode (String) – (optional) Paytronix store code where the activation transaction should be performed. Defaults to corp
enforceUniqueFields (List[String]) – (required) See Enforcing Field Uniqueness
setUserFields (Object) – (required) See SetUserFields
setAccountFields (Object) – (required) See SetAccountFields

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "printedCardNumber": "6000100000001985",
    "activationStoreCode": "pxweb",
    "enforceUniqueFields": ["mobilePhone"],
    "setUserFields": { ... },
    "setAccountFields": { ... }
}

See Common Enrollment Service Response for details of the responses for this endpoint.

Add a Perk to an Account ¶

POST enrollment/addAccountPerk.json¶

Adds a perk (specified by Paytronix-assigned perk code) to a user’s account. One of printedCardNumber or accountId is required.

The following authentication methods are supported for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (optional) The printed card number of the user. accountId (Integer) – (optional) The account ID of the user. perkCode (Integer) – (required) Paytronix-assigned perk code to add.

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "printedCardNumber": "6000100000002024",
    "perkCode": 123456
}

"result": "success"

JSON Parameters:
	result (String) – (required) `success` perkCode (Integer) – (required) The Paytronix-assigned perk code that was added to the user’s account.

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Add a Secondary Address For User ¶

POST enrollment/addAddressForUser.json¶

Adds another address for a user that will be returned in UserInformation

The following authentication methods are supported for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user. addressInformation (Object) – (required) See `AddressInformation`

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "printedCardNumber": "6000100000001985",
    "addressInformation": { ... }
}

Delete a Secondary Address For User ¶

DELETE enrollment/deleteAddressForUser.json¶

Deletes an address record for a user with the given addressId. Can only delete addresses added by POST enrollment/addAddressForUser.json

The following authentication methods are supported for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user. addressId (Integer) – (required) The id of the address to be deleted

Delete User ¶

DELETE enrollment/user.json¶

Deletes user data for a user identified by its username. De-identifies and de-registers the user; account information and balances are not affected.

The following authentication methods are supported for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. username (String) – (required) Username associated with the user/account to delete.

Delete User By Printed Card Number ¶

DELETE enrollment/userByPrintedCardNumber.json¶

Deletes user data for a user identified by its printed card number. De-identifies and de-registers the user; account information and balances are not affected.

The following authentication methods are supported for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) Printed card number of the card associated with the user/account to delete

Edit an Address For User ¶

POST enrollment/editAddressForUser.json¶

Overwrites all fields on an address record for a user with the given addressId. To get the addresses available to edit for a user call the userInformation endpoint in the Guest Service

The following authentication methods are supported for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) The card of the user. addressInformation (Integer) – (required) See `AddressInformation` - note: addressId field is required for this endpoint

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "printedCardNumber": "6000100000001985",
    "addressInformation": { ... }
}

Edit User Fields ¶

POST enrollment/editUser.json¶

Edits the demographic data for a user, without affecting whether the user is registered or not. If the user is not already registered, then setting username or password in setUserFields is forbidden. However if the user is already registered, then it is legal to set them.

Note that uniqueness cannot be enforced using this endpoint because the card template (program) is not known. Use POST enrollment/editAccount.json supplying a printed card number if this behavior is required.

The following authentication methods are supported for this endpoint:

JSON Parameters:
	username (String) – (required) Name of the user to modify. To obtain the username given a printed card number, see Guest Service, or use `POST enrollment/editAccount.json` setUserFields (Object) – (required) See `SetUserFields`

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "username": "testuser",
    "setUserFields": { ... }
}

See Common Enrollment Service Response for details of the responses for this endpoint.

Edit User or Account Fields ¶

POST enrollment/editAccount.json¶

Edits the demographic data for an account and user, without affecting whether the associated user is registered or not. If the user is not already registered, then setting username or password in setUserFields is forbidden. However if the user is already registered, then it is legal to set them.

The following authentication methods are supported for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) Printed card number of the account to modify.
accountId (Int) – (optional) The ID of the user account to be edited.
enforceUniqueFields (List[String]) – (required) See Enforcing Field Uniqueness
setUserFields (Object) – (required) See SetUserFields
setAccountFields (Object) – (required) See SetAccountFields

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "printedCardNumber": "6000100000001985",
    "accountId": 54,
    "enforceUniqueFields": ["mobilePhone"],
    "setUserFields": { ... },
    "setAccountFields": { ... }
}

See Common Enrollment Service Response for details of the responses for this endpoint.

Edit User or Account Fields for an eClub Account ¶

POST enrollment/editEClubAccount.json¶

Edits the demographic data for an account without affecting whether the associated account is registered or not.

The following authentication methods are supported for this endpoint:

Guest email authentication

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
email (String) – (required) Email address associated with the account to edit.
cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the eClub program to enroll the user in.
enforceUniqueFields (List[String]) – (required) See Enforcing Field Uniqueness
setUserFields (Object) – (required) See SetUserFields
setAccountFields (Object) – (required) See SetAccountFields

Example:

{
  "authentication": "email",
  "merchantId": 777777,
  "cardTemplateCode": 1,
  "email": "[email protected]",
  "enforceUniqueFields": [
        "email"
  ],
  "setUserFields": {
        "style": "typed",
        "optIn": true,
        "phone": [
          "9708675309"
        ]
  },
  "setAccountFields": {
        "style": "typed",
        "favoriteStore": [

        ]
  }
}

See Common Enrollment Service Response for details of the responses for this endpoint.

Register an Active Account ¶

POST enrollment/register.json¶

Registers an already activated card with the given demographic data. username and password must be set in setUserFields.

The following authentication methods are supported for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) Name of the user to modify. To obtain the username given a printed card number, see Guest Service.
accountId (Int) – (optional) The ID of the user account to register.
enforceUniqueFields (List[String]) – (required) See Enforcing Field Uniqueness
setUserFields (Object) – (required) See SetUserFields
setAccountFields (Object) – (required) See SetAccountFields

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "printedCardNumber": "6000100000001985",
    "accountId": 54,
    "enforceUniqueFields": ["mobilePhone"],
    "setUserFields": { ... },
    "setAccountFields": { ... }
}

See Common Enrollment Service Response for details of the responses for this endpoint.

Change External Accounts Linked to an Account ¶

POST enrollment/editExternalAccounts.json¶

Edits the external account identifiers for an account, leaving other account and user attributes untouched. If constrainByIntegration is set, then external accounts with integrations that do not match will be untouched, regardless of the operation chosen.

The following authentication methods are supported for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) The card of the user.
constrainByIntegration (String) – (optional) If specified, only manipulate external accounts for the given integration. Contact Paytronix to understand what the possible values are.
operation (String) – (required) Value can be add, which means that the listed external accounts should be added if they do not already exist, remove meaning to remove any that do exist, or set which means that external accounts should be added and deleted to match the given list.
externalAccounts (List[Object]) – (required) List of external accounts to add, remove, or set. See SetExternalAccount

Example:

{
    "authentication": "b2b",
    "merchantId": 123,
    "printedCardNumber": "6000100000001985",
    "constrainByIntegration": "1gVdgGicN7m7MD9BxzXar2uqCnH3I4Qf7Zcw2mjYXL",
    "operation": "set",
    "externalAccounts": [
        {
            "integration": "1gVdgGicN7m7MD9BxzXar2uqCnH3I4Qf7Zcw2mjYXL",
            "accountCode": "123456"
        }
    ]
}

See Common Enrollment Service Response for details of the responses for this endpoint.

Get User and Account Field Settings for an eClub Program ¶

GET enrollment/eClubEnrollmentConfig.json¶

Returns information about each field used for enrolling guests into an eClub.

The following authentication methods are supported for this endpoint:

Anonymous authentication

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the eClub program to enroll the user in.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` config (Object) – (required) Details about the enrollment configuration. See `EnrollmentConfig` below.

Example:

{
  "result": "success",
  "config": {
        "fields": [
          {
                "type": "entry",
                "field": "firstName",
                "label": "First Name",
                "maxLength": 30,
                "minLength": 1,
                "pattern": "[- a-zA-z]+",
                "required": true,
                "setOnce": false
          },
          {
                "type": "entry",
                "field": "lastName",
                "label": "Last Name",
                "maxLength": 30,
                "minLength": 1,
                "pattern": "[- a-zA-z]+",
                "required": true,
                "setOnce": false
          },
          {
                "type": "entry",
                "field": "postalCode",
                "label": "Zip Code",
                "maxLength": 10,
                "minLength": 5,
                "pattern": "^\\d{5}$|^\\d{9}$|^\\d{5}( |-)\\d{4}$|^[A-Za-z]\\d[A-Za-z](( |-)?)\\d[A-Za-z]\\d$",
                "required": true,
                "setOnce": false
          },
          {
                "type": "date",
                "field": "dateOfBirth",
                "label": "DOB",
                "required": true,
                "setOnce": true
          },
          {
                "type": "email",
                "field": "email",
                "label": "Email Address",
                "required": true,
                "setOnce": true
          }
        ],
        "maxRelatedUsers": 0
  }
}

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Get User and Account Field Settings for a Program ¶

GET enrollment/enrollmentConfig.json¶

Returns information about each field used for enrollment/edit of user and account information.

The following authentication methods are supported for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program to enroll the user in.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` config (Object) – (required) Details about the enrollment configuration. See `EnrollmentConfig` below.

Example:

{
    "config": {
        "fields": [
            {
                "field": "firstName",
                "label": "First Name",
                "maxLength": 30,
                "minLength": 3,
                "pattern": "[- a-zA-z]+",
                "required": true,
                "type": "entry",
                "setOnce": false
            },
            {
                "field": "mobilePhone",
                "label": "Mobile Phone",
                "required": true,
                "type": "phone",
                "setOnce": false
            },
            {
                "field": "email",
                "label": "Email",
                "required": true,
                "type": "email",
                "setOnce": false
            },
            {
                "field": "optIn",
                "label": "Opt In to Email",
                "required": false,
                "type": "boolean",
                "setOnce": false
            },
            {
                "field": "dateOfBirth",
                "label": "Date Of Birth",
                "required": true,
                "type": "date",
                "setOnce": true
            },
            {
                "field": "postalCode",
                "label": "ZIP Code",
                "maxLength": 5,
                "minLength": 5,
                "pattern": "\\d{5}",
                "required": false,
                "type": "entry",
                "setOnce": false
            },
            {
                "field": "country",
                "label": "Country",
                "required": false,
                "type": "selection",
                "setOnce": false,
                "values": [
                    {
                        "code": "US",
                        "label": "USA"
                    },
                    {
                        "code": "CA",
                        "label": "Canada"
                    }
                ]
            },
            {
                "field": "custom1",
                "label": "Dietary Preference",
                "required": false,
                "type": "selection",
                "setOnce": false,
                "values": [
                    {
                        "code": "None",
                        "label": "None"
                    },
                    {
                        "code": "Low Sugar",
                        "label": "Low Sugar"
                    },
                    {
                        "code": "Low Fat",
                        "label": "Low Fat"
                    },
                    {
                        "code": "Low Sodium",
                        "label": "Low Sodium"
                    }
                ]
            },
            {
                "field": "custom2",
                "label": "How did you hear about us?",
                "required": true,
                "type": "entry",
                "setOnce": false
            },
            {
                "field": "perks",
                "label": "Favorite Colors",
                "maxSelect": 3,
                "minSelect": 1,
                "required": true,
                "type": "multi-selection",
                "setOnce": false,
                "values": [
                    {
                        "code": "red",
                        "label": "Red"
                    },
                    {
                        "code": "green",
                        "label": "Green"
                    },
                    {
                        "attributes": {
                            "htmlColor": "#0000FF"
                        },
                        "code": "blue",
                        "label": "Blue"
                    },
                    {
                        "code": "yellow",
                        "label": "Yellow"
                    },
                    {
                        "code": "purple",
                        "label": "Purple"
                    }
                ]
            }
        ]
    },
    "result": "success"
}

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

EnrollmentConfig¶

The config object contains fields which is a list of objects, each of which describes a single user or account field. Each object contains at a minimum:

field: Indicates which field is described by the object, e.g. firstName.
label: How the field should be labelled on the input form, e.g. First Name.
type: Indicates which type of field is described by the object and what other fields the object has. See below for the various types.
required: Indicates whether the field must be entered by the user or not.
setOnce: Indicates whether the field should only be set once, typically during registration.

There are several types of field:

"type": "entry": A standard text entry field. See EnrollmentConfigEntryField
"type": "boolean": A boolean field, typically represented as a checkbox. See EnrollmentConfigBooleanField
"type": "date": A date input field. See EnrollmentConfigDateField
"type": "phone": A phone number input field. See EnrollmentConfigPhoneField
"type": "email": An email address input field. See EnrollmentConfigEmailField
"type": "selection": A single selection field, typically represented as a dropdown or spinner. See EnrollmentConfigSelectionField
"type": "multi-selection": A multi-selection field, typically represented as a multi-selection list or list of checkboxes. See EnrollmentConfigMultiSelectionField

JSON Parameters:
	fields (List[Object]) – List of enrollment fields, see previous paragraph for details.

Short example:

{
    "result": "success",
    "config": {
        "fields": [
           { "field": "firstName",     "type": "entry",   "setOnce": False ,      ... },
           { "field": "stateProvince", "type": "selection",       "setOnce": False , ... },
           { "field": "email",         "type": "email",   "setOnce": False ,     ... },
            ...
        ]
    }
}

EnrollmentConfigEntryField¶

An entry field is used for any general type of text entry. If text value must follow a pattern or restrict the character which are valid, then a pattern may be specified. Also, minimum and maximum lengths may be specified.

JSON Parameters:

field (String) – (required) The internal name of the field
label (String) – (required) The display name of the field
required (Boolean) – (required) Will be true if this field is required for enrollment (edit or register), false if field should be displayed but not required
pattern (String) – (optional) If present, the pattern defines a regular expression pattern to which the value of this field must conform.See http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html for a definition of the reqular expression syntax.
minLength (Integer) – (optional) If present, this number defines the minimum length of the value for this field.
maxLength (Integer) – (optional) If present, this number defines the maximum length of the value for this field.

EnrollmentConfigDateField¶

A date entry field. As described in JSON Encoding Details, values must be in the format yyyy-mm-dd which is 10 characters in length. Example: 1985-10-26.

JSON Parameters:
	field (String) – (required) The internal name of the field label (String) – (required) The display name of the field required (Boolean) – (required) Will be `true` if this field is required for enrollment (edit or register), `false` if field should be displayed but not required

EnrollmentConfigEmailField¶

An email field must conform to the formatting of an email address.

JSON Parameters:
	field (String) – (required) The internal name of the field label (String) – (required) The display name of the field required (Boolean) – (required) Will be `true` if this field is required for enrollment (edit or register), `false` if field should be displayed but not required

EnrollmentConfigPhoneField¶

A phone field must be exactly 10 digits (no punctuation or separator characters). This type exists as a hint to the caller on how to capture this field in a UI.

For example, a UI could present 3 text boxes (first length of 3, second length of 3, and third length of 4). However, when submitting a phone field in an edit/register call, the caller would have to combine those 3 UI field values into a single 10 digit string.

JSON Parameters:
	field (String) – (required) The internal name of the field label (String) – (required) The display name of the field required (Boolean) – (required) Will be `true` if this field is required for enrollment (edit or register), `false` if field should be displayed but not required

EnrollmentConfigBooleanField¶

A boolean field requires that the value be either true or false. The UI can capture the true/fales, 1/0, on/off, checked/unchecked value as needed (such as a checkbox) but the resulting field value submitted in an edit/register call must be either true or false.

JSON Parameters:
	field (String) – (required) The internal name of the field label (String) – (required) The display name of the field required (Boolean) – (required) Will be `true` if this field is required for enrollment (edit or register), `false` if field should be displayed but not required

EnrollmentConfigSelectionField¶

A selection field specifies the list of valid values for this field. The value for this field when submitted in an edit/register call must be a code value from one of the Selection entries in the values list.

JSON Parameters:

field (String) – (required) The internal name of the field
label (String) – (required) The display name of the field
required (Boolean) – (required) Will be true if this field is required for enrollment (edit or register), false if field should be displayed but not required
values (List[Object]) – (required) A list of Selection objects. This value submitted for enrollment should be equal to one of the code values from the values selection list

EnrollmentConfigMultiSelectionField¶

A multi-selection field specifies the list of valid values for this field. The value for this field when submitted in an edit/register call must be a list of code values from one or more of the Selection entries in the values list.

JSON Parameters:

field (String) – (required) The internal name of the field
label (String) – (required) The display name of the field
required (Boolean) – (required) Will be true if this field is required for enrollment (edit or register), false if field should be displayed but not required
minSelect (Integer) – (optional) If present, this number defines the minimum number of selections that must be chosen from the values list. If not present but required, then assume 1.
maxSelect (Integer) – (optional) If present, this number defines the maximum length of selections that must be chosen from the values list. If not present, then assume the same value as minSelect.
values (List[Object]) – (required) A list of Selection objects. This field’s value should be a list of the code values from the values selection list

Selection¶

JSON Parameters:
	code (String) – (required) Identifier for the selection, as would be used when submitting this value in an editUser call or the like label (String) – (required) The display name of the selection

Get Configured Perks by Perk Type ¶

GET enrollment/perksByType.json¶

Returns the information about the perk field for a specific perk type

The following authentication methods are supported for this endpoint:

Anonymous authentication

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. cardTemplateCode (Integer) – (required) Paytronix-assigned card template code identifying the program to enroll the user in. perkType (String) – (required) The type of the perk values to return. Currently only supports type `"registration"`

Example of a successful response:

{
        "result": "success",
        "perksField": {
                "type": "multi-selection",
                "field": "perks",
                "label": "Perks",
                "maxSelect": 3,
                "minSelect": 1,
                "required": false,
                "setOnce": false,
                "values": [
                        {
                                "attributes": {
                                "type": "registration"
                                },
                                "code": "1",
                                "label": "Vegan"
                        },
                        {
                                "attributes": {
                                "type": "registration"
                                },
                                "code": "2",
                                "label": "Age Verified"
                        },
                        {
                                "attributes": {
                                "type": "registration"
                                },
                                "code": "0",
                                "label": "Vegetarian"
                        }
                ]
        }
}

Send Email Verification Challenge ¶

POST enrollment/sendVerificationEmail.json¶

Send an email to the user with a link to a URL with a verification code.

The following authentication methods are supported for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
username (String) – (required) The username of the user to verify.
url (String) – (optional) A URL which will be embedded in the email sent to the email address associated to the user. Paytronix will append a URL parameter (id=...) so that when the user clicks on the link in the email, their browser will be redirected to the URL which should extract the id value and pass this as the code parameter to the processEmailVerification resource.

Example of a successful response:

{
    "email": "[email protected]",
    "result": "success"
}

Example of a failed response:

{
    "email": "[email protected]",
    "result": "failure",
    "errorCode": "email_verification.send_failed",
    "errorMessage": "Unable to send email to the specified address"
}

Edit Related Guest ¶

POST enrollment/editRelatedGuest.json¶

Edit user information for guests who do not have their own accounts, but instead are added to an existing account as a related guest

The following authentication methods are supported for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
relatedGuestCode (Integer) – (required) Paytronix-assigned code identifying the related guest to be edited. Can be retrieved using the Guest Service
username (String) – (required) Username of the user to whom the guest is related. To obtain the username given a printed card number, see Guest Service
setRelatedGuestFields (Object) – (required) Fields to update for the related guest. See RelatedGuestFieldsInput below.

Example of request:

{
    "authentication": "b2b",
    "merchantId": 123,
    "username":"someUser"
    "setRelatedGuestFields":{...}
}

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

Example:

{ "result": "success" }

"result": "failure"

JSON Parameters:

result (String) – (required) failure
errorCode (String) – (required) The error code of the failure.
errorMessage (String) – (required) The (human readable) error message of the failure.
errorsByField (Map[String,List[Object]]) – (required) Object representing a map of field name to an object of error code/text. See ValidationError below. Each field name will be prefixed setRelatedGuestFields/, as these are the only fields in the request subject to this validation logic. See Field Validation Errors.

Add Related Guest ¶

POST enrollment/addRelatedGuests.json¶

Add user information for guests who do not have their own accounts, but instead are added to an existing account as a related guest

The following authentication methods are supported for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
username (String) – (required) Username of the user to whom the guest is related. To obtain the username given a printed card number, see Guest Service
setRelatedGuestFields (List[Object]) – (required) List of fields to update for the related guest. See RelatedGuestFieldsInput below.

Example of request:

{
    "authentication": "b2b",
    "merchantId": 123,
    "username":"someUser"
    "setRelatedGuestFields":[{...},{...}]
}

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

Example:

{ "result": "success" }

"result": "failure"

JSON Parameters:

result (String) – (required) failure
errorCode (String) – (required) The error code of the failure.
errorMessage (String) – (required) The (human readable) error message of the failure.
errorsByField (Map[String,List[Object]]) – (required) Object representing a map of field name to an object of error code/text. See ValidationError below. Each field name will be prefixed setRelatedGuestFields/, as these are the only fields in the request subject to this validation logic. See Field Validation Errors.

Remove Related Guest ¶

DELETE enrollment/relatedGuest.json¶

Remove a related guest by making their relation to the referrer inactive and allowing the related user to be a standalone user.

The following authentication methods are supported for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. relatedGuestCode (Integer) – (required) Paytronix-assigned code identifying the related guest to be removed. Can be retrieved using the Guest Service username (String) – (required) Username of the primary user from whom the related guest will be detached, see Guest Service

"result": "success"

JSON Parameters:
	result (String) – (required) `result` removedGuest (RelatedGuest) – (required) The related guest that was deleted is returned. See `RelatedGuest` for the format of this object.

Example:

{ "result" : "success" }

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Validate Related Guest ¶

POST enrollment/validateRelatedGuest.json¶

Validates user information for guests.

The following authentication methods are supported for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. relatedGuestCode (Integer) – (required) Paytronix-assigned code identifying the related guest to be edited. Can be retrieved using the Guest Service setRelatedGuestFields (Object) – (required) Fields to validate. See `RelatedGuestFieldsInput` below.

Example of request:

{
    "authentication": "b2b",
    "merchantId": 123,
    "username":"someUser"
    "setRelatedGuestFields":[{...},{...}]
}

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

Example:

{ "result": "success" }

"result": "failure"

JSON Parameters:

result (String) – (required) failure
errorCode (String) – (required) The error code of the failure.
errorMessage (String) – (required) The (human readable) error message of the failure.
errorsByField (Map[String,List[Object]]) – (required) Object representing a map of field name to an object of error code/text. See ValidationError below. Each field name will be prefixed setRelatedGuestFields/, as these are the only fields in the request subject to this validation logic. See Field Validation Errors.

Complete Email Verification ¶

POST enrollment/processEmailVerification.json¶

Process a verification code for the user. If the code is valid, the user’s email will be marked verified in the Paytronix system.

The following authentication methods are supported for this endpoint:

B2B authentication

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. code (String) – (required) A code extracted from the URL of the caller (`id`).

Example of a successful response:

{
    "email": "[email protected]",
    "result": "success"
}

Example of a failed response:

{
    "email": "[email protected]",
    "result": "failure",
    "errorCode": "email_verification.invalid_code",
    "errorMessage": "Invalid email verification code"
}

Begin an Automatic Account Combine Workflow ¶

POST enrollment/initiateAutoCombine.json¶

Initiates the auto-combine process by sending an email to the address on file for an existing account, asking them to confirm their desire to combine a new card with their existing account. Used following a uniqueness conflict during registration.

The following authentication methods are supported for this endpoint:

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (required) Printed card number associated with the account
combineCode (String) – (required) Code returned by EnrollmentService during uniqueness conflict
confirmationUrl (String) – (optional) URL to be embedded in the auto-combine confirmation email, which will be used to confirm that the owner of the existing account wishes to auto-combine. Paytronix will append a URL parameter (id=...) so that when the user clicks on the link in the email, their browser will be redirected to the URL which should extract the id value and pass this as the confirmationCode parameter to the autoCombineDetails and processAutoCombine resources

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Get Candidate Accounts for Automatic Combine ¶

GET enrollment/autoCombineDetails.json¶

Used to get information on which existing accounts a new card can be combined with. Requires a confirmation code gotten by the cardholder from the email generated by the initiateAutoCombine resource.

The following authentication methods are supported for this endpoint:

Query Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. combineConfirmationCode (String) – (required) A code extracted from the URL of the caller (`id`)

"result": "success"

JSON Parameters:
	result (String) – (required) `success` maskedCardNumber (String) – (required) Masked card number representing the account which will be combined accounts (List[Object]) – (required) Information about the other accounts to which the account can be combined. See `AutoCombineAccountInfo`

"result": "failure"

JSON Parameters:
	result (String) – String (required) `failure` errorCode (String) – String (required) The error code of the failure. errorMessage (String) – String (required) The (human readable) error message of the failure.

AutoCombineAccountInfo¶

This object represents data about accounts to which the new account can be combined. If there is more than one possible account, the guest will have to choose which one to combine the new card to.

JSON Parameters:

maskedCardNumber (String) – (required) Masked card number for this account
firstName (String) – (optional) First name of the owner of this account
lastName (String) – (optional) Last name of the owner of this account
dateOfBirth (Date) – (optional) Date of birth of the owner of this account
lastActivityDate (Date) – (required) Date of this account’s last activity
accountCode (Long) – (required) Unique identifier for this account, to be used in POST enrollment/processAutoCombine.json

Complete an Automatic Combine Workflow ¶

POST enrollment/processAutoCombine.json¶

The last step in the auto-combine process, this resource actually causes the new account to be combined with an existing account. Requires a confirmation code gotten by the cardholder from the email generated by the initiateAutoCombine resource, as well as an accountCode from an autoCombineDetails response.

The following authentication methods are supported for this endpoint:

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. combineConfirmationCode (String) – String (required) A code extracted from the URL of the caller (`id`) accountCode (Long) – Long (required) Code representing the account with which the new account will be combined

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

"result": "accountSuspended"

Depending on the server-side configuration, the cardholder’s account may be suspended in cases where they combine too many cards to a single account. This behavior represents a potential fraud concern, though it may not be desirable to explicitly state such a concern to the user. The user would usually be directed to contact the merchant’s customer service department to resolve the issue

JSON Parameters:
	result (String) – (required) `accountSuspended` errorCode (String) – (required) The error code of the failure. errorMessage (String) – (required) The (human readable) error message of the failure.

Enroll with Mobile Phone via SMS ¶

POST enrollment/smsEnroll.json¶

Enroll a guest with a mobile phone number and an inactive card number. If successful, the mobile phone number will be linked to the new account, and a SMS message will be sent to the mobile phone. If guest replies the SMS message with a valid email address the account will be registered with the email as the username, and SMS opt-in verified.

The following authentication methods are supported for this endpoint:

B2B authentication

JSON Parameters:

merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
printedCardNumber (String) – (optional) If provided the the guest will be enrolled to that card number. Otherwise a new card number will be created for them.
phoneNumber (String) – (required) Mobile phone number
activationStoreCode (String) – (optional) Paytronix store code where the activation transaction should be performed. If this is not provided an activation store needs to be configured in Paytronix’s server.

"result": "success"

JSON Parameters:
	result (String) – (required) `success` printedCardNumber (String) – (required) Printed card number associated with the activated account

"result": "failure"

JSON Parameters:
	result (String) – String (required) `failure` errorCode (String) – String (required) The error code of the failure. errorMessage (String) – String (required) The (human readable) error message of the failure.

Send SMS Enroll text message to Mobile Phone for an active account ¶

POST enrollment/editSmsEnroll.json¶

Send a SMS Enroll text message to a mobile phone number for provided active card number, where the mobile phone number field in the specified user record is empty or matches the provided phone number. If successful, the mobile phone number will be linked to the new account, and a SMS message will be sent to the mobile phone. If guest replies the SMS message with a valid email address the account will be registered with the email as the username, and SMS opt-in verified.

The following authentication methods are supported for this endpoint:

B2B authentication

JSON Parameters:
	merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in. printedCardNumber (String) – (required) Printed card number associated with the account phoneNumber (String) – (required) Mobile phone number

"result": "success"

JSON Parameters:
	result (String) – (required) `success`

"result": "failure"

JSON Parameters:
	result (String) – String (required) `failure` errorCode (String) – String (required) The error code of the failure. errorMessage (String) – String (required) The (human readable) error message of the failure.

Common Enrollment Service Response ¶

These responses are used for many Enrollment Service endpoints, see individual endpoints for which ones use this common format.

"result": "success"

Indicates that the operation succeeded.

JSON Parameters:
	result (String) – (required) `success` modificationsOccurred (Boolean) – (required) Whether or not anything was modified with the enrollment. oauthTokens (Object) – (optional) OAuth tokens to be used to act on behalf of the newly created account. See `TokenResponse` for details accountId (Int) – (optional) The ID of the newly enrolled account.

Example:

{
    "result": "success",
    "modificationsOccurred": "True",
    "oauthTokens": {"access_token": "mF_9.B5f-4.1JqM",
                    "token_type": "Bearer",
                    "expires_in": 3600,
                    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
                    "scope": "openid profile email"
                    "username": "user1a"
                    "printedCardNumber": "01293812048129048"
                    },
    "accountId": "54"
}

"result": "cardCreatedSuccess"

Indicates that the operation succeeded and provides the created card information.

JSON Parameters:

result (String) – (required) cardCreatedSuccess
printedCardNumber (String) – (required) Printed card number of the generated card
generatedRegistrationCode (String) – (optional) Registration code of the generated card
oauthTokens (Object) – (optional) OAuth tokens to be used to act on behalf of the newly created account. See TokenResponse for details
accountId (Int) – (optional) The ID of the user account related to the card creation.

Example:

{
    "result": "cardCreatedSuccess",
    "printedCardNumber": "6000100000001985",
    "generatedRegistrationCode": "578281",
    "accountId": "54"
}

"result": "cardCreatedEmailVerificationRequired"

Indicates that the operation succeeded and provides the created card information, and additionally requires the guest to verify their email address before marking the account as fully registered.

JSON Parameters:

result (String) – (required) cardCreatedSuccess
printedCardNumber (String) – (required) Printed card number of the generated card
generatedRegistrationCode (String) – (optional) Registration code of the generated card
oauthTokens (Object) – (optional) OAuth tokens to be used to act on behalf of the newly created account. See TokenResponse for details
accountId (Int) – (optional) The ID of the user account related to the card creation.

Example:

{
              "result": "cardCreatedEmailVerificationRequired",
              "oauthTokens": {
                      "type": "successAccessRefreshTokenResponse",
                      "access_token": "BXDEaCyGgWAvDyHRygFusmGHoaBYAmeUWqyNEeTkQ6",
                      "expires_in": 1800,
                      "printedCardNumber": "600016157686210",
                      "refresh_token": "H9QiYBXYaZTTfCL7qdtQMcMERwvomMZarEkFARDKcD",
                      "scope": "user_read user_write account_read account_write",
                      "token_type": "bearer",
                      "username": "[email protected]"
              },
              "printedCardNumber": "600016157686210"
}

TokenResponse¶

JSON Parameters:

access_token (String) – (required) Access token to be used in future requests
token_type (String) – (required) Token type is, at present, always bearer. See OAuth 2.0 Bearer Token documentation for further details
expires_in (Integer) – (optional) Time until access token expires
refresh_token (String) – (required) Refresh token to be used for future POST oauth/requestGuestToken.json calls
scope (String) – (optional) Token scope, indicating the sorts of operations which can be performed with the access token
username (String) – (optional) Username of the user for which the tokens are valid
printedCardNumber (String) – (optional) Printed card number of the account for which the tokens are valid

"result": "uniquenessConflict"

Indicates that the operation was not performed because the uniqueness check found a conflicting user.

JSON Parameters:

result (String) – (required) uniquenessConflict
errorCode (String) – (required) The error code of the failure
errorMessage (String) – (required) The (human readable) error message of the failure
conflictingField (String) – (required) Name of the field which was in conflict
canAutoCombine (Boolean) – (required) Boolean value indicating whether or not the new account can be combined to the conflicting account
combineCode (String) – String (optional) Code which can be passed to POST enrollment/initiateAutoCombine.json to begin the auto-combine process

{
    "result": "uniquenessConflict",
    "conflictingField": "mobilePhone"
}

"result": "invalidInputs"

Indicates that the operation was not performed because the inputs could not be validated.

JSON Parameters:

result (String) – (required) invalidInputs
errorCode (String) – (required) The error code of the failure
errorMessage (String) – (required) The (human readable) error message of the failure
errorsByField (Map[String,List[Object]]) – (required) Object representing a map of field name to an object of error code/text. See ValidationError below. Each field name is prefixed by either setUserFields/ or setAccountFields/ to indicate where the field was given in the request. See Field Validation Errors.

{
    "result": "invalidInputs",
    "errorCode": "enrollment_input.validation_error",
    "errorMessage": "Validation error for input fields",
    "errorsByField": {
        "setUserFields/username": [
            {
                 "code": "invalid_username_underscore"
                 "text": "username cannot have leading underscores"
            }
        ]
    }
}

"result": "failure"

Indicates that the operation did not complete successfully and was rolled back as best as able. Example:

JSON Parameters:
	result (String) – (required) `failure` errorCode (String) – (required) The error code of the failure errorMessage (String) – (required) The (human readable) error message of the failure

{
    "result": "failure",
    "responseCode": 435,
    "responseMessage": "Card already active"
}

Reply Objects ¶

RelatedGuest¶

Information about a RelatedGuest

JSON Parameters:

relatedGuestCode (Integer) – (required) Paytronix-assigned code identifying the related guest to be edited. Can be retrieved using the
firstName (String) – (optional) Guest’s first name. Max 30 characters.
lastName (String) – (optional) Guest’s last name. Max 30 characters.
email (String) – (optional) Guest’s email address. Max 100 characters.
dateOfBirth (LocalDate) – (optional) Related Guests’ date of birth in yyyy-mm-dd format.
salutation (String) – (optional) Guest’s salutation. Allowed values are “Mr.”, “Ms.”, “Mrs.”, “Dr.”, and “Rev.”

ValidationError¶

Information about a ValidationError

JSON Parameters:
	code (String) – (required) Machine-readable error code. See Field Validation Errors. text (String) – (required) Human-readable error message.

Error Codes ¶

The following are the possible codes and messages that can be returned by the Enrollment Service.

There are other system-level errors which may be returned which may not be documented here.

The caller of the endpoint can use the returned error message value to display to the end user or, if different wording is desired, can provide their own mapping of code to message.

Note

This list does not currently contain error messages for activateAnd*, createAnd*, editUser, editAccount or register resources.

Code	Message
`email_verification.server_error`	Internal server error
`email_verification.invalid_merchant_id`	Invalid merchant ID
`email_verification.invalid_username`	Invalid username
`email_verification.card_not_active`	Card not active
`email_verification.account_not_active`	Account not active
`email_verification.no_email_address`	User does not have an email address defined
`email_verification.email_already_verified`	Email address already verified
`email_verification.invalid_code`	Invalid code
`enrollment_config.invalid_merchant`	Invalid merchant
`enrollment_config.invalid_card_template`	Invalid card template
`enrollment_config.cache_error`	Cache error
`enrollment_input.validation_error`	Validation error for input fields
`enrollment_input.invalid_field`	Invalid input field
`enrollment_input.username_not_unique`	Username already exists
`enrollment_config.invalid_merchant`	Invalid merchant
`auto_combine.server_error`	Server error
`auto_combine.invalid_merchant_id`	Invalid merchant ID
`auto_combine.invalid_combine_code`	Invalid or expired combine code
`auto_combine.card_not_found`	Card not found
`auto_combine.combine_code_not_for_specified_card`	Combine code is valid, but not for the specified card number
`auto_combine.card_status_not_valid_for_combine`	Card or account status is no longer valid for combine
`auto_combine.card_exchanged`	Card has been exchanged
`auto_combine.already_registered`	This user is already registered
`auto_combine.already_attached`	This card has already been involved in an attach
`auto_combine.no_combinable_accounts`	There are no existing accounts to which this card can be combined
`auto_combine.invalid_combine_confirmation_code`	Invalid combine confirmation code
`auto_combine.merchant_id_mismatch`	Merchant ID in combine confirmation code does not match the merchant ID in the request
`auto_combine.no_matching_account`	The account matching the specified account code either does not exist or is no longer valid for this auto combine
`auto_combine.activation_not_allowed`	Activation of the card referenced in this request is not allowed
`add_perk.server_error`	Server error
`add_perk.account_not_found`	Account not found
`add_perk.perk_not_found`	Perk code does not exist
`add_perk.perk_unavailable`	Perk not available for card template
`add_perk.already_has_perk`	Account already has this perk
`add_perk.too_many_perks`	Account already has maximum number of perks