Registration¶

Overview¶

Registration is an essential part of many mobile apps. Many merchants issue and activate cards at a physical store - this “turns on” the card and enables it to accrue points and participate in loyalty programs. However the card is not considered registered until essential guest demographic information is uploaded to Paytronix. Registration comes with a variety of benefits that Paytronix will perform behind the scenes, including special rewards, birthday emails, and other promotions. There are several ways to for a guest to register via REST. The most common methods are:

createAndRegister: This call both creates a new card number and registers it using the provided guest information. It should be used only if the guest does not already have a physical card. The new card number will be returned
register: If the guest has already obtained a physical card, this call will register the card number specified using the provided guest information. Some physical cards also contain a short security registration code printed on the back of the card. If this is the case, both the card number and the registration code must first be verified via the below flow. If the card does not have a registration code, only the card number needs to be verified.

Authentication¶

createAndRegister: This particular endpoint only supports an authentication type of anonymous.
register: The register endpoint may utilize one of three different types of authentication: OAuth, card, and B2B. Paytronix typically recommends using “OAuth” as it offers the greatest authentication flexibility and accommodates both cards with and without registration codes. “Card” authentication may be used only if the integrator is absolutely certain that the physical cards will never utilize a registration code.

Flow¶

To register a guest who does not have a card number:¶

The integration obtains a list of required registration fields by calling the endpoint enrollmentConfig. Paytronix will return a list of required and optional fields, along with min/max lengths and formatting requirements.
The integration should display the fields supplied in step 1.
The integration sends a createAndRegister call using the guest’s registration input.
The Paytronix system will return a result of success or failure.
1. If the result is a success, Paytronix will return a newly created card number and an access token, which may then be used to authenticate functionality such as account balance and user information. A success message and/or the card number should be displayed to the guest.
2. If the result is a failure, an error should be provided to the guest. Paytronix will include additional information regarding why the message failed. This might be a critical or formatting failure, or a validation error with a supplied field. In the case of the latter, an errorsByField object will be provided with the problematic field. If the problem is field-related, the guest should be prompted to correct the problem field and resubmit the form. The flow then repeats from step 3.

To register a guest who does have a card number:¶

The guest supplies a printed card number and a registration code if one exists.
If using oauth authentication, the integration authenticates the information in step 1 by following the Guest Website Login flow. Paytronix returns an access token after a successful authentication. Please note that this step may also occur after step 4, depending on the desired page flow.
The integration obtains a list of required registration fields by calling the endpoint enrollmentConfig. Paytronix will return a list of required and optional fields, along with min/max lengths and formatting requirements.
The integration should display the fields supplied in step 3.
The integration sends a register call using the guest’s registration input, as well as the access token from step 2 if oauth authentication is used.
The Paytronix system will return a result of success or failure.
1. If the result is a success, a message should be displayed to the guest.
2. If the result is a failure, an error should be provided to the guest. Paytronix will include additional information regarding why the message failed. This might be a critical or formatting failure, or a validation error with a supplied field. In the case of the latter, an errorsByField object will be provided with the problematic field. If the problem is field-related, the guest should be prompted to correct the problem field and resubmit the form. The flow then repeats from step 5.

Example¶

createAndRegister¶

Request Body

{
  "authentication": "anonymous",
  "client_id": "3FTmkQuXBnotarealcklientIDFCO9PREEnj_WHaK",
  "client_secret": "654secretnx4",
  "merchantId": 777777,
  "cardTemplateCode": 0,
  "enforceUniqueFields": [
        "mobilePhone"
  ],
  "setUserFields": {
        "style": "typed",
        "username": [
          "john.doe"
        ],
        "password": [
          "open123"
        ],
        "mobilePhone": [
          "7894563210"
        ]
  },
  "setAccountFields": {
        "style": "typed",
        "favoriteStore": [
          {
                "code": "123"
          }
        ]
  }
}

Response

{
  "result": "cardCreatedSuccess",
  "generatedRegistrationCode": "123456",
  "oauthTokens": {
        "access_token": "rIe7dgL5pthisisnotarealtokenqrFbA268pw5GP",
        "expires_in": 1800,
        "printedCardNumber": "9990000003239",
        "refresh_token": "PvOuthisisnotarealrefreshtokenN45TV4kGq",
        "scope": "account_read account_write user_read user_write",
        "token_type": "bearer",
        "username": "john.doe"
  },
  "printedCardNumber": "9990000012345"
}

register¶

Request Body

{
  "authentication": "oauth",
  "client_id": "3FTmkQuXBnotarealcklientIDFCO9PREEnj_WHaK",
  "client_secret": "654fs@mnx4",
  "access_token": "rIe7dgL5pthisisnotarealtokenqrFbA268pw5GP",
  "merchantId": 777777,
  "printedCardNumber": "600030100041234455",
  "enforceUniqueFields": [
        "mobilePhone",
        "email"
  ],
  "setUserFields": {
        "style": "typed",
        "username": [
          "john.doe"
        ],
        "password": [
          "open123"
        ],
        "mobilePhone": [
          "7894563210"
        ]
  },
  "setAccountFields": {
        "style": "typed",
        "favoriteStore": [
          {
                "code": "123"
          }
        ]
  }
}

Response

{
  "result": "success",
  "oauthTokens": {
        "access_token": "rIe7dgL5pthisisnotarealtokenqrFbA268pw5GP",
        "expires_in": 1800,
        "printedCardNumber": "600030100041234455",
        "refresh_token": "PvOuthisisnotarealrefreshtokenN45TV4kGq",
        "scope": "account_read account_write user_read user_write",
        "token_type": "bearer",
        "username": "john.doe"
  }
}

API Reference¶

Please see the following API reference page for more technical details: Enrollment Service