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] |
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:
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
Relative route: /v4/rest/giftissuance
HTTP verb: POST
Body type: 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
}
}
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 |
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 | |
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. |
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.
Relative route: /v4/rest/giftredemption
HTTP verb: POST
Body type: 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": "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
}
}
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 |
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 |
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 | ||
hostMessage | A dynamic, printable message from the host | ||
printCode | A list of codes that can correspond to additional printable data. |
The Inquiry transaction is designed to provide information about an account including the
balances, promoCodeAssignments, customerInfo, promotions. Inquiry does not alter
balances or promoCodeAssignments.
Relative route: /v4/rest/inquiry
HTTP verb: POST
Body type: 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
}
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 | |
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. |
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".
Relative route: /v4/rest/loyaltyissuance
HTTP verb: POST
Body type: 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": "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
}
}
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 |
May be up to 320 characters long | |
emailPref | Opt (I)n, Opt (O)ut |
birthday | YYYYMMDD |
anniversary | YYYYMMDD |
gender | M, F |
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.
Relative route: /v4/rest/loyaltyredemption
HTTP verb: POST
Body type: 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": "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
}
}
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 |
May be up to 320 characters long | |
emailPref | Opt (I)n, Opt (O)ut |
birthday | YYYYMMDD |
anniversary | YYYYMMDD |
gender | M, F |
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.
Relative route: /v4/rest/tip
HTTP verb: POST
Body type: 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": "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
}
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 |
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) |
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
Relative route: /v4/rest/voidtransaction
HTTP verb: POST
Body type: 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",
},
"search": {
"batchId": null,
"batchReference": null,
"transactionId": "1875720",
"approvalCode": null
},
"questionsAndAnswers": null // 0 to 5 repetitions
}
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