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 | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | * | * | | * | | :http:post:`enrollment/createAndEdit.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | * | * | * | * | | :http:post:`enrollment/createAndRegister.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | * | * | * | * | | :http:post:`enrollment/createAndRegisterWithCardNumber.json`| +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | * | * | * | * | | :http:post:`enrollment/createEClubAndRegister.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | * | | * | | :http:post:`enrollment/activateAndEdit.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | * | * | * | | :http:post:`enrollment/activateAndRegister.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | | :http:post:`enrollment/addAddressForUser.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | | :http:delete:`enrollment/deleteAddressForUser.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | | :http:delete:`enrollment/user.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | | :http:delete:`enrollment/userByPrintedCardNumber.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | | :http:post:`enrollment/editAddressForUser.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | | :http:post:`enrollment/editUser.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | * | | :http:post:`enrollment/editAccount.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | * | | :http:post:`enrollment/editEClubAccount.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | * | * | | :http:post:`enrollment/register.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | * | | :http:post:`enrollment/editExternalAccounts.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | | :http:get:`enrollment/eClubEnrollmentConfig.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | | :http:get:`enrollment/enrollmentConfig.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | * | :http:post:`enrollment/editRelatedGuest.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | * | :http:post:`enrollment/addRelatedGuests.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | * | :http:delete:`enrollment/relatedGuest.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | | :http:post:`enrollment/validateRelatedGuest.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | * | | | | :http:post:`enrollment/smsEnroll.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ | | | | | | :http:post:`enrollment/editSmsEnroll.json` | +---------+-----------+-----------+----------------------+--------------------------+-------------------------------------------------------------+ \* Customer number, perks, and external account number .. contents:: Topics 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_fields: 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": []`` 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'``. .. http:jsonentity:: SetUserFields :jsonparam String style: *(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. :jsonparam Boolean optIn: *(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. :jsonparam List[String] salutation: *(optional)* Allowed values are ``Mr.``, ``Ms.``, ``Mrs.``, ``Dr.``, and ``Rev.`` See :ref:`set_clear_or_keep_fields` :jsonparam List[String] firstName: *(optional)* If a value is provided, it must be non-empty and no longer than 30 characters. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] lastName: *(optional)* If a value is provided, it must be non-empty and no longer than 30 characters. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] companyName: *(optional)* If a value is provided, it must be non-empty and no longer than 50 characters. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] email: *(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 :ref:`set_clear_or_keep_fields` :jsonparam List[String] addressLabel: *(optional)* If a value is provided, it must be non-empty and no longer than 100 characters. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] address1: *(optional)* If a value is provided, it must be non-empty and no longer than 100 characters. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] address2: *(optional)* If a value is provided, it must be non-empty and no longer than 100 characters. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] city: *(optional)* If a value is provided, it must be non-empty and no longer than 50 characters. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] stateProvince: *(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 :ref:`set_clear_or_keep_fields` :jsonparam List[String] postalCode: *(optional)* If a value is provided, must be a valid postal code for the given country and state/province. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] country: *(optional)* Allowed values are ``US`` and ``CA`` See :ref:`set_clear_or_keep_fields` :jsonparam List[String] phone: *(optional)* Validated using Phone Number Validation. See :ref:`phone_validation` :jsonparam List[String] fax: *(optional)* If a value is provided, it must be exactly 10 numeric digits. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] mobilePhone: *(optional)* Validated using Phone Number Validation. See :ref:`phone_validation` :jsonparam List[Date] dateOfBirth: *(optional)* If a value is provided, the date must be before the date the request is received, and after 1753-01-01 See :ref:`set_clear_or_keep_fields` :jsonparam List[Date] anniversaryDate: *(optional)* If a value is provided, the date must be before the date the request is received, and after 1753-01-01 See :ref:`set_clear_or_keep_fields` :jsonparam List[String] custom1: *(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 :ref:`set_clear_or_keep_fields` :jsonparam List[String] custom2: *(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 :ref:`set_clear_or_keep_fields` :jsonparam List[String] custom3: *(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 :ref:`set_clear_or_keep_fields` :jsonparam List[String] custom4: *(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 :ref:`set_clear_or_keep_fields` :jsonparam List[String] custom5: *(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 :ref:`set_clear_or_keep_fields` :jsonparam List[String] custom6: *(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 :ref:`set_clear_or_keep_fields` :jsonparam List[String] username: 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 :ref:`set_clear_or_keep_fields` :jsonparam List[String] password: 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 :ref:`set_clear_or_keep_fields` :jsonparam Boolean textCampaignOptIn: *(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. :jsonparam List[String] nickname: *(optional)* If a value is provided, it must be non-empty and no longer than 30 characters. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] avatarCode: *(optional)* If a value is provided, it must be non-empty and no longer than 30 characters. See :ref:`set_clear_or_keep_fields` :jsonparam List[String] referrerEmail: *(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 :ref:`set_clear_or_keep_fields` :jsonparam List[String] referralCode: *(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 :ref:`set_clear_or_keep_fields` Complete example which sets most fields, clears the value of ``custom1`` and ``custom2``, and leaves the current value of ``custom3`` and ``custom4`` unchanged: .. code:: javascript { "style": "typed", "optIn": true, "salutation": ["Mr."], "firstName": ["Test"], "lastName": ["User"], "companyName": ["Paytronix Systems, Inc."], "email": ["example@paytronix.com"], "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": ["referrer@paytronix.com"], "referralCode": ["JB2IUG_iubdbk2cwelkcI4HNILV5vGliugGIndcNUWDIUYG"] } .. http:jsonentity:: SetAccountFields :jsonparam String style: *(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. :jsonparam List[String] customerNumber: *(optional)* If a value is provided, it must be non-empty and no longer than 30 characters. See :ref:`set_clear_or_keep_fields` :jsonparam List[Object] perks: *(optional)* See :http:jsonentity:`SetPerk` :jsonparam List[Object] externalAccounts: *(optional)* See :http:jsonentity:`SetExternalAccount` :jsonparam List[Object] favoriteStore: *(optional)* See :http:jsonentity:`SetFavoriteStore` :jsonparam List[Object] favoriteStores: *(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: .. code:: javascript { "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" } ] } .. http:jsonentity:: SetPerk :jsonparam Integer code: *(required)* Paytronix-assigned perk code to set. .. http:jsonentity:: SetExternalAccount :jsonparam String integration: *(required)* Identifies the scope of the external account, e.g. Facebook, or iOS. Contact Paytronix to understand what the possible values are. :jsonparam String accountCode: *(required)* Unique identifier for the external account within the scope of the integration. :jsonparam String appIdentifier: *(optional)* This field is required for Mobile Push. :jsonparam String accessToken: *(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. :jsonparam String integrationDetail: *(optional)* Additional detail about the integration setting the external account, such as version number. .. http:jsonentity:: AddressInformation :jsonparam Integer addressId: *(optional)* Unique id referring to existing address record. *(required)* for calls to edit or delete address :jsonparam String label: *(required)* Label for the address. Maximum of 30 characters. :jsonparam String address1: *(optional)* First line of the address. Maximum of 100 characters. :jsonparam String address2: *(optional)* Second line of the address. Maximum of 100 characters. :jsonparam String city: *(optional)* Maximum of 50 characters. :jsonparam String stateProvince: *(optional)* A valid two character state or province abbreviation. :jsonparam String postalCode: *(optional)* A valid United States zip code or Canadian postal code. :jsonparam String country: *(optional)* A valid country code. .. http:jsonentity:: SetFavoriteStore :jsonparam String code: *(required)* A Paytronix store code. .. http:jsonentity:: RelatedGuestFieldsInput :jsonparam String salutation: *(optional)* One of ``Mr.``, ``Ms.``, ``Mrs.``, ``Dr.``, and ``Rev.`` :jsonparam String firstName: *(optional)* Maximum of 30 characters :jsonparam String lastName: *(optional)* Maximum of 30 characters :jsonparam String email: *(optional)* Maximum of 100 characters :jsonparam String dateOfBirth: *(optional)* Related guest’s date of birth in ``yyyy-mm-dd`` format. .. _phone_validation: 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 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 .. _enrollment_field_errors: 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: 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: .. code:: javascript { ... "enforceUniqueFields": ["phone", "email"], ... "setUserFields": { ... "phone": "9995551212", "email": "example@paytronix.com", ... }, ... } 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 :ref:`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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`anonymous_auth` * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the program to enroll the user in. :jsonparam String activationStoreCode: *(optional)* Paytronix store code where the activation transaction should be performed. Defaults to ``pxweb`` :jsonparam List[String] enforceUniqueFields: *(required)* See :ref:`enforcing_field_uniqueness` :jsonparam Object setUserFields: *(required)* See :http:jsonentity:`SetUserFields` :jsonparam Object setAccountFields: *(required)* See :http:jsonentity:`SetAccountFields` Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "cardTemplateCode": 0, "activationStoreCode": "pxweb", "enforceUniqueFields": ["mobilePhone"], "setUserFields": { ... }, "setAccountFields": { ... } } See :ref:`common_enrollment_response` for detail about the responses for this endpoint. Create and Register an Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`anonymous_auth` * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the program to enroll the user in. :jsonparam String activationStoreCode: *(optional)* Paytronix store code where the activation transaction should be performed. Defaults to ``pxweb`` :jsonparam List[String] enforceUniqueFields: *(required)* See :ref:`enforcing_field_uniqueness` :jsonparam Object setUserFields: *(required)* See :http:jsonentity:`SetUserFields` :jsonparam Object setAccountFields: *(required)* See :http:jsonentity:`SetAccountFields` Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "cardTemplateCode": 0, "activationStoreCode": "pxweb", "enforceUniqueFields": ["mobilePhone"], "setUserFields": { ... }, "setAccountFields": { ... } } See :ref:`common_enrollment_response` for details of the responses for this endpoint. Create and Register an Account with CardNumber ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(required)* Card Number that needs to be activated (needs to belong to "Reverse Enrollment with card" card batch) :jsonparam Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the program to enroll the user in. :jsonparam String activationStoreCode: *(optional)* Paytronix store code where the activation transaction should be performed. Defaults to ``pxweb`` :jsonparam List[String] enforceUniqueFields: *(required)* See :ref:`enforcing_field_uniqueness` :jsonparam Object setUserFields: *(required)* See :http:jsonentity:`SetUserFields` :jsonparam Object setAccountFields: *(required)* See :http:jsonentity:`SetAccountFields` Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "printedCardNumber": "601325887998001" "cardTemplateCode": 0, "activationStoreCode": "pxweb", "enforceUniqueFields": ["mobilePhone"], "setUserFields": { ... }, "setAccountFields": { ... } } See :ref:`common_enrollment_response` for details of the responses for this endpoint. Create and Register an account for an eClub Program ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`anonymous_auth` * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the eClub program to enroll the user in. :jsonparam String activationStoreCode: *(optional)* Paytronix store code where the activation transaction should be performed. The activation store defaults to pxweb if this field isn't set. :jsonparam (List[String]) enforceUniqueFields: *(required)* See *Enforcing Field Uniqueness* in. :jsonparam Object setUserFields: *(required)* See SetUserFields in. :jsonparam Object setAccountFields: *(required)* See SetAccountFields in. Example: .. code:: javascript { "authentication": "anonymous", "merchantId": 123, "cardTemplateCode": 0, "activationStoreCode": "pxweb", "enforceUniqueFields": [], "setUserFields":{ ... }, "setAccountFields": { ... } } See :ref:`common_enrollment_response` for details of the responses for this endpoint. Activate a Card and Set Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(required)* The card of the user. :jsonparam String activationStoreCode: *(optional)* Paytronix store code where the activation transaction should be performed. Defaults to ``pxweb`` :jsonparam List[String] enforceUniqueFields: *(required)* See :ref:`enforcing_field_uniqueness` :jsonparam Object setUserFields: *(required)* See :http:jsonentity:`SetUserFields` :jsonparam Object setAccountFields: *(required)* See :http:jsonentity:`SetAccountFields` Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "printedCardNumber": "6000100000001985", "activationStoreCode": "pxweb", "enforceUniqueFields": ["mobilePhone"], "setUserFields": { ... }, "setAccountFields": { ... } } See :ref:`common_enrollment_response` for details of the responses for this endpoint. Activate and Register an Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(required)* The card of the user. :jsonparam String activationStoreCode: *(optional)* Paytronix store code where the activation transaction should be performed. Defaults to ``corp`` :jsonparam List[String] enforceUniqueFields: *(required)* See :ref:`enforcing_field_uniqueness` :jsonparam Object setUserFields: *(required)* See :http:jsonentity:`SetUserFields` :jsonparam Object setAccountFields: *(required)* See :http:jsonentity:`SetAccountFields` Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "printedCardNumber": "6000100000001985", "activationStoreCode": "pxweb", "enforceUniqueFields": ["mobilePhone"], "setUserFields": { ... }, "setAccountFields": { ... } } See :ref:`common_enrollment_response` for details of the responses for this endpoint. Add a Secondary Address For User ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: enrollment/addAddressForUser.json Adds another address for a user that will be returned in :http:jsonentity:`UserInformation` The following authentication methods are supported for this endpoint: * :ref:`b2b_auth` * :ref:`anonymous_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(required)* The card of the user. :jsonparam Object addressInformation: *(required)* See :http:jsonentity:`AddressInformation` Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "printedCardNumber": "6000100000001985", "addressInformation": { ... } } Delete a Secondary Address For User ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:delete:: enrollment/deleteAddressForUser.json Deletes an address record for a user with the given addressId. Can only delete addresses added by :http:post:`enrollment/addAddressForUser.json` The following authentication methods are supported for this endpoint: * :ref:`b2b_auth` * :ref:`anonymous_auth` :queryparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :queryparam String printedCardNumber: *(required)* The card of the user. :queryparam Integer addressId: *(required)* The id of the address to be deleted Delete User ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:delete:: enrollment/user.json Deletes user account data for a user identified by its username The following authentication methods are supported for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :queryparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :queryparam String username: *(required)* Username associated with the user/account to delete. Delete User By Printed Card Number ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:delete:: enrollment/userByPrintedCardNumber.json Deletes user account data for a user identified by its printed card number. The following authentication methods are supported for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :queryparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :queryparam String printedCardNumber: *(required)* Printed card number of the card associated with the user/account to delete Edit an Address For User ~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`anonymous_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(required)* The card of the user. :jsonparam Integer addressInformation: *(required)* See :http:jsonentity:`AddressInformation` - note: addressId field is required for this endpoint Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "printedCardNumber": "6000100000001985", "addressInformation": { ... } } Edit User Fields ~~~~~~~~~~~~~~~~ .. http: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 :http:post:`enrollment/editAccount.json` supplying a printed card number if this behavior is required. The following authentication methods are supported for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam String username: *(required)* Name of the user to modify. To obtain the username given a printed card number, see :ref:`guest_service`, or use :http:post:`enrollment/editAccount.json` :jsonparam Object setUserFields: *(required)* See :http:jsonentity:`SetUserFields` Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "username": "testuser", "setUserFields": { ... } } See :ref:`common_enrollment_response` for details of the responses for this endpoint. Edit User or Account Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(required)* Printed card number of the account to modify. :jsonparam Int accountId: *(optional)* The ID of the user account to be edited. :jsonparam List[String] enforceUniqueFields: *(required)* See :ref:`enforcing_field_uniqueness` :jsonparam Object setUserFields: *(required)* See :http:jsonentity:`SetUserFields` :jsonparam Object setAccountFields: *(required)* See :http:jsonentity:`SetAccountFields` Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "printedCardNumber": "6000100000001985", "accountId": 54, "enforceUniqueFields": ["mobilePhone"], "setUserFields": { ... }, "setAccountFields": { ... } } See :ref:`common_enrollment_response` for details of the responses for this endpoint. Edit User or Account Fields for an eClub Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`email_auth` * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String email: *(required)* Email address associated with the account to edit. :jsonparam Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the eClub program to enroll the user in. :jsonparam List[String] enforceUniqueFields: *(required)* See :ref:`enforcing_field_uniqueness` :jsonparam Object setUserFields: *(required)* See :http:jsonentity:`SetUserFields` :jsonparam Object setAccountFields: *(required)* See :http:jsonentity:`SetAccountFields` Example: .. code:: javascript { "authentication": "email", "merchantId": 777777, "cardTemplateCode": 1, "email": "test.mctest@test.com", "enforceUniqueFields": [ "email" ], "setUserFields": { "style": "typed", "optIn": true, "phone": [ "9708675309" ] }, "setAccountFields": { "style": "typed", "favoriteStore": [ ] } } See :ref:`common_enrollment_response` for details of the responses for this endpoint. Register an Active Account ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(required)* Name of the user to modify. To obtain the username given a printed card number, see :ref:`guest_service`. :jsonparam Int accountId: *(optional)* The ID of the user account to register. :jsonparam List[String] enforceUniqueFields: *(required)* See :ref:`enforcing_field_uniqueness` :jsonparam Object setUserFields: *(required)* See :http:jsonentity:`SetUserFields` :jsonparam Object setAccountFields: *(required)* See :http:jsonentity:`SetAccountFields` Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "printedCardNumber": "6000100000001985", "accountId": 54, "enforceUniqueFields": ["mobilePhone"], "setUserFields": { ... }, "setAccountFields": { ... } } See :ref:`common_enrollment_response` for details of the responses for this endpoint. Change External Accounts Linked to an Account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(required)* The card of the user. :jsonparam String constrainByIntegration: *(optional)* If specified, only manipulate external accounts for the given integration. Contact Paytronix to understand what the possible values are. :jsonparam String operation: *(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. :jsonparam List[Object] externalAccounts: *(required)* List of external accounts to add, remove, or set. See :http:jsonentity:`SetExternalAccount` Example: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "printedCardNumber": "6000100000001985", "constrainByIntegration": "1gVdgGicN7m7MD9BxzXar2uqCnH3I4Qf7Zcw2mjYXL", "operation": "set", "externalAccounts": [ { "integration": "1gVdgGicN7m7MD9BxzXar2uqCnH3I4Qf7Zcw2mjYXL", "accountCode": "123456" } ] } See :ref:`common_enrollment_response` for details of the responses for this endpoint. Get User and Account Field Settings for an eClub Program ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`anonymous_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the eClub program to enroll the user in. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object config: *(required)* Details about the enrollment configuration. See :http:jsonentity:`EnrollmentConfig` below. Example: .. code:: javascript { "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 } } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Get User and Account Field Settings for a Program ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`anonymous_auth` * :ref:`b2b_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the program to enroll the user in. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam Object config: *(required)* Details about the enrollment configuration. See :http:jsonentity:`EnrollmentConfig` below. Example: .. code:: javascript { "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" } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. .. http:jsonentity:: 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 :http:jsonentity:`EnrollmentConfigEntryField` ``"type": "boolean"`` A boolean field, typically represented as a checkbox. See :http:jsonentity:`EnrollmentConfigBooleanField` ``"type": "date"`` A date input field. See :http:jsonentity:`EnrollmentConfigDateField` ``"type": "phone"`` A phone number input field. See :http:jsonentity:`EnrollmentConfigPhoneField` ``"type": "email"`` An email address input field. See :http:jsonentity:`EnrollmentConfigEmailField` ``"type": "selection"`` A single selection field, typically represented as a dropdown or spinner. See :http:jsonentity:`EnrollmentConfigSelectionField` ``"type": "multi-selection"`` A multi-selection field, typically represented as a multi-selection list or list of checkboxes. See :http:jsonentity:`EnrollmentConfigMultiSelectionField` :jsonparam List[Object] fields: List of enrollment fields, see previous paragraph for details. Short example: .. code:: javascript { "result": "success", "config": { "fields": [ { "field": "firstName", "type": "entry", "setOnce": False , ... }, { "field": "stateProvince", "type": "selection", "setOnce": False , ... }, { "field": "email", "type": "email", "setOnce": False , ... }, ... ] } } .. http:jsonentity:: 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. :jsonparam String field: *(required)* The internal name of the field :jsonparam String label: *(required)* The display name of the field :jsonparam Boolean required: *(required)* Will be ``true`` if this field is required for enrollment (edit or register), ``false`` if field should be displayed but not required :jsonparam String pattern: *(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. :jsonparam Integer minLength: *(optional)* If present, this number defines the minimum length of the value for this field. :jsonparam Integer maxLength: *(optional)* If present, this number defines the maximum length of the value for this field. .. http:jsonentity:: EnrollmentConfigDateField A ``date`` entry field. As described in :ref:`rest_encoding`, values must be in the format ``yyyy-mm-dd`` which is 10 characters in length. Example: ``1985-10-26``. :jsonparam String field: *(required)* The internal name of the field :jsonparam String label: *(required)* The display name of the field :jsonparam Boolean required: *(required)* Will be ``true`` if this field is required for enrollment (edit or register), ``false`` if field should be displayed but not required .. http:jsonentity:: EnrollmentConfigEmailField An ``email`` field must conform to the formatting of an email address. :jsonparam String field: *(required)* The internal name of the field :jsonparam String label: *(required)* The display name of the field :jsonparam Boolean required: *(required)* Will be ``true`` if this field is required for enrollment (edit or register), ``false`` if field should be displayed but not required .. http:jsonentity:: 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. :jsonparam String field: *(required)* The internal name of the field :jsonparam String label: *(required)* The display name of the field :jsonparam Boolean required: *(required)* Will be ``true`` if this field is required for enrollment (edit or register), ``false`` if field should be displayed but not required .. http:jsonentity:: 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``. :jsonparam String field: *(required)* The internal name of the field :jsonparam String label: *(required)* The display name of the field :jsonparam Boolean required: *(required)* Will be ``true`` if this field is required for enrollment (edit or register), ``false`` if field should be displayed but not required .. http:jsonentity:: 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 :http:jsonentity:`Selection` entries in the ``values`` list. :jsonparam String field: *(required)* The internal name of the field :jsonparam String label: *(required)* The display name of the field :jsonparam Boolean required: *(required)* Will be ``true`` if this field is required for enrollment (edit or register), ``false`` if field should be displayed but not required :jsonparam List[Object] values: *(required)* A list of :http:jsonentity:`Selection` objects. This value submitted for enrollment should be equal to one of the ``code`` values from the ``values`` selection list .. http:jsonentity:: 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 :http:jsonentity:`Selection` entries in the ``values`` list. :jsonparam String field: *(required)* The internal name of the field :jsonparam String label: *(required)* The display name of the field :jsonparam Boolean required: *(required)* Will be ``true`` if this field is required for enrollment (edit or register), ``false`` if field should be displayed but not required :jsonparam Integer minSelect: *(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. :jsonparam Integer maxSelect: *(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``. :jsonparam List[Object] values: *(required)* A list of :http:jsonentity:`Selection` objects. This field's value should be a list of the ``code`` values from the ``values`` selection list .. http:jsonentity:: Selection :jsonparam String code: *(required)* Identifier for the selection, as would be used when submitting this value in an editUser call or the like :jsonparam String label: *(required)* The display name of the selection Get Configured Perks by Perk Type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`anonymous_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query Integer cardTemplateCode: *(required)* Paytronix-assigned card template code identifying the program to enroll the user in. :query String perkType: *(required)* The type of the perk values to return. Example of a successful response: .. FIXME the reply object should be actually documented instead of just exampled here .. code:: javascript { "perksField": { "field": "perks", "label": "Perks", "maxSelect": 1, "minSelect": 1, "required": true, "type": "multi-selection", "values": [ { "attributes": { "daylabel": "Monday", "dayvalue": "2", "hourlabel": "3-5 PM", "hourvalue": "1517", "isActive": "yes", "subtype": "earlybird", "description": "Come in on Monday for an early dinner between 3pm and 5pm", "imageCode": "i/abc", "type": "promo" }, "code": "0", "label": "Early Bird Mon 3-5" }, { "attributes": { "daylabel": "Tuesday", "dayvalue": "3", "hourlabel": "3-5 PM", "hourvalue": "1517", "isActive": "yes", "subtype": "earlybird", "description": "Come in on Tuesday for an early dinner between 3pm and 5pm", "imageCode": "i/def", "type": "promo" }, "code": "1", "label": "Early Bird Tue 3-5" }, { "attributes": { "daylabel": "Monday", "dayvalue": "2", "hourlabel": "8-10 PM", "hourvalue": "2022", "isActive": "yes", "subtype": "latenight", "description": "Come in on Monday for an late dinner between 8pm and 10pm", "imageCode": "i/ghi", "type": "promo" }, "code": "24", "label": "Late Night Mon 8-10" } ] }, "result": "success" } Send Email Verification Challenge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String username: *(required)* The username of the user to verify. :jsonparam String url: *(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: .. FIXME the reply object should be actually documented instead of just exampled here .. code:: javascript { "email": "john.developer@paytronix.com", "result": "success" } Example of a failed response: .. code:: javascript { "email": "john.developer@paytronix.com", "result": "failure", "errorCode": "email_verification.send_failed", "errorMessage": "Unable to send email to the specified address" } Edit Related Guest ~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`oauth_auth` * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam Integer relatedGuestCode: *(required)* Paytronix-assigned code identifying the related guest to be edited. Can be retrieved using the :ref:`guest_service` :jsonparam String username: *(required)* Username of the user to whom the guest is related. To obtain the username given a printed card number, see :ref:`guest_service` :jsonparam Object setRelatedGuestFields: *(required)* Fields to update for the related guest. See :http:jsonentity:`RelatedGuestFieldsInput` below. Example of request: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "username":"someUser" "setRelatedGuestFields":{...} } .. http:response:: success :jsonparam String result: *(required)* ``success`` Example: .. code:: javascript { "result": "success" } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. :jsonparam Map[String,List[Object]] errorsByField: *(required)* Object representing a map of field name to an object of error code/text. See :http:jsonentity:`ValidationError` below. Each field name will be prefixed ``setRelatedGuestFields/``, as these are the only fields in the request subject to this validation logic. See :ref:`enrollment_field_errors`. Add Related Guest ~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`oauth_auth` * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String username: *(required)* Username of the user to whom the guest is related. To obtain the username given a printed card number, see :ref:`guest_service` :jsonparam List[Object] setRelatedGuestFields: *(required)* List of fields to update for the related guest. See :http:jsonentity:`RelatedGuestFieldsInput` below. Example of request: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "username":"someUser" "setRelatedGuestFields":[{...},{...}] } .. http:response:: success :jsonparam String result: *(required)* ``success`` Example: .. code:: javascript { "result": "success" } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. :jsonparam Map[String,List[Object]] errorsByField: *(required)* Object representing a map of field name to an object of error code/text. See :http:jsonentity:`ValidationError` below. Each field name will be prefixed ``setRelatedGuestFields/``, as these are the only fields in the request subject to this validation logic. See :ref:`enrollment_field_errors`. Remove Related Guest ~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`oauth_auth` * :ref:`b2b_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query Integer relatedGuestCode: *(required)* Paytronix-assigned code identifying the related guest to be removed. Can be retrieved using the :ref:`guest_service` :query String username: *(required)* Username of the primary user from whom the related guest will be detached, see :ref:`guest_service` Example of request: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "relatedGuestCode":"1111" "username":"someUser" } .. http:response:: success :jsonparam String result: *(required)* ``result`` :jsonparam RelatedGuest removedGuest: *(required)* The related guest that was deleted is returned. See :http:jsonentity:`RelatedGuest` for the format of this object. Example: .. code:: javascript { "result" : "success" } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Validate Related Guest ~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: enrollment/validateRelatedGuest.json Validates user information for guests. The following authentication methods are supported for this endpoint: * :ref:`oauth_auth` * :ref:`b2b_auth` * :ref:`anonymous_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam Integer relatedGuestCode: *(required)* Paytronix-assigned code identifying the related guest to be edited. Can be retrieved using the :ref:`guest_service` :jsonparam Object setRelatedGuestFields: *(required)* Fields to validate. See :http:jsonentity:`RelatedGuestFieldsInput` below. Example of request: .. code:: javascript { "authentication": "b2b", "merchantId": 123, "username":"someUser" "setRelatedGuestFields":[{...},{...}] } .. http:response:: success :jsonparam String result: *(required)* ``success`` Example: .. code:: javascript { "result": "success" } .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. :jsonparam Map[String,List[Object]] errorsByField: *(required)* Object representing a map of field name to an object of error code/text. See :http:jsonentity:`ValidationError` below. Each field name will be prefixed ``setRelatedGuestFields/``, as these are the only fields in the request subject to this validation logic. See :ref:`enrollment_field_errors`. Complete Email Verification ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String code: *(required)* A code extracted from the URL of the caller (``id``). Example of a successful response: .. FIXME the reply object should be actually documented instead of just exampled here .. code:: javascript { "email": "john.developer@paytronix.com", "result": "success" } Example of a failed response: .. code:: javascript { "email": "john.developer@paytronix.com", "result": "failure", "errorCode": "email_verification.invalid_code", "errorMessage": "Invalid email verification code" } Begin an Automatic Account Combine Workflow ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(required)* Printed card number associated with the account :jsonparam String combineCode: *(required)* Code returned by EnrollmentService during uniqueness conflict :jsonparam String confirmationUrl: *(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 .. http:response:: success :jsonparam String result: *(required)* ``success`` .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Get Candidate Accounts for Automatic Combine ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`anonymous_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :query String combineConfirmationCode: *(required)* A code extracted from the URL of the caller (``id``) .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String maskedCardNumber: *(required)* Masked card number representing the account which will be combined :jsonparam List[Object] accounts: *(required)* Information about the other accounts to which the account can be combined. See :http:jsonentity:`AutoCombineAccountInfo` .. http:response:: failure :jsonparam String result: String *(required)* ``failure`` :jsonparam String errorCode: String *(required)* The error code of the failure. :jsonparam String errorMessage: String *(required)* The (human readable) error message of the failure. .. http:jsonentity:: 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. :jsonparam String maskedCardNumber: *(required)* Masked card number for this account :jsonparam String firstName: *(optional)* First name of the owner of this account :jsonparam String lastName: *(optional)* Last name of the owner of this account :jsonparam Date dateOfBirth: *(optional)* Date of birth of the owner of this account :jsonparam Date lastActivityDate: *(required)* Date of this account's last activity :jsonparam Long accountCode: *(required)* Unique identifier for this account, to be used in :http:post:`enrollment/processAutoCombine.json` Complete an Automatic Combine Workflow ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` * :ref:`anonymous_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String combineConfirmationCode: String *(required)* A code extracted from the URL of the caller (``id``) :jsonparam Long accountCode: Long *(required)* Code representing the account with which the new account will be combined .. http:response:: success :jsonparam String result: *(required)* ``success`` .. http:response:: failure :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. .. http:response:: 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 :jsonparam String result: *(required)* ``accountSuspended`` :jsonparam String errorCode: *(required)* The error code of the failure. :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure. Enroll with Mobile Phone via SMS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http: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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(optional)* If provided the the guest will be enrolled to that card number. Otherwise a new card number will be created for them. :jsonparam String phoneNumber: *(required)* Mobile phone number :jsonparam String activationStoreCode: *(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. .. http:response:: success :jsonparam String result: *(required)* ``success`` :jsonparam String printedCardNumber: *(required)* Printed card number associated with the activated account .. http:response:: failure :jsonparam String result: String *(required)* ``failure`` :jsonparam String errorCode: String *(required)* The error code of the failure. :jsonparam String errorMessage: String *(required)* The (human readable) error message of the failure. Send SMS Enroll text message to with Mobile Phone for an active account ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. http:post:: enrollment/editSmsEnroll.json Send a SMS Enroll text message to a mobile phone number for provided active card number, if 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: * :ref:`b2b_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID to perform the operation in. :jsonparam String printedCardNumber: *(required)* Printed card number associated with the account :jsonparam String phoneNumber: *(required)* Mobile phone number .. http:response:: success :jsonparam String result: *(required)* ``success`` .. http:response:: failure :jsonparam String result: String *(required)* ``failure`` :jsonparam String errorCode: String *(required)* The error code of the failure. :jsonparam String errorMessage: String *(required)* The (human readable) error message of the failure. .. _common_enrollment_response: Common Enrollment Service Response ---------------------------------- These responses are used for many Enrollment Service endpoints, see individual endpoints for which ones use this common format. .. http:response:: success Indicates that the operation succeeded. :jsonparam String result: *(required)* ``success`` :jsonparam Boolean modificationsOccurred: *(required)* Whether or not anything was modified with the enrollment. :jsonparam Object oauthTokens: *(optional)* OAuth tokens to be used to act on behalf of the newly created account. See :http:jsonentity:`TokenResponse` for details :jsonparam Int accountId: *(optional)* The ID of the newly enrolled account. Example: .. code:: javascript { "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" } .. http:response:: cardCreatedSuccess Indicates that the operation succeeded and provides the created card information. :jsonparam String result: *(required)* ``cardCreatedSuccess`` :jsonparam String printedCardNumber: *(required)* Printed card number of the generated card :jsonparam String generatedRegistrationCode: *(optional)* Registration code of the generated card :jsonparam Object oauthTokens: *(optional)* OAuth tokens to be used to act on behalf of the newly created account. See :http:jsonentity:`TokenResponse` for details :jsonparam Int accountId: *(optional)* The ID of the user account related to the card creation. Example: .. code:: javascript { "result": "cardCreatedSuccess", "printedCardNumber": "6000100000001985", "generatedRegistrationCode": "578281", "accountId": "54" } .. http:jsonentity:: TokenResponse :jsonparam String access_token: *(required)* Access token to be used in future requests :jsonparam String token_type: *(required)* Token type is, at present, always ``bearer``. See `OAuth 2.0 Bearer Token documentation `_ for further details :jsonparam Integer expires_in: *(optional)* Time until access token expires :jsonparam String refresh_token: *(required)* Refresh token to be used for future :http:post:`oauth/requestGuestToken.json` calls :jsonparam String scope: *(optional)* Token scope, indicating the sorts of operations which can be performed with the access token :jsonparam String username: *(optional)* Username of the user for which the tokens are valid :jsonparam String printedCardNumber: *(optional)* Printed card number of the account for which the tokens are valid .. _enrollment_uniqueness_conflict: .. http:response:: uniquenessConflict Indicates that the operation was not performed because the uniqueness check found a conflicting user. :jsonparam String result: *(required)* ``uniquenessConflict`` :jsonparam String errorCode: *(required)* The error code of the failure :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure :jsonparam String conflictingField: *(required)* Name of the field which was in conflict :jsonparam Boolean canAutoCombine: *(required)* Boolean value indicating whether or not the new account can be combined to the conflicting account :jsonparam String combineCode: String *(optional)* Code which can be passed to :http:post:`enrollment/initiateAutoCombine.json` to begin the auto-combine process .. code:: javascript { "result": "uniquenessConflict", "conflictingField": "mobilePhone" } .. http:response:: invalidInputs Indicates that the operation was not performed because the inputs could not be validated. :jsonparam String result: *(required)* ``invalidInputs`` :jsonparam String errorCode: *(required)* The error code of the failure :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure :jsonparam Map[String,List[Object]] errorsByField: *(required)* Object representing a map of field name to an object of error code/text. See :http:jsonentity:`ValidationError` below. Each field name is prefixed by either ``setUserFields/`` or ``setAccountFields/`` to indicate where the field was given in the request. See :ref:`enrollment_field_errors`. .. code:: javascript { "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" } ] } } .. http:response:: failure Indicates that the operation did not complete successfully and was rolled back as best as able. Example: :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure .. code:: javascript { "result": "failure", "responseCode": 435, "responseMessage": "Card already active" } Reply Objects ------------- .. http:jsonentity:: RelatedGuest Information about a RelatedGuest :jsonparam Integer relatedGuestCode: *(required)* Paytronix-assigned code identifying the related guest to be edited. Can be retrieved using the :jsonparam String firstName: *(optional)* Guest's first name. Max 30 characters. :jsonparam String lastName: *(optional)* Guest's last name. Max 30 characters. :jsonparam String email: *(optional)* Guest's email address. Max 100 characters. :jsonparam LocalDate dateOfBirth: *(optional)* Related Guests' date of birth in yyyy-mm-dd format. :jsonparam String salutation: *(optional)* Guest’s salutation. Allowed values are “Mr.”, “Ms.”, “Mrs.”, “Dr.”, and “Rev.” .. http:jsonentity:: ValidationError Information about a ValidationError :jsonparam String code: *(required)* Machine-readable error code. See :ref:`enrollment_field_errors`. :jsonparam String text: *(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 | +------------------------------------------------------+----------------------------------------------------------------------------------------+