Action to Load (ATL) Service

The ATL service provide endpoints for creating action to load events and adding guests to them.

Endpoints

Create Action to Load Event

POST actiontoload/actionToLoadEvent.json

Use this endpoint to create ATL events and specify the wallet adjustments that should be made for guests who trigger an action.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • name (String) – (required) The name of the ATL event. Must be <= 100 characters.
  • adjustmentStore (String) – (required) Which store the wallet adjustments for a guest should be attributed to. Can be either the literal string enrollmentStore or a Store object.
  • adjustments (List[Object]) – (required) A non-empty array of wallet adjustments to be made for guests who trigger the event. See ATLAdjustment for details.
  • startDatetime (String) – (optional) Datetime in the format YYYY-MM-DDTHH:mm:ss in US Eastern time for when this event should start responding to triggering actions. Must be in the future. Defaults to the current time.
  • endDatetime (String) – (optional) Datetime in the format YYYY-MM-DDTHH:mm:ss in US Eastern time for when this event should stop responding to triggering actions. If supplied, must be after startDatetime. Defaults to never.
  • eventTrigger (String) – (required) What will cause this event to trigger adjustments. One of clickOnly, actionOnly, or clickOrAction.

Example:

{
        "merchantId": 5555,
        "name": "ATLEvent_AlphaBravoCharlie",
        "adjustmentStore":"enrollmentStore",
        "adjustments":[
                {
                        "walletCode":45,
                        "amount":1
                }
        ],
        "startDatetime":"2025-01-15T13:00:00",
        "endDatetime":"2025-01-31T23:59:59",
        "eventTrigger":"actionOnly"

}
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • eventCode (String) – (required) The code of the newly created ATL event.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) One of system_error, invalid_request, or atl_disabled if your merchant does not have the action to load feature enabled.
  • errorMessage (String) – (required) Additional content for humans that might help diagnose the problem.

Add Guests to an Event

POST actiontoload/actionToLoadEventGuest.json

Use this endpoint to add guests to an ATL event. Only guests added to an event will have adjustments applied when an action is triggered.

The following authentication methods are allowed for this endpoint:

JSON Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant ID to perform the operation in.
  • atlEventCode (String) – (required) The code of the ATL event to add guests to, as returned by POST actiontoload/actionToLoadEvent.json.
  • guests – (required) A non-empty group of guests to add to the event. Limited to 10,000 per request. See GuestIds for details.

Example:

{
        "merchantId": 5555,
        "atlEventCode":"ATL API wK11QDQpZOWv14xb2hZL",
        "guests":{
                "printedCardNumbers":[
                        "9990318272",
                        "235726255334353",
                        "9990340383"
                ]
        }

}
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • invalids (List[Object]) – (required) An array of guests that could not be added to the event and the reasons why. Any guests not present in this response were added successfully. The guests will be specified by either account id or printed card number, depending on which was used to make the request. See InvalidGuests for details.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) Either system_error, invalid_request, or atl_disabled if your merchant does not have the action to load feature enabled.
  • errorMessage (String) – (required) Additional content for humans that might help diagnose the problem.

Request Objects

Store
JSON Parameters:
 
  • storeCode (String) – (required)
ATLAdjustment
JSON Parameters:
 
  • walletCode (Int) – (required) Code of the wallet to adjust. Must be attached to the account being adjusted - it’s not created if it doesn’t exist.
  • amount (BigDecimal) – (required) How much to adjust the wallet by.
GuestIds

Either printedCardNumbers or accountIds must be present, but not both.

JSON Parameters:
 
  • printedCardNumbers (List[String]) – (optional)
  • accountIds (List[Int]) – (optional)

Response Objects

InvalidGuests

Each InvalidGuest object describes why the cards/accounts could not be added and contains a list of GuestIds that failed for that reason.

Possible invalid reasons are one of: duplicates dontExist inactiveAccounts inactiveCards alreadyLoaded atlIneligible

{
             "result": "success",
             "invalids": [
                     {
                             "dontExist": {
                                     "printedCardNumbers": [
                                             "235726255334353"
                                     ]
                             }
                     },
                     {
                             "atlIneligible": {
                                     "printedCardNumbers": [
                                             "9990318272",
                                             "9990340383"
                                     ]
                             }
                     }
             ]
}