FACTOR4

Transaction REST API

Date: 19-Aug-2022

Version 2022.19.01

http://restapi.factor4gift.com/


Contents

Standard Header        4

Endpoints        5

1.1 Gift Issuance        5

1.1.1 Description        5

1.1.2 Route        6

1.1.3 Sample JSON        6

1.1.4 Parameters        7

1.2 Gift Redemption        15

1.2.1 Description        15

1.2.2 Route        15

1.2.3 Sample JSON Request        16

1.2.3 Parameters        17

1.2.5 Output        21

1.3 Inquiry        21

1.3.1 Description        22

1.3.2 Route        22

1.3.3 Sample JSON        22

1.3.4 Parameters        23

1.4 Loyalty Issuance        28

1.4.1 Description        28

1.4.2 Route        28

1.4.3 Sample JSON Request        28

1.4.4 Parameters        30

1.5 Loyalty Redemption        33

1.5.1 Description        33

1.5.2 Route        33

1.5.3 Sample JSON Request        34

1.5.4 Parameters        35

1.6 Tip        38

1.6.1 Description        38

1.6.2 Route        39

1.6.3 Sample JSON Request        39

1.6.4 Parameters        40

1.7 Void Transaction        42

1.7.1 Description        42

1.7.2 Route        43

1.7.3 Sample JSON Request        43

1.7.4 Parameters        44


Standard Header

The RequestStandardHeaderComponent must exist in every request message sent to the Transaction API.

StandardHeader Request Parameters

Parameter

Required

Description

Data Type

Constraints

systemId

Yes

installation specific system_id

String

clientId

Yes

external_id of the client

String

Length: 1-12

locationId

Yes

id_pos of the location

String

Length: 1-12

terminalId

Yes

id_pos of the terminal

String

Length: 1-12

terminalDateTime

No

date time of the requesting terminal. (YYYYMMDD or

YYYYMMDDHHMMSS)

String

Length: 8 or

14

requestId

No

rolling counter to authenticate

request, reconcile transactions, and

identify duplicate request. It is a

base-36 encoded number that ranges

from "0" to "ZZZZZZ".

String

Alphanumeric

Length: 0-64

localeId

No

localization id, It is not required and will default to the host settings if it is

not set

String

[A-Z]

Length: 0-2

initiatorType

No

(E)mployee, Client (U)ser, Account-holding (C)customer

String

[E,U,C]
Length: 0-1

initiatorId

No

Employee id_pos, User Id, Customer Id

String

Alphanumeric

Length: 0-10

initiatorPassword

No

Employee password_pos, User

Password, Customer Password

String

Length: 0-10

externalId

No

Id from integrated POS system

String

Alphanumeric

Length: 0-25

batchId

No

The terminal's batch, may be used to search

Integer

Length: 0-6

batchReferenceId

No

The terminal's id within the batch, may be used to search.

Integer

Length: 0-6

channel

No

The originating channel of the request

String

Length:

0-256

subChannel

No

The originating sub channel of the request

String

Length:

0-256

Endpoints

Format for the endpoint documentation:

1.1 Gift Issuance

1.1.1 Description

Gift Issuance adds currency value to an account. If the card is in inventory (new or recycled)

then it will activate the card and add a new account. When the value is added from a location

with a group-specific balance then the value will be added to the group-specific balance. (See

Multi-purse Inquiry Story for an example of the result.)

Features:

1) Activate an existing Card

Include the card number to be activated as accountId, and set the activating flag to 'Y'

2) Issue a specific currency value to an Account

Include the Amount element with the valueCode and amount to issue value

3) Issue a default currency value to an Account

Include the Amount element with the valueCode not set - system will default to location's

currency type

4) Update customer demographics.

Provide any changes to customer demographics in the customerInfo element

1.1.2 Route

Relative route: /v4/rest/giftissuance

HTTP verb: POST

Body type: JSON

1.1.3 Sample JSON

Request JSON

{

    "standardHeader": {

        "requestId""1",

        "localeId"null,

        "systemId""SB"

        "clientId""999",

        "locationId""171162",

        "terminalId""2",

        "terminalDateTime"null,

        "initiatorType""E",

        "initiatorId""1000",

        "initiatorPassword""1234",

        "externalId"null,

        "batchId"null,

        "batchReference"null,

        "channel""SMS",

        "subChannel""Twilio",

    },

    "account": {

        "programId"null,

        "accountId""918261733872916",

        "pin""231514",

        "entryType""K"

    },

    "activating""Y",

    "amount": {

        "valueCode""USD",

        "enteredAmount""1.00",

        "nsfAllowed""N"

    },

    "questionsAndAnswers"null// 0 to 5 repetitions

    "customerInfo": {

        "customerType""1",

        "firstName""Jon"

        "middleName""Mid",

        "lastName""Doe"

        "address1"null,

        "address2"null

        "city"null,

        "state"null

        "postal"null,

        "country"null

        "mailPref"null,

        "phone"null

        "isMobile"null,

        "phonePref"null

        "email"null,

        "emailPref"null

        "birthday"null,

        "anniversary"null

        "gender"null

    }

}

1.1.4 Parameters

Request Parameters

Parameter 

Required 

Description 

Data 

Type

Special Format 

Length

standardHeader 

Yes 

see details on 

standardHeader 

parameters

Account

entryType 

Yes 

entry method for the account id: 

(B)arcode, (K)eyed, (M)agnetic, 

(P)roximity

String 

[B,K,M,P] 

1

accountId 

Yes 

Account identifier 

String 

Alphanumeric 

0-60

accountIdType 

No 

the account 

identifier type 

entered: Card, 

Phone, 

PaymentCardToken, Email

String 

[Card, Phone, 

PaymentCardToken, Email]

accountIdSuffix 

No 

last 4 digits of a 

Payment Card - 

applies only for 

accountIdType: 

PaymentCardToken

Integer 

Numeric 

4

pin 

No 

pin number of the account or card

Integer 

Numeric 

0-6

programId 

No 

id of the program the account belongs to, used when 

referencing account by external id

Integer 

Numeric 

0-9

amount

enteredAmount 

No 

the amount of the transaction

Decimal 

Decimal 

0-11

valueCode 

No 

the value code for entered amount

String 

Alphanumeric 

1-10

tenderType 

No 

Description of they type of tender used for the transaction

String 

Alphanumeric 

0-256

nsfAllowed 

No 

boolean to allow 

transactions where the account has an insufficient balance to proceed: Y/N

String 

[Y,N] 

1

activating 

No 

A flag used to 

determine if the 

transaction should activate the 

account: Y/N

String 

[Y,N] 

1

promotionCodes 

Array of 

promotionCode 

elements (0-50)

Array

promotionCode

code 

No 

the promo code to be issued/redeemed

String

quantity 

No 

quantity value 

associated with 

promotionCode

Integer 

Numeric

nsfAllowed 

No 

boolean to allow 

transactions where the account has an insufficient balance to proceed: Y/N

String 

[Y,N] 

1

activating 

No 

A flag used to 

determine if the 

transaction should activate the 

account: Y/N

String 

[Y,N] 

1

promotionCodes 

Array of 

promotionCode 

elements (0-50)

Array

promotionCode

code 

No 

the promo code to be issued/redeemed

String

quantity 

No 

quantity value 

associated with 

promotionCode

Integer 

Numeric

redeem 

No 

flag for issuing 

(false), or 

redeeming (true) a promo code for a transaction

Boolean 

[true, false]

questionAndAnswers 

Array of 

questionAndAnswer elements (0-5)

Array

questionAndAnswer

code 

No 

the code of the 

question to be 

answered

String

answer 

No 

the answer to the question

String

customerInfo

customerType 

No 

(1) Primary account holder, (2) Alternate, (G)iver of card

String 

0-1

firstName 

No 

customer first name 

String 

0-35

middleName 

No 

customer middle 

name

String 

0-35

lastName 

No 

customer last name 

String 

0-35

address1 

No 

customer address line 1

String 

0-100

address2 

No 

customer address line 2

String 

0-100

city 

No 

customer city 

String 

0-75

state 

No 

customer state 

String 

0-75

postal 

No 

customer postal 

code - must be valid

String

country 

No 

customer country - 2 character ISO 

3166-1 Country 

code

String 

2 character ISO 

3166-1 Country 

code

0,2

mailPref 

No 

flag for identifying customer preference for receiving mail: Opt (I)n, Opt (O)ut

String 

[I,O] 

0-1

phone 

No 

customer phone 

number - Preferred format "+CCC AAA LLL LLLL xEEEE" -  see account 

identifiers for more information

String 

0-23

isMobile 

No 

flag for identifying if the phone is a 

mobile number: Y/N

String 

[Y,N] 

0-1

phonePref 

No 

flag for identifying customer preference being contacted via phone: Opt (I)n, Opt (O)ut

String 

[I,O] 

0-1

email 

No 

customer email 

address - see 

account identifiers for more 

information

String 

0-320

emailPref 

No 

flag for identifying customer preference being contacted via email: Opt (I)n, Opt (O)ut

String 

[I,O] 

0-1

birthday 

No 

customer birthday: YYYYMMDD

Dat 

YYYYMMDD 

0,8

anniversary 

No 

customer 

anniversary: 

YYYYMMDD

Date 

YYYYMMDD 

0,8

gender 

No 

customer gender: M/F

String 

[M,F] 

0-1

Response Parameters

NOTE: All parameters may not be present - response parameters are dependent on Program configuration and Request values provided

Parameter 

Description 

Data 

Type

Length

standardHeader 

requestId 

Id of the request that caused yielded the response

String 

1-64

status 

(A)pproved, (D)uplicate and (E)rror 

String 

1

identification

transactionId 

Id of transaction that just occurred, can be used to search

String

approvalCode 

Approval code of transaction that just occurred, can be used to search

String 

1-6

demonstration 

flag indicating a demonstration location

expirationDate 

Date account used in transaction expires (YYYYMMDD)

Date 

8

balances 

an array of balance elements 

Array

balance

valueCode 

the value code associated to the balance

String

amount 

the balance amount 

Decimal

difference 

the difference in amount of the balance prior to the transaction

Decimal

exchangeRate 

the exchange rate of the balance associated to the value code

Decimal

promotions 

Array of promotion elements

promotion

code 

the code associated to the promo 

String

name 

the name of the promotion 

String

description 

the description of the promotion 

String

type 

the configured type of the promotion 

String

 promotionCodeAssignments 

Array of promotionCodeAssignment elements (0-50)

Array

 promotionCodeAssignment

code 

the promo code to be 

issued/redeemed

String

name 

the name of the promo 

String

description 

the description of the promo 

String

externalId 

the external_id of the promo 

String

classification 

the classification of the promo 

String

earnedOn 

the date the promoCodeAssignment was earned

Date

expiresOn 

the date the promoCodeAssignment expires

Date

event 

the event that took place during the transaction; (E)arned, (R)edeemed, (ER) Earned and Redeemed, (V)oided

[E/R/ER/V]

seen 

a flag indicating if the 

promoCodeAssignment had been in present in a previous transaction response; 'Y' indicates the 

promoCodeAssignment had been in a previous transaction response, 'N' indicates the present response is the first transaction response the 

promoCodeAssignment has been displayed

[Y,N]

customerInfo

customerType 

(1) Primary account holder, (2) 

Alternate, (G)iver of card

String

firstName 

customer first name 

String

middleName 

customer middle name 

String

lastName 

customer last name 

String

address1 

customer address line 1 

String

address2 

customer address line 2 

String

city 

customer city 

String

state 

customer state 

String

postal 

customer postal code 

String

country 

customer country - 2 character ISO 3166-1 Country code

String

mailPref 

flag for identifying customer preference for receiving mail: Opt (I)n, Opt (O)ut

String

phone 

customer phone number - Preferred format "+CCC AAA LLL LLLL xEEEE"  - see account identifiers for more information

String

isMobile 

flag for identifying if the phone is a mobile number: Y/N

String

phonePref 

flag for identifying customer preference being contacted via phone: Opt (I)n, Opt (O)ut

String

email 

customer email address - see account identifiers for more information

String

emailPref 

flag for identifying customer preference being contacted via email: Opt (I)n, Opt (O)ut

String

birthday 

customer birthday: YYYYMMDD 

Date

anniversary 

customer anniversary: YYYYMMDD 

Date

gender 

customer gender: M/F 

String

accessCode 

6 digit access code used for non-POS authentication

Integer 

6

hostMessage 

A dynamic, printable message from the host

printCode 

A list of codes that can correspond to additional printable data.

1.2 Gift Redemption

1.2.1 Description

Gift Redemption subtracts currency value from an account. Program settings determine how request amounts totaling more than the total (available) balance should be handled. Options include: not redeeming any balance and instead returning a "Non-Sufficient Funds" message, redeeming entire balance along with an additional total to be collected via another source of payment, granting loyalty points for the entire purchase, and granting loyalty points for just the portion of the requested amount beyond the available redeemable balance.

1.2.2 Route

Relative route: /v4/rest/giftredemption

HTTP verb: POST

Body type: JSON

1.2.3 Sample JSON Request

{

    "standardHeader": {

        "requestId""1",

        "localeId"null,

        "systemId""SB"

        "clientId""999",

        "locationId""171162",

        "terminalId""2",

        "terminalDateTime"null,

        "initiatorType""E",

        "initiatorId""1000",

        "initiatorPassword""1234",

        "externalId"null,

        "batchId"null,

        "batchReference"null,

        "channel""SMS",

        "subChannel""Twilio"

    },

    "account": {

        "programId"null,

        "accountId""918261733872916",

        "pin""930728",

        "entryType""K"

    },

    "activating"null,

    "amount": {

        "valueCode""USD",

        "enteredAmount""1",

        "nsfAllowed"null

    },

    "includeTip"null,

    "cashOut""N",

    "promotionCodes"null// 0 to 50 repetitions

    "questionsAndAnswers"null// 0 to 5 repetitions

    "customerInfo": {

        "customerType"null,

        "firstName"null

        "middleName"null,

        "lastName"null

        "address1"null,

        "address2"null

        "city"null,

        "state"null

        "postal"null,

        "country"null

        "mailPref"null,

        "phone"null

        "isMobile"null,

        "phonePref"null

        "email"null,

        "emailPref"null

        "birthday"null,

        "anniversary"null

        "gender"null

    }

}

1.2.3 Parameters

Required

Field Name 

Description 

Data 

Type

Length

requestId 

rolling counter to authenticate request, reconcile transactions, and identify duplicate request.

Alphanumeric 

0-64

systemId 

always "SB"

clientId 

id of the client (ISO) 

Alphanumeric 

1-12

locationId 

id of the merchant location 

Alphanumeric 

1-12

terminalId 

id of the terminal 

Alphanumeric 

1-12

accountId 

Account Id or Scan 

Printable 

character

0-60

entryType 

(B)arcode, (K)eyed, (M)agnetic, (P)roximity 

1

valueCode 

ISO 4217 currency id or a group-specific code 

Alphanumeric 

1-10

Optional

Parameter 

Description 

Data 

Type

Length

localeId 

locale id is the localization id. It is not required and will default to the host settings if it is not set

Alphanumeric 

0-2

terminalDateTime 

The date and time of the 

terminal: YYYYMMDD or 

YYYYMMDDHHMMSS

YYYYMMDD[HHMMSS] 

8 or 14

initiatorType 

(E)mployee, Client (U)ser, Account-holding (C)customer

Alphanumeric 

1

initiatorId 

Employee, User/Customer Id 

Alphanumeric 

0-10

initiatorPassword 

Employee, User/Customer Password

Numeric 

0-10

externalId 

Id from integrated POS system 

Alphanumeric 

0-25

batchId 

The terminal's batch, may be used to search

Numeric 

0-6

batchReference 

The terminal's id within the batch, may be used to search

Numeric 

0-6

channel 

Alphanumeric 

0-255

subChannel 

Alphanumeric 

0-255

programId 

id of the program the account belongs to, used when 

referencing account by external id

Numeric 

0-9

pin 

Account Id's pin 

Numeric 

0-6

activating 

A flag used to determine if the transaction should activate the account. Valid values for this flag are Y and N. If these is not set the default behavior will be used.

1

enteredAmount 

purchase amount: may include up to 2 decimal places

Decimal 

0-11

nsfAllowed 

Non sufficient funds Y or N 

1

includeTip 

The amount of the value 

redeemed that should be 

included as a tip

Decimal

cashOut 

A flag used to determine if the transaction should redeem all cash from the account. Valid values for this flag are Y and N.

1

promotionCodes 

array of promotionCode (0-50 repetitions, each promoCode has code and quantity 

parameter)

questionsAndAnswers 

array of questionAndAnswer (0-5 repetitions, each 

questionAndAnswer has code and answer parameter)

customerType 

(1) Primary account holder, (2) Alternate, (G)iver of card

Alphanumeric 

0-1

firstName 

May be up to 35 characters long

Alphanumeric 

0-35

middleName 

May be up to 35 characters long

Alphanumeric 

0-35

lastName 

May be up to 35 characters long

Alphanumeric 

0-35

address1 

May be up to 100 characters long

Alphanumeric 

0-100

address2 

May be up to 100 characters long

Alphanumeric 

0-100

city 

May be up to 75 characters long

Alphanumeric 

0-75

state 

May be up to 75 characters long

Alphanumeric 

0-75

postal

Must be valid

Alphanumeric 

country 

The 2 character ISO 3166-1 Country code

Alphanumeric 

0-2

mailPref 

Opt (I)n, Opt (O)ut

Alphanumeric 

0-1

phone 

Preferred format "+CCC AAA LLL LLLL xEEEE"

Alphanumeric 

0-23

isMobile 

Phone number is mobile? Y, N or empty

Alphanumeric 

0-1

phonePref 

Opt (I)n, Opt (O)ut

Alphanumeric 

0-1

email 

May be up to 320 characters long

Alphanumeric 

0-320

emailPref 

Opt (I)n, Opt (O)ut

Alphanumeric 

0-1

birthday 

YYYYMMDD 

Date

0-8

anniversary 

YYYYMMDD 

Date

0-8

gender 

M, F 

Alphanumeric 

0-1

1.2.5 Output

Field Name

Description 

Data 

Type

Length

requestId 

Id of the request that caused yielded the response

Alphanumeric

0-64

status 

(A)pproved, (D)uplicate and (E)rror 

1

transactionId 

Id of transaction that just occurred, can be used to search

Numeric

1-10

approvalCode 

Approval code of transaction that just occurred, can be used to search

Numeric

1-6

expirationDate 

Date account used in transaction expires (YYYYMMDD)

Numeric

8

balances 

array of balance elements, each

containing valueCode, amount,

difference and exchangeRate

  promotionCodeAssignments 

array of promo code assignment

elements, each containing code,

name, description, externalId,

classification, earnedOn,

expiresOn, event and seen

customerInfo

  demographics of the customer linked to
 the account

hostMessage 

A dynamic, printable message from the host

printCode 

A list of codes that can correspond to additional printable data.

1.3 Inquiry

1.3.1 Description

The Inquiry transaction is designed to provide information about an account including the

balances, promoCodeAssignments, customerInfo, promotions. Inquiry does not alter

balances or promoCodeAssignments.

1.3.2 Route

Relative route: /v4/rest/inquiry

HTTP verb: POST

Body type: JSON

1.3.3 Sample JSON

Request JSON

{

    "standardHeader": {

        "requestId""1",

        "localeId"null,

        "systemId""SB"

        "clientId""999",

        "locationId""171162",

        "terminalId""2",

        "terminalDateTime"null,

        "initiatorType""E",

        "initiatorId""1000",

        "initiatorPassword""1234",

        "externalId"null,

        "batchId"null,

        "batchReference"null,

        "channel""SMS",

        "subChannel""Twilio",

    },

    "account": {

        "programId"null,

        "accountId""918261712396546",

        "pin""930728",

        "entryType""K"

    },

    "questionsAndAnswers"null// 0 to 5 repetitions

}

1.3.4 Parameters

Request Parameters

Parameter 

Required 

Description 

Data 

Type

Special Format 

Length

Inquiry

standardHeader 

Yes 

see details on 

standardHeader 

parameters

account

entryType 

Yes 

entry method for the account id: 

(B)arcode, (K)eyed, (M)agnetic, 

(P)roximity

String 

[B,K,M,P] 

1

accountId 

Yes 

Account identifier 

String 

Alphanumeric 

0-60

accountIdType 

No 

the account 

identifier type 

entered: Card, 

Phone, 

PaymentCardToken, Email

String 

[Card, Phone, 

PaymentCardToken, Email]

accountIdSuffix 

No 

last 4 digits of a 

Payment Card - 

applies only for 

accountIdType: 

PaymentCardToken

Integer 

Numeric 

4

pin 

No 

pin number of the account or card

Integer 

Numeric 

0-6

programId 

No 

id of the program the account belongs to, used when 

referencing account by external id

Integer 

Numeric 

0-9

questionAndAnswers 

Array of 

questionAndAnswer elements (0-5)

Array

questionAndAnswer

code 

No 

the code of the 

question to be 

answered

String

answer 

No 

the answer to the question

String

Response Parameters

NOTE: All parameters may not be present - response parameters are dependent on Program configuration and Request values provided

Parameter 

Description 

Data 

Type

Length

InquiryResponse

standardHeader 

requestId 

Id of the request that caused yielded the response

String 

1-64

status 

(A)pproved, (D)uplicate and (E)rror 

String 

1

identification

transactionId 

Id of transaction that just occurred, can be used to search

String

approvalCode 

Approval code of transaction that just occurred, can be used to search

String 

1-6

demonstration 

flag indicating a demonstration location

expirationDate 

Date account used in transaction expires (YYYYMMDD)

Date 

8

balances 

an array of balance elements 

Array

balance

valueCode 

the value code associated to the balance

String

amount 

the balance amount 

Decimal

difference 

the difference in amount of the balance prior to the transaction

Decimal

exchangeRate 

the exchange rate of the balance associated to the value code

Decimal

promotions 

Array of promotion elements

promotion

code 

the code associated to the promo 

String

name 

the name of the promotion 

String

description 

the description of the promotion 

String

type 

the configured type of the promotion 

String

 promotionCodeAssignments 

Array of promotionCodeAssignment elements (0-50)

Array

 promotionCodeAssignment

code 

the promo code to be 

issued/redeemed

String

name 

the name of the promo 

String

description 

the description of the promo 

String

externalId 

the external_id of the promo 

String

classification 

the classification of the promo 

String

earnedOn 

the date the promoCodeAssignment was earned

Date

expiresOn 

the date the promoCodeAssignment expires

Date

event 

the event that took place during the transaction; (E)arned, (R)edeemed, (ER) Earned and Redeemed, (V)oided

[E/R/ER/V]

seen 

a flag indicating if the 

promoCodeAssignment had been in present in a previous transaction response; 'Y' indicates the 

promoCodeAssignment had been in a previous transaction response, 'N' indicates the present response is the first transaction response the 

promoCodeAssignment has been displayed

[Y,N]

customerInfo

customerType 

(1) Primary account holder, (2) 

Alternate, (G)iver of card

String

firstName 

customer first name 

String

middleName 

customer middle name 

String

lastName 

customer last name 

String

address1 

customer address line 1 

String

address2 

customer address line 2 

String

city 

customer city 

String

state 

customer state 

String

postal 

customer postal code 

String

country 

customer country - 2 character ISO 3166-1 Country code

String

mailPref 

flag for identifying customer preference for receiving mail: Opt (I)n, Opt (O)ut

String

phone 

customer phone number - Preferred format "+CCC AAA LLL LLLL xEEEE"  - see account identifiers for more information

String

isMobile 

flag for identifying if the phone is a mobile number: Y/N

String

phonePref 

flag for identifying customer preference being contacted via phone: Opt (I)n, Opt (O)ut

String

email 

customer email address - see account identifiers for more information

String

emailPref 

flag for identifying customer preference being contacted via email: Opt (I)n, Opt (O)ut

String

birthday 

customer birthday: YYYYMMDD 

Date

anniversary 

customer anniversary: YYYYMMDD 

Date

gender 

customer gender: M/F 

String

accessCode 

6 digit access code used for non-POS authentication

Integer 

6

hostMessage 

A dynamic, printable message from the host

printCode 

A list of codes that can correspond to additional printable data.

1.4 Loyalty Issuance

1.4.1 Description

The Loyalty Issuance transaction adds loyalty value to an account. If the card is in inventory

(new or recycled) then it will be activated and a new account added. Loyalty value is typically in

the form of points (generic placeholder). Punches (visit or purchase counters) or special

promotional balances (virtual coupons, vouchers, etc.) may also be added via promo codes.

The server (host) side determines how the amount entered and promo codes are interpreted.

Currency symbols should not appear on the input amount since it may not represent a purchase

amount. The value code sent should always be "Points".

1.4.2 Route

Relative route: /v4/rest/loyaltyissuance

HTTP verb: POST

Body type: JSON

1.4.3 Sample JSON Request

Request JSON

{

    "standardHeader": {

        "requestId""1",

        "localeId"null,

        "systemId""SB"

        "clientId""999",

        "locationId""171162",

        "terminalId""2",

        "terminalDateTime"null,

        "initiatorType""E",

        "initiatorId""1000",

        "initiatorPassword""1234",

        "externalId"null,

        "batchId"null,

        "batchReference"null,

        "channel""SMS",

        "subChannel""Twilio",

    },

    "account": {

        "programId"null,

        "accountId""918261735748234",

        "pin""821886",

        "entryType""K"

    },

    "activating"null,

    "amount": {

        "valueCode""Points",

        "enteredAmount""15",

        "nsfAllowed"null

    },

    "promotionCodes"null// 0 to 50 repetitions

    "questionsAndAnswers"null// 0 to 5 repetitions

    "customerInfo": {

        "customerType""1",

        "firstName""Ricky"

        "middleName"null,

        "lastName"null

        "address1"null,

        "address2"null

        "city"null,

        "state"null

        "postal"null,

        "country"null

        "mailPref"null,

        "phone"null

        "isMobile"null,

        "phonePref"null

        "email"null,

        "emailPref"null

        "birthday"null,

        "anniversary"null

        "gender"null

    }

}

1.4.4 Parameters

Required

Field Name 

Description 

requestId 

rolling counter to authenticate request, reconcile transactions, and identify duplicate request. It is an alphanumeric string up to 64 characters long.

systemId 

always "SB"

clientId 

id of the client (ISO) 

locationId 

id of the merchant location 

terminalId 

id of the terminal 

accountId 

Account Id or Scan 

entryType 

(B)arcode, (K)eyed, (M)agnetic, (P)roximity 

valueCode 

ISO 4217 currency id or a group-specific code (always "Points" for this transaction)

Optional

Parameter 

Description 

localeId 

locale id is the localization id. It is not required and will default to the host settings if it is not set

terminalDateTime 

The date and time of the terminal: YYYYMMDD or YYYYMMDDHHMMSS

initiatorType 

(E)mployee, Client (U)ser, Account-holding (C)customer

initiatorId 

Employee, User/Customer Id 

initiatorPassword 

Employee, User/Customer Password

externalId 

Id from integrated POS system 

batchId 

The terminal's batch, may be used to search

batchReference 

The terminal's id within the batch, may be used to search

channel 

subChannel 

programId 

id of the program the account belongs to, used when referencing account by external id

pin 

Account Id's pin 

activating 

A flag used to determine if the transaction should activate the account. Valid values for this flag are Y and N. If these is not set the default behavior will be used.

enteredAmount 

purchase amount: may include up to 2 decimal places

nsfAllowed 

Non sufficient funds Y or N 

promotionCodes 

array of promotionCode (0-50 repetitions, each promoCode has code and quantity parameter)

questionsAndAnswers 

array of questionAndAnswer (0-5 repetitions, each 

questionAndAnswer has code and answer parameter)

customerType 

(1) Primary account holder, (2) Alternate, (G)iver of card

firstName 

May be up to 35 characters long

middleName 

May be up to 35 characters long

lastName 

May be up to 35 characters long

address1 

May be up to 100 characters long

address2 

May be up to 100 characters long

city 

May be up to 75 characters long

state 

May be up to 75 characters long

postal

Must be valid

country 

The 2 character ISO 3166-1 Country code

mailPref 

Opt (I)n, Opt (O)ut

phone 

Preferred format "+CCC AAA LLL LLLL xEEEE"

isMobile 

Phone number is mobile? Y, N or empty

phonePref 

Opt (I)n, Opt (O)ut

email 

May be up to 320 characters long

emailPref 

Opt (I)n, Opt (O)ut

birthday 

YYYYMMDD 

anniversary 

YYYYMMDD 

gender 

M, F 

1.5 Loyalty Redemption

1.5.1 Description

Loyalty Redemption may be used to either convert loyalty points or punches to a promotion or a

currency, redeem points as part of a purchase, or to redeem one or more promotions. It should

not be used to remove a standard currency balance; for this, the Gift Redemption Transaction

should be used.

1.5.2 Route

Relative route: /v4/rest/loyaltyredemption

HTTP verb: POST

Body type: JSON

1.5.3 Sample JSON Request

Request JSON

{

    "standardHeader": {

        "requestId""1",

        "localeId"null,

        "systemId""SB"

        "clientId""999",

        "locationId""171162",

        "terminalId""2",

        "terminalDateTime"null,

        "initiatorType""E",

        "initiatorId""1000",

        "initiatorPassword""1234",

        "externalId"null,

        "batchId"null,

        "batchReference"null,

        "channel""SMS",

        "subChannel""Twilio",

    },

    "account": {

        "programId"null,

        "accountId""918261735748234",

        "pin""821886",

        "entryType""K"

    },

    "activating"null,

    "amount": {

        "valueCode""Points",

        "enteredAmount""4",

        "nsfAllowed"null

    },

    "promotionCodes"null// 0 to 50 repetitions

    "questionsAndAnswers"null// 0 to 5 repetitions

    "customerInfo": {

        "customerType""1",

        "firstName""Mark"

        "middleName"null,

        "lastName"null

        "address1"null,

        "address2"null

        "city"null,

        "state"null

        "postal"null,

        "country"null

        "mailPref"null,

        "phone"null

        "isMobile"null,

        "phonePref"null

        "email"null,

        "emailPref"null

        "birthday"null,

        "anniversary"null

        "gender"null

    }

}

1.5.4 Parameters

Required

Field Name 

Description 

requestId 

rolling counter to authenticate request, reconcile transactions, and identify duplicate request. It is an alphanumeric string up to 64 characters long.

systemId 

always "SB"

clientId 

id of the client (ISO) 

locationId 

id of the merchant location 

terminalId 

id of the terminal 

accountId 

Account Id or Scan 

entryType 

(B)arcode, (K)eyed, (M)agnetic, (P)roximity 

valueCode 

ISO 4217 currency id or a group-specific code

Optional

Parameter 

Description 

localeId 

locale id is the localization id. It is not required and will default to the host settings if it is not set

terminalDateTime 

The date and time of the terminal: YYYYMMDD or YYYYMMDDHHMMSS

initiatorType 

(E)mployee, Client (U)ser, Account-holding (C)customer

initiatorId 

Employee, User/Customer Id 

initiatorPassword 

Employee, User/Customer Password

externalId 

Id from integrated POS system 

batchId 

The terminal's batch, may be used to search

batchReference 

The terminal's id within the batch, may be used to search

channel 

subChannel 

programId 

id of the program the account belongs to, used when referencing account by external id

pin 

Account Id's pin 

activating 

A flag used to determine if the transaction should activate the account. Valid values for this flag are Y and N. If these is not set the default behavior will be used.

enteredAmount 

purchase amount: may include up to 2 decimal places

nsfAllowed 

Non sufficient funds Y or N 

promotionCodes 

array of promotionCode (0-50 repetitions, each promoCode has code and quantity parameter)

questionsAndAnswers 

array of questionAndAnswer (0-5 repetitions, each 

questionAndAnswer has code and answer parameter)

customerType 

(1) Primary account holder, (2) Alternate, (G)iver of card

firstName 

May be up to 35 characters long

middleName 

May be up to 35 characters long

lastName 

May be up to 35 characters long

address1 

May be up to 100 characters long

address2 

May be up to 100 characters long

city 

May be up to 75 characters long

state 

May be up to 75 characters long

postal

Must be valid

country 

The 2 character ISO 3166-1 Country code

mailPref 

Opt (I)n, Opt (O)ut

phone 

Preferred format "+CCC AAA LLL LLLL xEEEE"

isMobile 

Phone number is mobile? Y, N or empty

phonePref 

Opt (I)n, Opt (O)ut

email 

May be up to 320 characters long

emailPref 

Opt (I)n, Opt (O)ut

birthday 

YYYYMMDD 

anniversary 

YYYYMMDD 

gender 

M, F 

1.6 Tip

1.6.1 Description

Tips remove additional value from an account's currency balance after a Gift Redemption

Transaction has completed. Gift Redemption transactions may only have one tip associated. It

may already include a tip (without a separate tip transaction). Tips can only be appended to a

sale within 24 hours of the Gift Redeem. It can be voided separately. But it must be voided if the

Gift Redeem is void.

1.6.2 Route

Relative route: /v4/rest/tip

HTTP verb: POST

Body type: JSON

1.6.3 Sample JSON Request

Request JSON

{

    "standardHeader": {

        "requestId""1",

        "localeId"null,

        "systemId""SB"

        "clientId""999",

        "locationId""171162",

        "terminalId""2",

        "terminalDateTime"null,

        "initiatorType""E",

        "initiatorId""1000",

        "initiatorPassword""1234",

        "externalId"null,

        "batchId"null,

        "batchReference"null,

        "channel""SMS",

        "subChannel""Twilio",

    },

    "account": {

        "programId"null,

        "accountId""918261731033350",

        "pin""707268",

        "entryType""K"

    },

    "search": {

        "batchId"null,

        "batchReference"null,

        "transactionId""1875666",

        "approvalCode"null

    },

    "amount": {

        "valueCode""USD",

        "enteredAmount""8.00",

        "nsfAllowed""N"

    },

    "questionsAndAnswers"null // 0 to 5 repetitions

}

1.6.4 Parameters

Required

Field Name 

Description 

requestId 

rolling counter to authenticate request, reconcile transactions, and identify duplicate request. It is an alphanumeric string up to 64 characters long.

systemId 

always "SB"

clientId 

id of the client (ISO) 

locationId 

id of the merchant location 

terminalId 

id of the terminal 

accountId 

Account Id or Scan 

entryType 

(B)arcode, (K)eyed, (M)agnetic, (P)roximity 

valueCode 

ISO 4217 currency id or a group-specific code

Text Box 2

Optional

Parameter 

Description 

localeId 

locale id is the localization id. It is not required and will default to the host settings if it is not set

terminalDateTime 

The date and time of the terminal: YYYYMMDD or YYYYMMDDHHMMSS

initiatorType 

(E)mployee, Client (U)ser, Account-holding (C)customer

initiatorId 

Employee, User/Customer Id 

initiatorPassword 

Employee, User/Customer Password

externalId 

Id from integrated POS system 

batchId 

The terminal's batch, may be used to search

batchReference 

The terminal's id within the batch, may be used to search

programId 

id of the program the account belongs to, used when referencing account by external id

pin 

Account Id's pin 

batchId

batch id of transaction to add tip on to (search for previous transactions to add tip to based on past transaction's batchId)

batchReference

batch reference of transaction to add tip on to (search for previous transactions to add tip to based on past transaction's batchReference)

channel

subChannel

transactionId 

transaction id of transaction to add tip on to (search for previous transactions to add tip to based on past transaction's transactionId)

approvalCode

approval code of transaction to add tip on to (search for previous transactions to add tip to based on past transaction's approvalCode)

enteredAmount 

Amount to tip

nsfAllowed 

Non sufficient funds Y or N 

questionsAndAnswers 

array of questionAndAnswer (0-5 repetitions, each 

questionAndAnswer has code and answer parameter)

1.7 Void Transaction

1.7.1 Description

The Void Transaction may be used to reverse a previous transaction. The operator may void the

previous transaction, the previous transaction on a card, a transaction identified by a transaction

id, or a transaction identified by a transaction id and an authorization number. A Void

transaction may provide entirely valid information and still fail, if the state of the account has

changed between the void and the transaction the operator wishes to void. For example, if gift

value is issued to an account and then redeemed, a void on the original issuance of gift value

should fail because the balance is no longer available to be removed.

Void Transaction Types:

1) Previous transaction by Account

include the account element - the previous transaction will be attempted to be voided

2) Specific transaction by transactionId

include the search element with the transaction_id - the matching transaction with the

transaction_id will be attempted to be voided

3) Specific transaction by transactionId AND authorization number

include the search element with the transaction_id AND approval_code - the matching

transaction with the transaction_id will be attempted to be voided

Void Failure Cases:

1) Previously Voided Transactions

2) Voiding a VoidTransaction

3) Balance being Voided is no longer available

4) Account Identifier not Found

5) Search element does not find a corresponding Transaction

6) Improperly formatted Request

1.7.2 Route

Relative route: /v4/rest/voidtransaction

HTTP verb: POST

Body type: JSON

1.7.3 Sample JSON Request

Request JSON

{

    "standardHeader": {

        "requestId""1",

        "localeId"null,

        "systemId""SB"

        "clientId""999",

        "locationId""171162",

        "terminalId""2",

        "terminalDateTime"null,

        "initiatorType""E",

        "initiatorId""1000",

        "initiatorPassword""1234",

        "externalId"null,

        "batchId"null,

        "batchReference"null,

        "channel""SMS",

        "subChannel""Twilio",

    },

    "search": {

        "batchId"null,

        "batchReference"null,

        "transactionId""1875720",

        "approvalCode"null

    },

    "questionsAndAnswers"null // 0 to 5 repetitions

}

1.7.4 Parameters

Request Parameters

Parameter 

Required 

Description 

Data 

Type

Special Format 

Length

standardHeader 

Yes 

see details on 

standardHeader 

parameters

account

entryType 

(see options)

entry method for the account id: 

(B)arcode, (K)eyed, (M)agnetic, 

(P)roximity

String 

[B,K,M,P] 

1

accountId 

(see options)

Account identifier 

String 

Alphanumeric 

0-60

accountIdType 

No 

the account 

identifier type 

entered: Card, 

Phone, 

PaymentCardToken, Email

String 

[Card, Phone, 

PaymentCardToken, Email]

accountIdSuffix 

No 

last 4 digits of a 

Payment Card - 

applies only for 

accountIdType: 

PaymentCardToken

Integer 

Numeric 

4

pin 

No 

pin number of the account or card

Integer 

Numeric 

0-6

programId 

No 

id of the program the account belongs to, used when 

referencing account by external id

Integer 

Numeric 

0-9

search

batchId

No 

the amount of the transaction

Integer

batchReference

No 

batchReference of target transaction

String

transactionId

(see options)

transactionId of target transaction

String

approvalCode

No 

approvalCode of target transaction

String

questionAndAnswers 

Array of 

questionAndAnswer elements (0-5)

Array

 questionAndAnswer

code 

No 

the code of the 

question to be 

answered

String

answer 

No 

the answer to the question

String

Version 72