archer developer guide v2

© 2018 Xenial, a Global Payments company. All Rights Reserved. Proprietary and Confidential Information. 1

Archer Developer Guide v2

Copyright © 2019 Xenial, Inc. A Global Payments Company. All Rights Reserved. Proprietary and Confidential Information.

Document Version 140


NoticeTHE INFORMATION CONTAINED HEREIN IS PROVIDED TO RECIPIENT "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULARPURPOSE, OR WARRANTY OF TITLE OR NON- INFRINGEMENT. ALL SUCH WARRANTIES ARE EXPRESSLY DISCLAIMED.

XENIAL SHALL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTINGFROM THE USE OF ANY INFORMATION CONTAINED HEREIN, WHETHER RESULTING FROM BREACH OF CONTRACT, BREACH OFWARRANTY, NEGLIGENCE, OR OTHERWISE, EVEN IF XENIAL HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. XENIALRESERVES THE RIGHT TO MAKE CHANGES TO THE INFORMATION CONTAINED HEREIN AT ANY TIME WITHOUT NOTICE.

THIS DOCUMENT AND ALL INFORMATION CONTAINED HEREIN IS PROPRIETARY XENIAL INFORMATION. UNDER ANYCIRCUMSTANCES, RECIPIENT SHALL NOT DISCLOSE THIS DOCUMENT OR THE SYSTEM DESCRIBED HEREIN TO ANY THIRD PARTYWITHOUT PRIOR WRITTEN CONSENT OF A DULY AUTHORIZED REPRESENTATIVE OF XENIAL. IN ORDER TO PROTECT THECONFIDENTIAL NATURE OF THIS PROPRIETARY INFORMATION, RECIPIENT AGREES:

A. TO IMPOSE IN WRITING SIMILAR OBLIGATIONS OF CONFIDENTIALITY AND NON- DISCLOSURE AS CONTAINEDHEREIN ON RECIPIENT'S EMPLOYEES AND AUTHORIZED THIRD PARTIES TO WHOM RECIPIENT DISCLOSES THISINFORMATION (SUCH DISCLOSURE TO BE MADE ON A STRICTLY NEED-TO-KNOW BASIS) PRIOR TO SHARING THISDOCUMENT AND

B. TO BE RESPONSIBLE FOR ANY BREACH OF CONFIDENTIALITY BY THOSE EMPLOYEES AND THIRD PARTIES TOWHOM RECIPIENT DISCLOSES THIS INFORMATION.

RECIPIENT ACKNOWLEDGES AND AGREES THAT USE OF THE INFORMATION CONTAINED HEREIN SIGNIFIES ACKNOWLEDGEMENTAND ACCEPTANCE OF THESE TERMS. ANY SUCH USE IS CONDITIONED UPON THE TERMS, CONDITIONS AND OBLIGATIONSCONTAINED WITHIN THIS NOTICE.

THE TRADEMARKS AND SERVICE MARKS RELATING TO PRODUCTS OR SERVICES OF XENIAL OR OF THIRD PARTIES ARE OWNEDBY XENIAL OR THE RESPECTIVE THIRD PARTY OWNERS OF THOSE MARKS, AS THE CASE MAY BE, AND NO LICENSE WITHRESPECT TO ANY SUCH MARK IS EITHER GRANTED OR IMPLIED.

TO VERIFY EXISTING CONTENT OR TO OBTAIN ADDITIONAL INFORMATION, PLEASE CALL OR EMAIL YOUR ASSIGNED XENIALCONTACT.


1. Table of Contents Table of Contents1. Overview2.

Introduction2.1. Audience2.2. Who This is Intended For2.3. Not Other Limitations of the API2.4.

Archer API Overview3. Using the Archer API3.1.

URL-encoded request example3.1.1. JSON request example3.1.2. URL-encoded response example3.1.3. JSON response example3.1.4.

Errors3.2. Case Sensitive3.3. Versioning and Backwards Compatibility3.4. Security3.5. Client Authorization3.6. Authentication3.7. Archer API Endpoints3.8. Summary of Archer API Calls3.9.

Loyalty Integrations4. Balances, Loyalty, and Discounts4.1.

Balances4.1.1. Loyalty4.1.2. Discounts4.1.3.

Archer API Reference5. Activate5.1.

Usage5.1.1. Request Parameters5.1.2. Response Parameters5.1.3.

Load5.2. Description5.2.1. Request Parameters5.2.2. Response Parameters5.2.3.

Redeem5.3. Usage5.3.1. Request Parameters5.3.2. Response Parameters5.3.3.

Balance Inquiry5.4. Usage5.4.1. Request Parameters5.4.2. Response Parameters5.4.3.

Void5.5. Usage5.5.1. Request Parameters5.5.2. Response Parameters5.5.3.

Reverse5.6. Usage5.6.1. Request Parameters5.6.2. Response Parameters5.6.3.

Transfer5.7. Usage5.7.1. Request Parameters5.7.2. Response Parameters5.7.3.

Reward5.8. Usage5.8.1. Request Parameters5.8.2. Response Parameters5.8.3.

Add Alias5.9. Usage5.9.1. Request Parameters5.9.2. Response Parameters5.9.3.

Remove Alias5.10. Usage5.10.1. Request Parameters5.10.2. Response Parameters5.10.3.

Create Alias5.11. Usage5.11.1. Request Parameters5.11.2. Response Parameters5.11.3.


Deactivate5.12. Usage5.12.1. Request Parameters5.12.2. Response Parameters5.12.3.

Greet5.13. Usage5.13.1. Request Parameters5.13.2. Response Parameters5.13.3.

Rewards Info5.14. Usage5.14.1. Request Parameters5.14.2. Response Parameters5.14.3. Notes5.14.4.

Cashout5.15. Usage5.15.1. Request Parameters5.15.2. Response Parameters5.15.3.

Compute Loyalty5.16. Usage5.16.1. Request Parameters5.16.2. Response Parameters5.16.3.

Archer Certification Mode example success responses6. Activate / cm6.1. Load / cm6.2. Redeem / cm6.3. Balance Inquiry / cm6.4. Void / cm6.5. Reverse / cm6.6. Transfer / cm6.7. Reward / cm6.8. Rewards Info / cm6.9. Create Alias / cm6.10. Add Alias and Remove Alias / cm6.11. Deactivate / cm6.12. Greet / cm6.13. Cashout / cm6.14. Compute Loyalty / cm6.15.

Appendices7. Appendix A - Parameter Reference7.1.

domain7.1.1. chain7.1.2. store7.1.3. terminal7.1.4. request7.1.5. sva7.1.6. acquired7.1.7. amount7.1.8. currency7.1.9.

pin7.1.10. tax7.1.11. tip7.1.12. exclude7.1.13. order7.1.14. reversal7.1.15. alias7.1.16. status.code7.1.17. status.name7.1.18. status.description7.1.19. account7.1.20. alias7.1.21. sva.status7.1.22. sva.registered7.1.23. sva.balances7.1.24. sva.detailedBalances7.1.25.

currency7.1.25.1. amount7.1.25.2. threshold7.1.25.3. flavor7.1.25.4.

orders7.1.26. notes7.1.27. rewards7.1.28. void.action7.1.29. terminal.order7.1.30. terminal.version7.1.31. owed7.1.32.


partial7.1.33. clerk7.1.34. coupon7.1.35. coupon.status7.1.36. coupon.description7.1.37. coupon.balances7.1.38. payment.type7.1.39. user.custom7.1.40. redemption.start7.1.41. redemption.end7.1.42. promotional7.1.43. orderInfo7.1.44. discount.status7.1.45.

Appendix B - Enumerated Values7.2. Acquired Type Values7.2.1. Account Status Values7.2.2. Payment Type Values7.2.3. Discount Status Values7.2.4. Order Info Values7.2.5.

Appendix C - Errors7.3. HTTP errors7.3.1. Application errors7.3.2.

Appendix D - Certification Host Response Matrix7.4. Amount Response Matrix7.4.1.

Appendix E - Certification Host Stored Value Accounts7.5. Appendix F - Code Samples7.6.

Curl7.6.1. Java7.6.2.

Appendix G - HTTP headers7.7. Content-type7.7.1. Accept7.7.2.


2. Overview

2.1. Introduction

Archer is a simple HTTP-based API for performing gift, loyalty, digital wallet, and rewards transactions against the Xenial Stored Value Platform. Itis designed completely around standard HTTP features that are supported out-of-the-box by your favorite HTTP client, no matter what languageor platform you are using.

2.2. Audience

This document is provided for software developers integrating software with the Xenial Stored Value Platform via the Archer API. This APIprovides a simple integration path that allows developers to build functioning clients quickly and easily. This is accomplished by:

Leveraging standard HTTP protocols and clientsNot requiring the use of complicated SOAP, XML or JSON schemas for requests or responsesProviding a simplified view of the platform's available feature setProviding client libraries for certain languages and platforms

2.3. Who This is Intended ForNot

The Archer API has been designed for simplicity and is not appropriate for everyone. It may not be suitable for your needs if one or more of thefollowing are true:

You require a robust credit and/or debit processing interface

2.4. Other Limitations of the API

The Archer API was designed for use by merchant-oriented applications (including terminal, point of sale, e-commerce, host-to-host, mobilewallet, and others) that are configured at runtime, either statically or dynamically, with merchant credentials provided by Xenial. It may beappropriate for some applications, most notably consumer-facing mobile or web applications, to use a different API (such as the Katana API) thatis designed with a security, authentication, and authorization model more appropriate for those classes of applications.


1. 2. 3. 4.

3. Archer API Overview

3.1. Using the Archer API

The easiest way to explain how to use Archer is with an example. To send an Archer request, you POST form data to a URL like that shownbelow.

The URL is broken up into four distinct parts:

The is the address of the Archer host you are using. Multiple endpoints exist for development, testing, and production use.API EndpointThe identifies the fact that you are attempting to use the Archer API (as opposed to another Xenial API).API NameThe denotes that you are using Version 1 of the Archer API.API VersionLastly, the identifies what request type you are trying to perform. In this case, the client was performing a "load" to add value toAPI Calla stored value account.

Each Archer API Call requires a set of parameters necessary to execute the request. These parameters are passed as URL-encoded form data orJSON map that can easily be provided using a standard HTTP client. To demonstrate, the following is a fully functional example of a loadrequest using the command line utility.curl

The HTTP and headers control the input and output encoding of parameters, respectively.Content-type Accept

3.1.1. URL-encoded request example

curl https://api2.cert.chockstone.com/archer/v2/load \-iu test_user:test_password \-X POST \-d domain=test \-d request=201212312359590001 \-d store=0001 \-d terminal=0001 \-d terminal.order=0001 \-d terminal.version=v17 \-d sva=6277200000000001 \-d acquired=MANUAL \-d amount=1000 \-d currency=USD

3.1.2. JSON request example


curl https://api2.cert.chockstone.com/archer/v2/load \-iu test_user:test_password \-X POST \-H "Accept: application/json" \-H "Content-type: application/json" \-d '{"domain":"test","request":"201212312359590001","store":"0001","terminal":"0001","terminal.order":"0001","terminal.version":"v17","sva":"6277200000000001","acquired":"MANUAL","amount":1000,"currency":"USD"}'

The Archer host will return a response that contains an HTTP status code identifying whether the transaction succeeded or failed, along with aURL or JSON-encoded parameters that can be parsed and used by the client.

3.1.3. URL-encoded response example

HTTP/1.1 200 OKDate: Wed, 19 Dec 2012 23:06:33 GMTAccept-Ranges: bytesServer: chockstoneVary: Accept-Charset, Accept-Encoding, Accept-Language, AcceptContent-Type: application/x-www-form-urlencoded;charset=UTF-8Content-Length: 278

notes=%2A%2A%2A%20Certification%20test%20server%20%2A%2A%2A&order=135595839312510&rewards=Points%208&status.code=200&status.description=The%20request%20has%20succeeded&status.name=OK&sva=XXXXXXXXXXXX0001&sva.balances=USD%201000%2CPoints%208&sva.registered=true&sva.status=ACTIVE

Note that actual response data will not be sent with linebreaks or other formatting.

3.1.4. JSON response example


HTTP/1.1 200 OKDate: Wed, 19 Dec 2012 22:59:45 GMTAccept-Ranges: bytesServer: chockstoneVary: Accept-Charset, Accept-Encoding, Accept-Language, AcceptContent-Type: application/json;charset=UTF-8Transfer-Encoding: chunked

{"notes":"*** Certification test server ***","order":"135595798567700","rewards":"Points 8","status.code":"200","status.description":"The request has succeeded","status.name":"OK","sva":"XXXXXXXXXXXX0001","sva.balances":"USD 1000,Points 8","sva.detailedBalances": { "balances":[ { "currency":"USD", "amount":1000, "formatted":"10.00", "expirations":[] } ], "loyalty":[ { "currency":"Points", "amount":8, "formatted":"8", "threshold": 10, "flavor": "VISIT", "expirations":[] }, ], "discounts":[ { "currency":"D0001", “status”: “REDEEMED”, "description": "Free Coke", “redemption.end”: “2018-06-30T00:00:00Z” }, { "currency":"D0001", “status”: “AVAILABLE”, "description": "Free Coke", “redemption.end”: “2018-06-30T00:00:00Z” }, { "currency":"D0002", “status”: “FUTURE”, "description": "Free Appetizer", “redemption.start”: “2020-07-01T00:00:00Z”, “redemption.end”: “2020-07-30T00:00:00Z” }, { "currency":"D0003", “status”: “EXPIRED”, "description": "Free Taco", “redemption.end”: “2017-06-30T00:00:00Z” } ]},"sva.registered":"true","sva.status":"ACTIVE"}


1. 2. 3.

Note that actual response data will not be sent with linebreaks or other formatting.

3.2. Errors

Archer uses standard HTTP response codes to indicate success or failure of an API request. In general, means success, means an200 4XXapplication-level error, and means a system-level error. Specific errors as they are translated from the Xenial Stored Value Platform to HTTP5XXresponse codes are documented in .Appendix C - Errors

3.3. Case Sensitive

The Archer API is case sensitive! Code samples are provided throughout this document to specify currencies, parameter values, etc. If you do notmatch the cases exactly, the corresponding features will not work as intended.

3.4. Versioning and Backwards Compatibility

Every attempt is made to ensure that all changes made to a specific version of the API remain backwards compatible. Any changes that breakbackwards compatibility are implemented as a new version of the API, so that clients are unaffected and may migrate to the new version whenappropriate.

Changes that are considered to break backwards compatibility include removing request or response parameters, and changing the syntacticstructure or semantic meanings of existing parameters.

Note that both the introduction of new, optional request parameters that behave identically as before when not provided in a request, and theintroduction of new response parameters that may be ignored by clients are not considered changes that break backwards compatibility.Additionally, it is expected that well-implemented clients use appropriate defensive coding techniques and are able to ignore unexpectedresponse parameters and continue to function correctly.

3.5. Security

All Archer requests must be made using . Attempting to use plain is not supported and will consequently fail.HTTPS HTTP

3.6. Client Authorization

The Archer v1 API accepts an optional Xenial-supplied API Key with each request, using the HTTP header "Api-Key". An example API Key isprovided below.

Api-Key: 8yEsbyXBsaU

The following snippet shows how to pass client authorization credentials using the command line tool curl:

curl -H "Api-Key: 8yEsbyXBsaU" ...

All client requests should still include authentication credentials even when sending the API Key.

3.7. Authentication

Archer utilizes a simple username/password authentication scheme implemented using the standard HTTP Basic Access Authentication protocol.This authentication scheme should be supported by nearly all HTTP client libraries. Because all Archer communicationoccurs over HTTPS (SSL), the authentication credentials are protected from eavesdropping and are never exposed as plain text.

Archer expects clients to provide the appropriate authentication credentials with every request. Details about passing authentication informationto Archer using the Basic Access Authentication Protocol can be found here:http://en.wikipedia.org/wiki/Basic_access_authentication

A quick summary for manually constructing an Authorization HTTP header:

A username and password are combined into a string "username:password"The resulting string literal is then encoded using Base64Construct the header as follows (where is a sample Base64-encoded string from step 2):"dXNlcm5hbWU6cGFzc3dvcmQK"

http://en.wikipedia.org/wiki/HTTP_Secure

http://en.wikipedia.org/wiki/Basic_access_authentication


3.

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQK

Manual construction of the Basic Authentication header is typically not required if using a standard HTTP client library forcommunicating with the Archer host. For example, the following code snippet shows how to pass the authentication credentials usingthe command line tool curl:

curl -u username:password ...

3.8. Archer API Endpoints

Archer provides three API Endpoints for the different execution environments:

Environment Endpoint Description

Certification https://api2.cert.chockstone.com/archer A stateless sandbox environment for development and certification

Test https://api2.test.chockstone.com/archer An environment for customer and user acceptance testing

Production https://api2.chockstone.net/archer The environment for live, production use

The Certification environment does not store and track actual stored value accounts and balances. Instead, it is a completely statelessenvironment that mimics production behavior but is designed to provide developers the ability to control the responses received for the purpose oftesting various transaction scenarios. The developer can force a desired response by sending the appropriate value in one of the requestparameters, typically or , as documented in the section entitled .amount sva Appendix D - Certification Host Response Matrix

The Test environment is identical to the Production environment in function except that it is provided for testing only.

3.9. Summary of Archer API Calls

The following is a summary of the API Calls available within Archer via their URI path:

/archer/v2/activate/archer/v2/load/archer/v2/redeem/archer/v2/inquiry/archer/v2/void/archer/v2/reverse/archer/v2/transfer/archer/v2/reward/archer/v2/alias/add/archer/v2/alias/remove/archer/v2/alias/create/archer/v2/deactivate/archer/v2/rewardsinfo/archer/v2/cashout/archer/v2/loyalty/compute

https://api2.cert.chockstone.com/archer

https://api2.test.chockstone.com/archer

https://api2.chockstone.net/archer


4. Loyalty IntegrationsA standard Archer loyalty integration is primarily comprised of five calls:

/archer/v2/greet - identifies a loyalty member and returns information about their account/archer/v2/redeem - to redeem any available rewards/archer/v2/loyalty/compute - to provide order information, including item details and payment information, so that loyalty programand promotions can be computed./archer/v2/void - to void an Order and undo redemptions or loyalty promotions/archer/v2/reverse - to handle socket timeouts or incomplete responses from the host

4.1. Balances, Loyalty, and Discounts

A special note on the various types of currencies supported by Archer, as further documented in .sva.detailedBalances

Archer uses a single concept of a "currency" to load, redeem, and reward value (etc) onto a stored value account. This makes it simple toimplement redemption with a single API call, whether for a gift transaction or a loyalty reward redemption or a coupon redemption. However, eachtype of currency has some unique attributes.

4.1.1. Balances


This represents gift balances in a fiat currency such as USD or EUR. For more information, see .sva.detailedBalances

4.1.2. Loyalty

This represents the single loyalty currency in use by the merchant. The name is determined by the merchant based on the branding of theirprogram. For example, one merchant may use "Visits" as their loyalty currency and another may use "Points" or "Stars". As a result, awell-implemented client will not hardcode or make assumptions about the name of the loyalty currency but will instead look for the currency namethat is returned in the "loyalty" section of the sva.detailedBalances portion of a response.

This allows a client to print the loyalty currency name on receipts and on the screen consistent with the merchant's program.

4.1.3. Discounts

This currency represents discounts, rewards, and coupons that a guest will redeem. The currency name correlates exactly with a discount codewithin a POS, that enforces the logic and behavior of the discount, reward, or coupon. For presentation purposes, the client should use the"description" field instead of the currency name on receipts, screens, etc. This is because the description will always be user-friendly and intendedfor the guest to see, whereas the currency name is only to be consistent with the discount code programmed into the POS.


5. Archer API ReferenceThis section provides detailed information about each API Call supported by Archer.

Each subsection contains a table that provides a summary about the API call.

Description A short description of the purpose of the call

Request Path The path to invoke the call

Reversible Indicates whether the call should be followed immediately by a call on a network error conditionreverse

Voidable Indicates whether the call can be voided

In addition, usage information is provided explaining when and why to use the API call, as well as the request and response parametersnecessary to handle the request.


5.1. Activate

Description Activates and adds an initial balance to a new stored value account

Request Path archer/v2/activate

Reversible Yes

Voidable Yes

5.1.1. Usage

Used to activate a new stored value account and load it with an initial balance. If the specified stored value account is already active, the requestwill fail.

Note: stored value accounts can also be activated implicitly via the method depending on the platform configuration for a customer'sloadspecific program.

5.1.2. Request Parameters

Parameter Required Description Example

domain Yes Identifies the domain; see domain hps

chain Maybe Used by global partners to send requests on behalf of a group of merchants; see chain 130909013158178

request Yes Identifies this unique request; see request 201212312359590001

store Yes Identifies the store; see store 0001

terminal Yes Identifies the terminal; see terminal 001

terminal.order Yes A terminal-generated order number; see terminal.order 1701

terminal.version Yes Identifies the terminal software version; see terminal.version Cyberdyne T-1000

clerk No Identifies an individual clerk or server; see clerk 17

sva Yes Identifies the stored value account being activated; see sva 6277200000000001

pin No Specifies the PIN number associated with the account. 12345

acquired Yes Identifies how the sva was acquired; see acquired SWIPE

amount Yes The amount to activate the account with; see amount 1000

currency Yes The currency of the activation amount; see currency USD

redemption.start No The start of the redemption period (when a user can first redeem the coupon); see redemption.start

2018-08-01T00:00:00Z

redemption.end No The end of the redemption period (when the coupon expires); see redemption.end 2018-10-31T00:00:00Z

promotional No Identifies if activation amount is a promotional amount; see promotional true

5.1.3. Response Parameters

Parameter AlwaysExists

Description Example

status.code Yes Response status code; see status.code 200

status.name Yes Response status name; see status.name AccountNotFound

status.description Yes Long, detailed description about the error; see status.description

order Yes A host-generated order ID; Used for voids. 120100010000000063


sva Yes The masked version of the stored value account XXXXXXXXXXXX0001

sva.status Yes The status of the stored value account; see sva.status ACTIVE

sva.registered Yes Identifies whether the account is registered or not; see sva.registered

true

sva.balances Yes The account's balances; see sva.balances "USD 1000,Points 1"

sva.detailedBalances Yes,JSON-only

The account's gift and loyalty balances, available discounts, andloyalty progress; see sva.detailedBalances

rewards No A list of any rewards added to the account; see rewards "Points 5"

notes No Rewards notes; see notes "You have earned an extra $1 forloading $10 onto your account!"


5.2. Load

Description Loads value onto a stored value account

Request Path archer/v2/load

Reversible Yes

Voidable Yes

5.2.1. Description

Loads a stored value account. In most cases (depending on the platform configuration for a customer) this request will also automatically activatethe account if necessary.

This method is typically used to add actual tendered currencies such as , but can also be used to add (although this is discouraged inUSD Pointspractice, as are typically awarded automatically by the host platform as defined by the customer's specific rewards program).Points











sva Yes Identifies the stored value account being loaded; see sva 6277200000000001



amount Yes The amount to load; see amount 1000

currency Yes The currency being loaded; see currency USD

redemption.start No The start of the redemption period (when a user can first redeem the coupon); see redemption.start

2018-08-01T00:00:00Z

redemption.end No The end of the redemption period (when the coupon expires); see redemption.end 2018-10-31T00:00:00Z

promotional No Identifies if activation amount is a promotional amount; see promotional true



Description Example









true







5.3. Redeem

Description Redeems value from a stored value account

Request Path archer/v2/redeem

Reversible Yes

Voidable Yes

5.3.1. Usage

Redeems value from a stored value account for the amount and currency specified. The corresponding account balance is decrementedaccordingly.

By default, if the account balance is non-zero but insufficient to cover the full redemption amount, the remaining balance will be drained and theamount still will be returned in the response for additional payment. This behavior is consistent with explicitly providing the parameterowed partialwith a value of "true". To disable this behavior so that the full amount must be redeemed or else the entire transaction fails, the client shouldprovide the parameter with the value of "false".partial

When partial authorization is being accepted and there is an amount still owed by the consumer, the merchant may accept any additional tenderto cover the balance. If the account holder is unable to provide additional payment and the purchase is canceled, then this transaction should bevoided to return the balance back to the account.











sva Yes Identifies the stored value account being redeemed; see sva 6277200000000001


amount Yes The total amount to redeem from the account, including tip and tax; see amount 1000

currency Yes The currency of the redemption amount; see currency USD

partial No Identifies whether a partial authorization is accepted or not; see partial true

pin No The pin associated with the sva; see pin 123456

tax No The portion of the amount being redeemed that represents tax; see tax 80

tip No The portion of the amount being redeemed that represents a tip; see tip 200



Description Example









true






owed Yes An amount still owed following the redemption. In cases ofinsufficient funds this will be non-zero; see owed

USD 278


5.4. Balance Inquiry

Description Returns the balances of all currencies on a stored value account

Request Path archer/v2/inquiry

Reversible No

Voidable No

5.4.1. Usage

Used to retrieve and display the balance(s) for each currency supported by a stored value account.










sva Yes Identifies the stored value account; see sva 6277200000000001





Description Example







true







5.5. Void

Description Voids a prior transaction using the parameter returned in its responseorder

Request Path archer/v2/void

Reversible Yes

Voidable No

5.5.1. Usage

Used to void (undo) a prior successful transaction. The original response from the host for the transaction to be voided contained a unique orderparameter used to identify the transaction. This parameter is specified to the host as part of the request to identify which transactionorder voidto be voided.

When voiding a transaction, all changes to the account are reversed, including any additional value added by rewards programs or automatedpromotions.

Note: if a transaction fails to return a complete response due to a network timeout condition, do not attempt to the transaction.void reverseInstead, resend the same transaction until you get a complete response back, whether the response indicates success or an error condition.void




chain Maybe Used by global partners to send requests on behalf of a group of merchants; see . Either store or chain must be supplied.chain

130909013158178


store Maybe Identifies the store; see . Either store or chain must be supplied.store 0001




order Yes Identifies the transaction to void; see order 14000000000000000001



Description Example








true






void.action Yes The action voided; see void.action redeem

void.amount Yes The amount voided; see amount 500

void.currency Yes The currency voided; see currency USD


5.6. Reverse

Description Reverses a prior transaction using the parameter of the original requestrequest

Request Path archer/v2/reverse

Reversible No

Voidable No

5.6.1. Usage

Used to reverse (undo) a prior transaction where a complete response was not received due to a network timeout. The parameter of therequestoriginal transaction is sent as the parameter to identify the transaction to be reversed.reversal

When reversing a transaction, all changes to the account are reversed, including any additional value added by rewards programs or automatedpromotions.

Note: if a transaction fails to return a complete response due to a network timeout condition, continue sending the same reverse reverserequest until you get a complete response back.




chain Maybe Used by global partners to send requests on behalf of a group of merchants; see .chainEither store or chain must be supplied.

130909013158178


store Maybe Identifies the store; see . Either store or chain must be supplied.store 0001




reversal Yes Identifies the transaction to reverse; see reversal 201212312359590001


Parameter Always Exists Description Example




reversal Yes Identifies the request ID of the transaction reversed; see reversal 201212312359590001


5.7. Transfer

Description Transfers balances from one stored value account to another

Request Path archer/v2/transfer

Reversible No

Voidable No

5.7.1. Usage

Transfers balances from one stored value account to another. This function is typically performed to replace a lost or stolen account with a newone or to consolidate two or more accounts into a single account.

After a transfer has completed, the source account will be closed and can no longer be used. The balance for the destination account will bereturned in the response.










from.sva Yes Identifies the stored value account to transfer from; see sva 6277200000000001

from.acquired Yes Identifies how the "from" sva was acquired; see acquired MANUAL

from.pin No Specifies the PIN number associated with the "from" account. 12345

to.sva Yes Identifies the stored value account being transferred to; see sva 627720000000002

to.acquired Yes Identifies how the "to" sva was acquired; see acquired SWIPE

to.pin No Specifies the PIN number associated with the "to" account. 12345



Description Example






sva.registered Yes Identifies whether the account is registered or not; see sva.registered true




The account's gift and loyalty balances, available discounts, and loyaltyprogress; see sva.detailedBalances


5.8. Reward

Description Specifies a payment amount from some payment form other than from a stored value account for the purpose of earningrewards

RequestPath

archer/v2/reward

Reversible Yes

Voidable Yes

5.8.1. Usage

When an account holder makes a payment using a payment form other than a stored value account (e.g. cash or credit card), the account holdermay present their stored value account to earn Points or other loyalty rewards which would be added to their account. This may occur by swipinga loyalty card, entering an alias (e.g. a phone number) or scanning a mobile app (amongst other possibilities).

The purchase amount will be deducted from the stored value account (as it would via a transaction) or loaded onto the stored valuenot redeemaccount (as it would via a transaction). Instead, the purchase amount is used to help determine what potential rewards may be addedloadbased on the merchant's loyalty and rewards program.











sva Yes Identifies the stored value account being rewarded; see sva 6277200000000001



amount Yes The total amount of the purchase, including tip and tax; see amount 1000

currency Yes The currency of the purchase; see currency USD

tax No The portion of the amount that represents tax; see tax 80

tip No The portion of the amount that represents a tip; see tip 200

exclude No The (non-tip, non-tax) portion of the amount that should be excluded from rewards; see exclude

1000



Description Example









true







5.9. Add Alias

Description Adds an alias, such as a phone number, to an existing stored value account

Request Path archer/v2/alias/add

Reversible No

Voidable No

5.9.1. Usage

This allows an account holder to add their phone number as an alias to a stored value account so that they may present their phone number to amerchant in place of a plastic card or other device.










sva Yes Identifies the stored value account being aliased; see sva 6277200000000001



alias Yes The alias to add to the sva; see alias 5035551212






sva Yes Identifies the account number that was aliased; see account 6277200000000001

alias Yes Identifies the alias that was added to the account; see alias 5035551212


5.10. Remove Alias

Description Removes an alias, such as a phone number, from a stored value account

Request Path archer/v2/alias/remove

Reversible No

Voidable No

5.10.1. Usage

This allows an account holder to remove their phone number as an alias from a stored value account. This is typically done because the accountholder wants to change to a new phone number or because they want to associate their current phone number with a different stored valueaccount.










sva Yes Identifies the stored value account that is aliased; see sva 6277200000000001



alias Yes The alias to remove from the sva; see alias 5035551212






sva Yes Identifies the account number that had the alias removed; see account 6277200000000001

alias Yes Identifies the alias that was removed from the account; see alias 5035551212


5.11. Create Alias

Description Creates a new stored value account and associates an alias to it

Request Path archer/v2/alias/create

Reversible No

Voidable No

5.11.1. Usage

This allows an account holder to add their phone number as an alias to a brand new stored value account. The new account does not have havea plastic card associated with it. This is typically referred to as a "cardless" account and can be used in cardless environments or by mobileapplications where the mobile device serves as a virtual "card."










alias Yes The alias to add to the new sva; see alias 5035551212






sva Yes Identifies the account number that was created and aliased; see account 6277200000000001

alias Yes Identifies the alias that was added to the new account; see alias 5035551212

pin Yes Specifies the PIN number associated with the new account. 12345


5.12. Deactivate

Description Deactivates an active stored value account

Request Path archer/v2/deactivate

Reversible Yes

Voidable No

5.12.1. Usage

Used to undo an activation of a stored value account that otherwise has not been used. Deactivation resets the account so that it is brand new,with zero balance or activity. Attempts to deactivate an account that is not active or has had subsequent activity will fail.




chain Maybe Used by global partners to send requests on behalf of a group of merchants; see .chainEither chain or store must be supplied.

130909013158178


store Maybe Identifies the store; see . Either chain or store must be supplied.store 0001





sva Yes Identifies the stored value account being deactivated; see sva 6277200000000001





Description Example





sva.status Yes The status of the stored value account; see sva.status NEW

sva.registered Yes Identifies whether the account is registered or not; see sva.registered false



The account's gift and loyalty balances, available discounts, and loyaltyprogress; see sva.detailedBalances


5.13. Greet

Description Returns an account balance plus registered owner information.

Request Path archer/v2/greet

Reversible No

Voidable No

5.13.1. Usage

Typically used in a restaurant scenario when a consumer first walks into the restaurant. This API will return an account balance, information aboutthe registered owner of the card, register a "visit" event for reporting and also may cause promos to fire without there being a financial transactioninvolved.









sva Yes Identifies the stored value account being presented; see sva 6277200000000001



orderInfo No Whether or not to include information on the last few orders in the response; see orderInfo ALL



Description Example









orders No Details of the last three COMPLETED orders; see orders


sva.status Yes The status of the stored value account; see sva.status NEW



false

sva.lastvisitstore No Last store at which this account was used. “PITA3207”

sva.lastvisitdate No Last date this account was used. "2014-03-17”

sva.dateregistered No Date on which this account was registered. “2013-01-02”

sva.dateactivated No Date on which this account was first used. “2014-03-12”

user.firstname No Consumers first name. "John"

user.lastname No Consumers last name. "Doe”

user.birthday No Day of the month of the consumers birthday, if available. "31”

user.birthmonth No Month of the year of the consumers birthday, if available. "12”

user.birthyear No Year of the consumers birthday, if available. "1975”

user.id.beanstalk No Consumer's ContactID if they are registered with Beanstalk. "17139584”

user.custom No,JSON-Only

Custom fields that are merchant-defined; see user.custom

5.14. Rewards Info

Description Returns the details of a loyalty rewards program that can be communicated to a consumer.

Request Path archer/v2/rewardsinfo

Reversible No

Voidable No

5.14.1. Usage

Typically used in a mobile app or by 3rd party developers to clearly communicate the details of a loyalty program to a consumer to promote usageand adoption. This API will return the program name, a short description, rewards structure (threshold and flavor), and URL to a full programdescription on the merchant's website.




chain Yes Identifies the merchant; see chain 130909013158178






Description Example




program.name Yes The name of the merchant's rewards program Bob's rewards


program.description Yes A brief description of the rewards program that can be displayed inline A fantastic rewards programbrought to you by Bob

program.flavor Yes A hint for rendering the progress towards the next reward in a loyaltyprogram; see flavor

VISIT SPEND LOAD PUNCH POINTS

program.threshold Yes Indicates the loyalty (non-tendered) balance amount needed to obtain anext reward in the loyalty program; see threshold

20

program.url Yes Link to full program details on the merchant's website https://heartlandgiftcard.com/

5.14.4. Notes

Returns an error if no Rewards Info is available for the merchant.

5.15. Cashout

Description Cashes out all remaining tendered currency from a stored value account, below a maximum amount.

Request Path archer/v2/cashout

Reversible Yes

Voidable Yes

5.15.1. Usage

A cashout transaction removes the entire cash value of a stored value account, if it's below the given maximum amount. So a $10 cashoutrequest would zero an account with a $9 balance (returning $9 to the consumer in cash). A $10 cashout request would fail and do nothing on anaccount with an $11 balance - the accounts balance is too high to cashout.




chain Maybe Used by global partners to send requests on behalf of a group ofmerchants; see chain

130909013158178







sva Yes Identifies the stored value account being cashed-out; see sva 6277200000000001


amount Yes The maximum amount (the limit) to cashout. Any card with a balancebelow this amount will be zeroed. amount

1000

currency Yes The currency of the cashout amount; see currency USD



https://heartlandgiftcard.com/









sva.registered Yes Identifies whether the account is registered or not; see sva.registered true


amount Yes The actual amount (balance) removed from the stored value account. USD 800


5.16. Compute Loyalty

Description Sends a finalized order complete with line items and payment advice so that progress and rewards associated with a loyaltyprogram can be computed

Request Path archer/v2/loyalty/compute

Content-Type Only supported. See application/json Content-type

Reversible Yes

Voidable Yes

5.16.1. Usage

Sends a finalized order (ticket) with line items and payment advice. This is typically the last thing sent before an order / ticket is finalized or closed.Prior to this, all coupons, discounts, redemptions, and payments have already been made.




chain Maybe Used by global partners to send requests on behalf of a group of merchants;see chain

130909013158178




terminal.order Yes A terminal-generated order number; see ; This should be theterminal.ordersame as was sent in any other redeem or load requests, for example, for thisorder.

7162534



sva Yes Identifies the stored value account; see sva 5022440200008000001


amount Yes The total amount of payments, including tip and tax; see amount 1000

currency Yes The currency of the amount; see currency USD

pin No The pin associated with the sva; see pin 123456

lineItem No Line items in an order

payment No Payments in an order

orderLineNumber Yes Line number of an order lineItem. 1001

sku Yes Stock Keeping Unit (SKU) of an order lineItem 355

quantity Yes Quantity ordered of an order lineItem 1

description No Description of an order lineItem Chicken Sandwich

type Yes Type of a payment in the order; see payment.type CASH


{"domain": "hps","request": "201803151253421369366454","store": "650000009539704","terminal": "1953416","terminal.version": "Cyberdyne T-1000","terminal.order": "7162534","sva": ";5022440200008000001=380100033158ARCHER?","pin": "8695","acquired": "SWIPE","amount": 1382,"currency": "USD","tax": 88,"tip": 200,"lineItem": [{"orderLineNumber": 1,"amount": 895,"currency": "USD","sku": "354","description": "Chicken Sandwich","quantity": 1},{"orderLineNumber": 2,"amount": 395,"currency": "USD","sku": "355","description": "Diet Coke","quantity": 1}],"payment": [{"type": "GIFT","orderLineNumber": 3,"amount": 1000,"currency": "USD"},{"type": "CREDIT","orderLineNumber": 4,"amount": 382,"currency": "USD"}]

}



Description Example




order Yes A host-generated order ID; Used for voids and adjust-order. 160430370000176048

sva Yes The masked version of the stored value account XXXXXXXXXXXXXXX0001



true







owed Yes An amount still owed following the redemption. In cases ofinsufficient funds this will be non-zero; see owed

USD 278


6. Archer Certification Mode example success responses

6.1. Activate / cm

(sva 6277200000000001, amount 1000 USD)

{[ "notes":"*** Certification test server ***\n*** Certification test server ***", "sva.status":"ACTIVE", "status.name":"OK", "sva.balances":"Points 0,USD 1100", "sva.detailedBalances":[ "balances":[ ["amount":1100, "currency":USD, "expirations":[], "formatted":"11.00" ] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status:AVAILABLE"] ], "loyalty":[ ["amount":0, "currency":"Points", "expirations":[], "formatted":"0", "threshold":20] ] ], "sva.registered":true, "status.description":"The request has succeeded", "rewards":"USD 100", "status.code":"200", "order":"940235105298120010", "sva":"XXXXXXXXXXXX0001"]}

6.2. Load / cm

(sva 6277200000000001, amount 2000 USD)


{[ "notes":"*** Certification test server ***\n*** Certification test server ***", "sva.status":"ACTIVE", "status.name":"OK", "sva.balances":"Points 8,USD 3200", "sva.detailedBalances":[ "balances":[ ["amount":3200, "currency":USD, "expirations":[], "formatted":"32.00" ] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status:AVAILABLE"] ], "loyalty":[ ["amount":8, "currency":"Points", "expirations":[], "formatted":"8", "threshold":20] ] ], "sva.registered":true, "status.description":"The request has succeeded", "rewards":"USD 200", "status.code":"200", "order":"277008899094870040", "sva":"XXXXXXXXXXXX0001"]}

6.3. Redeem / cm

(sva 6277200000000001, amount 1000 USD)


{[ "notes":"*** Certification test server ***\n*** Certification test server ***", "owed":"USD 0", "sva.status":"ACTIVE", "status.name":"OK", "sva.balances":"Points 18,USD 0", "sva.detailedBalances":[ "balances":[ ["amount":0, "currency":USD, "expirations":[], "formatted":"0.00" ] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status:AVAILABLE"] ], "loyalty":[ ["amount":18, "currency":"Points", "expirations":[], "formatted":"18", "threshold":20] ] ], "sva.registered":true, "status.description":"The request has succeeded", "rewards":"Points 10", "status.code":"200", "order":"603513772040110050", "sva":"XXXXXXXXXXXX0001"]}

6.4. Balance Inquiry / cm

(sva 6277200000000001)


{[ "notes":*** "Certification test server ***\n*** Certification test server ***", "sva".status":"ACTIVE", "status.name":"OK", "sva.balances":"USD 1000,Points 8", "sva.detailedBalances":[ "balances":[ ["amount":1000, "currency":USD, "expirations":[], "formatted":"10.00" ] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status:AVAILABLE"] ], "loyalty":[ ["amount":8, "currency":"Points", "expirations":[], "formatted":"8", "threshold":20] ] ], "sva.registered":true, "status.description":"The request has succeeded", "rewards":"Points 8", "status.code":"200", "sva":"XXXXXXXXXXXX0001"]}

6.5. Void / cm

(order id 120100010000000060)


{[ "void.amount":500, "notes":"*** Certification test server ***\n*** Certification test server ***", "sva.status":"ACTIVE", "void.action":"redeem", "void.currency":"USD", "status.name":"OK", "sva.balances":"USD 1500,Points 8", "sva.detailedBalances":[ "balances":[ ["amount":1500, "currency":USD, "expirations":[], "formatted":"15.00" ] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status:AVAILABLE"] ], "loyalty":[ ["amount":8, "currency":"Points", "expirations":[], "formatted":"8", "threshold":20] ] ], "sva.registered":"true", "status.description":"The request has succeeded", "status.code":"200", "order":"120100010000000060", "sva":"XXXXXXXXXXXXXXX0001"]}

6.6. Reverse / cm

(request id 1)

{[ "reversal":"1", "status.name":"OK", "status.description":"The request has succeeded", "status.code":"200"]}

6.7. Transfer / cm

("to" sva 6277200000000002)


{[ "sva.status":"ACTIVE", "status.name":"OK", "sva.balances":"USD 1000,Points 8", "sva.detailedBalances":[ "balances":[ ["amount":1000, "currency":USD, "expirations":[], "formatted":"10.00" ] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status:AVAILABLE"] ], "loyalty":[ ["amount":8, "currency":"Points", "expirations":[], "formatted":"8", "threshold":20] ] ], "sva.registered":true, "status.description":"The request has succeeded", "status.code":"200", "sva":"XXXXXXXXXXXX0002"]}

6.8. Reward / cm

(account alias 5035550120)


{[ "notes":"*** Certification test server ***\n*** Certification test server ***", "sva.status":"ACTIVE", "status.name":"OK", "sva.balances:":"Points 28,USD 1000", "sva.detailedBalances":[ "balances":[ ["amount":1000, "currency":USD, "expirations":[], "formatted":"10.00" ] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status:AVAILABLE"] ], "loyalty":[ ["amount":28, "currency":"Points", "expirations":[], "formatted":"28", "threshold":20] ] ], "sva.registered":true, "status.description":"The request has succeeded", "rewards:"Points 20", "status.code":"200", "order":"137959541378650060", "sva":"XXXXXXXXXXXXXXX0001"]}

6.9. Rewards Info / cm

{[ "program.description":"A fantastic rewards program brought to you by Heartland.", "program.flavor":"Visit", "program.threshold":10, "program.name":"Heartland Rewards", "program.url":"https://heartlandgiftcard.com/", "status.name":"OK", "status.description":"The request has succeeded", "status.code":"200" ]}

6.10. Create Alias / cm

(account alias 5035550101)

{[ "alias":"5035550101", "sva":"5022440000000000001", "pin":"12345", "status.name":"OK", "status.description":"The request has succeeded", "status.code":"200", ]}


6.11. Add Alias and Remove Alias / cm

(alias 5035550101, sva 6277200000000001)

{[ "alias":"5035550101", "sva":"6277200000000001", "status.name":"OK", "status.description":"The request has succeeded", "status.code":"200", ]}

6.12. Deactivate / cm

(sva 6277200000000001)

{[ "sva.status":"NEW", "status.name":"OK", "sva.balances":"USD 0,Points 0", "sva.detailedBalances":[ "balances":[ ["amount":0, "currency":USD, "expirations":[], "formatted":"0.00" ] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status:AVAILABLE"] ], "loyalty":[ ["amount":0, "currency":"Points", "expirations":[], "formatted":"0", "threshold":20] ] ], "sva.registered":"false", "status.description":"The request has succeeded", "status.code":"200", "sva":"XXXXXXXXXXXX0001"]}

6.13. Greet / cm

(sva 6277200000000001, order info ALL)


[ "notes":"*** Certification test server ***\n*** Certification test server ***", "rewards":"Points 8", "status.code":"200", "status.description":"The request has succeeded", "status.name":"OK", "sva":"XXXXXXXXXXXX0001", "sva.balances":"USD 1000,Points 8", "sva.detailedBalances":[ "balances":[ ["amount":1000, "currency":"USD", "expirations":[], "formatted":"10.00"] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status":"AVAILABLE"] ], "loyalty":[ ["amount":8, "currency":"Points", "expirations":[], "formatted":"8", "threshold":20] ] ], "sva.registered":true, "sva.status":"ACTIVE", "user.custom":[]]

6.14. Cashout / cm

(sva 6277200000000001, amount 1000 USD)


{[ "amount":"USD 1000", "notes":"*** Certification test server ***\n*** Certification test server ***", "sva.status":"ACTIVE", "status.name":"OK", "sva.balances":"Points 8,USD 0", "sva.detailedBalances":[ "balances":[ ["amount":0, "currency":"USD", "expirations":[], "formatted":"0.00"] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status":"AVAILABLE"] ], "loyalty":[ ["amount":8, "currency":"Points", "expirations":[], "formatted":"8", "threshold":20] ] ], "sva.registered":true, "status.description":"The request has succeeded", "status.code":"200", "order":"358206967610100020", "sva":"XXXXXXXXXXXX0001"]}

6.15. Compute Loyalty / cm

Request:


{[ {"lineItem":[ {"orderLineNumber":1, "amount":875, "currency":"USD", "sku":"Burger", "description":"Flame Broiled Whopper", "quantity":1} ], "terminal":"0001", "tip":300, "currency":"USD", "terminal.version":"qa-framework", "payment":[ {"type":"CASH", "orderLineNumber":2, "amount":2000, "currency":"USD"} ], "terminal.order":"1559080790830-1", "acquired":"SWIPE", "amount":2000, "store":"auto01", "domain":"computeloyaltyce", "tax":180, "sva":"6277200000000001", "request":"1559080790834-2"}]}

Response:


{[ "notes":"*** Certification test server ***\n*** Certification test server ***", "order":"444147854286300030", "rewards":"Points 15", "status.code":"200", "status.description":"The request has succeeded", "status.name":"OK", "sva":"XXXXXXXXXXXX0001", "sva.balances":"Points 23,USD 3000", "sva.detailedBalances":[ "balances":[ ["amount":3000, "currency":USD, "expirations":[], "formatted":"30.00" ] ], "discounts":[ ["currency":"Free taco", "description":"Small chicken taco", "redemption.end":"2038-01-01T12:00:00Z", "redemption.start":"2018-01-01T12:00:00Z", "status:AVAILABLE"] ], "loyalty":[ ["amount":23, "currency":"Points", "expirations":[], "formatted":"23", "threshold":20] ] ], "sva.registered":true, "sva.status":"ACTIVE", "user.custom":[]]

7. Appendices

7.1. Appendix A - Parameter Reference

7.1.1. domain

Description A Xenial or Heartland-assigned identifier to distinguish processing environments.

Format Alphanumeric

Max Length 16 chars

Examples hps

Notes Clients should make this a configurable parameter

7.1.2. chain

Description A Xenial or Heartland-assigned identifier to distinguish merchants

Format Alphanumeric

Max Length 25


Examples 301 130909013158178

DomainProgram

Notes Needed by global partners to send requests on behalf of a group of merchants

7.1.3. store

Description Identifies a unique merchant location. This value may or may not be assigned by Xenial or Heartland.

Format Alphanumeric

Max Length 50 chars

Examples 00001


7.1.4. terminal

Description Identifies a unique terminal within a store. This value may or may not be assigned by Heartland.

Format Alphanumeric

Max Length 25 chars

Examples 001


7.1.5. request

Description A client-generated token to uniquely identify an individual request. This token must be globally unique by store and terminal. That is, every request from an individual terminal in a store should have a unique request identifier or else the request willreceive an error. In the event the client does not receive a response (timeout) or if the client receives a response with a status code of 5xx, thisrequest identifier will be used to perform a timeout reversal.

Format Alphanumeric

MaxLength

50 chars

Examples 20301231235959-0001

Notes To help ensure uniqueness, it is a good idea to utilize a timestamp as part of the request identifier.

7.1.6. sva

Description Identifies the Stored Value Account. The value passed for this parameter can be a Stored Value Account Number, track data from the magnetic stripe on a swiped card, or an alias (such as a phone number) that references a Stored ValueAccount. Archer's intelligent parser knows how to automatically determine the type of SVA data presented and process the parametercorrespondingly.

Format Alphanumeric

MaxLength

512

Examples 6277200000000001 %B6277200000000001^HEARTLAND PAYMENT SYSTE^37829821000123456789?

B6277200000000001^HEARTLAND PAYMENT SYSTE^37829821000123456789 ;6277200000000001=391200012345?

6277200000000001=3912000123455035551212


Notes

7.1.7. acquired

Description Identifies how a Stored Value Account identifier was acquired. This parameter is used to control program behavior

on the host.

Format Enumerated set of alphanumeric values

Max Length N/A

Examples SWIPE

Notes The complete set of values is provided in the section entitled .Acquired Type Values

7.1.8. amount

Description Identifies the amount of a financial transaction. This parameter always expects an implied decimal point for the associated currency. For example, for the USD currency has an implied decimal point as if it were rendered as 1000 10.00

representing ten dollars USD. The location of the implied decimal point is currency-specific.

Format Numeric

Max Length N/A

Examples 1000

Notes

7.1.9. currency

Description Identifies the currency of a financial transaction. Can be an ISO 4217 Currency Code identifier (a three letter code) such as , , , , , or , , or a discount code / coupon code such as USD CAD MXN EUR GBP AUD NZD Points D001(POS-specific).

Format Alpha

MaxLength

20

Examples USD Points

D001

Notes

7.1.10. pin

Description The numeric pin associated with a stored value account. The pin is typically only required when redeeming from an accountusing an alias such as a phone number.

Format Numeric

MaxLength

10

Examples 123456

Notes Account pins are 4 to 8 digits long, but can be longertypically

7.1.11. tax

Description The portion of the request's that represents tax, if applicable.amount


Format Numeric

Max Length N/A

Examples 89

Notes

7.1.12. tip

Description The portion of the request's that represents a tip, if applicable.amount

Format Numeric

Max Length N/A

Examples 200

Notes

7.1.13. exclude

Description The portion of the request's that should be excluded from rewards. Does include tip or tax.amount not

Format Numeric

Max Length N/A

Examples 1000

Notes Some states require the exclusion of alcohol, tobacco, and certain other items.

7.1.14. order

Description Identifies a transaction (aka order) that was successfully processed by the host platform. Every successfully processedtransaction that changes the state of a stored value account that can be voided is assigned a unique ID by the XenialorderStored Value Platform host.

Format Numeric

MaxLength

19

Examples 140000000000000001

Notes

7.1.15. reversal

Description Identifies a prior transaction that was not successfully processed because of a network timeout. The value specified in this fieldshould be the value specified in the field of the transaction to be reversed.request

Format Alphanumeric

MaxLength

50

Examples 20301231235959-0001

Notes

7.1.16. alias

Description An alternate identifier used to reference a stored value account. The alias is typically a phone number in most merchantprograms.


Format Alphanumeric

MaxLength

100

Examples 5035551212

Notes

7.1.17. status.code

Description The HTTP response code. Codes in the range represent success, codes in the range represent an application error,2XX 4XXand codes in the range represent a system error. Every attempt is made to align the HTTP response code to our host errors5XXas closely as possible.

Format Numeric

MaxLength

3

Examples 200 400

500

Notes An exhaustive list of errors is provided in Appendix C - Errors

7.1.18. status.name

Description A short, descriptive name for a specific error condition. More than one unique may share the same status.name. For example, a large number of unique error conditions all share .status.code status.code 400

Format Alphanumeric

MaxLength

100

Examples Okay AccountNotFound

InsufficientFunds

Notes An exhaustive list of errors is provided in Appendix C - Errors

7.1.19. status.description

Description A long, descriptive name for a specific error condition. It is not intended to be machine parseable but is instead intended to bedisplayed to the end-user in some fashion, e.g. on a POS screen, on a receipt, on a webpage, etc.

Format Alphanumeric

MaxLength

256

Examples Unknown account [XXXXXXXXXXXX0001].The order [140000000000000001] has already been voided.

Notes

7.1.20. account

Description Identifies a stored value account that was involved in an alias request.

Format Numeric

Max Length 19

Examples 6277200000000001


Notes

7.1.21. alias

Description An alternate identifier used to reference a stored value account. The alias is typically a phone number in most merchantprograms.

Format Alphanumeric

MaxLength

100

Examples 5035551212

Notes

7.1.22. sva.status

Description Identifies the status of a stored value account.

Format Alphanumeric

Max Length

Examples ACTIVE

Notes The complete set of values is provided in the section entitled .Account Status Values

7.1.23. sva.registered

Description Identifies whether a stored value account is registered to a user profile or not.

Format Boolean

Max Length 5

Examples truefalse

Notes

7.1.24. sva.balances

Description Returns the balances for all currencies on the stored value account that are supported by a merchant. The balances areencoded as follows:

$currency $amount,$currency $amount

Each currency pair is separated by a comma, and the currency is separated from its amount by a single space.

Format Alphanumeric

MaxLength

100

Examples USD 1000,Points 7

Notes

7.1.25. sva.detailedBalances


Description Returns the gift and loyalty balances for all currencies on the stored value account that are supported by a merchant.

The array contains gift balances using a ISO 4217 Currency Code identifier and, depending on the merchant, maybalancescontain balances for multiple currencies (e.g. "USD", "CAD", "EUR").

The array typically contains a single loyalty currency (e.g. "Points", "Stars", "Punches") and also contains progressloyaltyinformation towards the next reward as well as the loyalty program flavor. See flavor and threshold for more information.

The array contains any coupons or discounts that are/were available for redemption. The currency for eachdiscountsavailable coupon or discount correlates with the discount code configured in the POS. Each entry has an implied amount=1, sothere will be multiple entries if a consumer can use a discount more than once. The availability of a discount is represented by

. Discounts with a limited redemption window also include and . discount.status redemption.start redemption.end

Depending on the type of stored value account, some of the arrays may be empty. For example, a card designed to store only asingle coupon will have empty arrays for both "balances" and "loyalty". Likewise, a simple gift card with no loyalty program willhave an empty "loyalty" array. Lastly, if a stored value account does not have any available coupons or discounts, the"discounts" array will be empty.

This field is preferred over "sva.balances" for rich integrations.strongly

Format Array of JSON objects

MaxLength


Examples

"balances":[ { "currency":"USD", "amount":500, "formatted":"5.00", "expirations":[] } ],"loyalty":[ { "currency":"Points", "amount":5, "formatted":"5", "threshold": 10, "flavor": "VISIT", "expirations":[] }, ],"discounts":[ { "currency":"D0001", “status”: “REDEEMED”, "description": "Free Coke", “redemption.end”: “2018-06-30T00:00:00Z” }, { "currency":"D0001", “status”: “AVAILABLE”, "description": "Free Coke", }, { "currency":"D0002", “status”: “FUTURE”, "description": "Free Appetizer", “redemption.start”: “2020-07-01T00:00:00Z”, “redemption.end”: “2020-07-30T00:00:00Z” }, { "currency":"D0003", “status”: “EXPIRED”, "description": "Free Taco", “redemption.end”: “2017-06-30T00:00:00Z” } ]

Notes This detailed information is only available in JSON responses.

7.1.25.1. currency

Description Identifies the currency of a financial transaction. Can be an ISO 4217 Currency Code identifier (a three letter code) such as , , , , , or , a loyalty Currency identifier such as or , or aUSD CAD MXN EUR GBP AUD NZD Points Starsdiscount code / coupon code such as (POS-specific).D001

Format Alpha

MaxLength

20

Examples USD Points

D001

Notes

7.1.25.2. amount


Description Identifies the amount of a financial transaction. This parameter always expects an implied decimal point for the associated currency. For example, for the USD currency has an implied decimal point as if it were rendered as 1000 10.00

representing ten dollars USD. The location of the implied decimal point is currency-specific.

Format Numeric

Max Length N/A

Examples 1000

Notes

7.1.25.3. threshold

Description Indicates the loyalty amount needed to obtain a reward in the loyalty program.

Format Numeric

Max Length N/A

Examples 20

Notes Value may be 0 if a progress hint is not available or defined for the loyalty program.

7.1.25.4. flavor

Description Indicates a hint for rendering the progress towards the next reward in a loyalty program. The set of values is enumerated in theExamples section.

tracks the number of qualified visits to earn a reward.VISIT tracks the amount of qualified spend to earn a reward.SPEND

tracks qualifying stored value loads to earn a reward.LOAD tracks the number of punches (item purchases) required to earn a reward.PUNCH

tracks the amount of qualified Points earned for redemption.POINTS

VISIT and are typically represented like punches on a virtual card (or checkboxes). , , and are typically representedPUNCH SPEND LOAD POINTSwith a progress meter.

Format Alphanumeric

MaxLength

Examples VISIT SPEND

LOAD PUNCH

POINTS

Notes Value is empty for non-applicable currencies. When present provides hints on how progress could be conveyed to the user, e.g.icons, progress bars, etc.

7.1.26. orders

Description An optional response parameter that provides details of the last three COMPLETED compute/loyalty orders.

Format JSON; list of orders, each of which contains the order id and a complete list of lineItems (orderLineNumber, sku, description,quantity).


Examples

{"orders":[ {"id":"120103680000003787", "lineItems":[ {"orderLineNumber":1, "description":"Chicken Sandwich", "quantity":2,"sku":"CS9446R1"}, {"orderLineNumber":2, "description":"20 oz Coke", "quantity":1, "sku":"CK8773R2"} ]}, {"id":"120103680000003789", "lineItems":[ {"orderLineNumber":2, "description":"Tofu Platter", "quantity":1,"sku":"TS543S11"}, {"orderLineNumber":3, "description":"20 oz Coke", "quantity":1, "sku":"CK8773R2"} ]}, {"id":"120103680000003791", "lineItems":[ {"orderLineNumber":1, "description":"Chicken Sandwich", "quantity":1,"sku":"CS9446R1"}, {"orderLineNumber":2, "description":"16 oz Root Beer", "quantity":1,"sku":"RB7652U8"} ]}]}

Notes A maximum of three orders are supplied, depending on availability. Tax, tip and NULL skus are not returned in the line items.

7.1.27. notes

Description Contains rewards messages to be displayed on a receipt, mobile app, or web page to inform an account holder about specialrewards or promotions that have executed on the account. The note text is simply a long, url-encoded string. The note text may contain zero or more instances of the two-character string " " (0x5C 0x6E). This is a newline character\n not(0x0A) but a backslash followed by the 'n' character. Well-written clients look for this two-character string and replace it with theappropriate line-break symbol for the target platform. For example, websites would turn those characters into a " " string while Unix clients would turn it into (0x0A) and<br/> '\n'Windows clients would turn it into (0x0D0A)."\r\n"

Format Alphanumeric

MaxLength

4096

Examples Congratulations! You have just earned $1\nfor loading $10 or more onto your account!

Notes

7.1.28. rewards

Description An optional response parameter that identifies any currency-based rewards added to the account as a result of a transaction.The list of rewards are encoded as follows:

$currency $amount,$currency $amount

Each currency pair is separated by a comma, and the currency is separated from its reward amount by a single space.The rewarded currencies can be of either of the currency types, gift ("balances"), "loyalty", or "discounts".

Format Alphanumeric

MaxLength

100

Examples USD 100,Points 1

Notes


7.1.29. void.action

Description Identifies the action of the transaction being voided, whether it was a , , etc.load redeem

Format Alphanumeric

Max Length 100

Examples loadredeem

Notes

7.1.30. terminal.order

Description A terminal-generated order number. Used for reporting, to associate related transactions to each other (split tender, tip adjust,redeem/reward, etc.).

Format Alphanumeric

MaxLength

50

Examples 017809F

Notes

7.1.31. terminal.version

Description The software version running on the terminal or POS.

Format Alphanumeric

Max Length 50

Examples Cyberdyne T-1000HAL 9000

Notes

7.1.32. owed

Description After a redemption, the amount still owed by the customer. Typically this will be , but in cases of insufficient funds it will beUSD 0a non-zero amount. It will always be encoded as a pair.$currency $amount

Format Alphanumeric

MaxLength

100

Examples USD 278USD 0

Notes

7.1.33. partial

Description Specifies whether the host should accept a partial redemption or not. A partial redemption is where the balance for an account isnon-zero but insufficient to cover the full redemption amount. If partial redemption is enabled by setting the parameter value totrue, the balance is drained and the amount owed is returned so that an additional payment in any acceptable form of tendermay be accepted. If partial redemption is disabled, then the full amount must be covered by the balance or the entire transactionfails.

Format Boolean


MaxLength

N/A

Examples truefalse

Notes

7.1.34. clerk

Description Identifies an individual clerk or server. Typically used on POS systems in which individual users must log in before processingtransactions.

Format Alphanumeric

MaxLength

50

Examples 17John Connor

Notes

7.1.35. coupon

Description Identifies the Coupon. The value passed for this parameter can be a Coupon ID,

track data from the magnetic stripe on a swiped card.

Format Alphanumeric

Max Length 512

Examples 349865984653 %B349865984653^^380100033158ARCHER?

B349865984653^^380100033158ARCHER ;349865984653=380100033158ARCHER?

349865984653=380100033158ARCHER

Notes

7.1.36. coupon.status

Description Identifies the status of a coupon.

Format Alphanumeric

Max Length

Examples ACTIVE

Notes The complete set of values is provided in the section entitled .Account Status Values

7.1.37. coupon.description

Description Description of the coupon

Format Alphanumeric

Max Length 64

Examples Free Appetizer50% off Entree

Notes


7.1.38. coupon.balances

Description Returns the coupon balances that are supported by a merchant. The balances are encoded as follows:

$couponType $amount,$couponType $amount

Each couponType pair is separated by a comma, and the couponType is separated from its amount by a single space.

Format Alphanumeric

Max Length 100

Examples D0001 1,D0002 1

Notes

7.1.39. payment.type

Description Identifies the types of payments in an Order/Adjust Order.

Format Alphanumeric

Max Length

Examples CASH

Notes The complete set of values is provided in the section entitled .Payment Type Values

7.1.40. user.custom

Description Custom, merchant-defined fields associated with a consumer.

Format JSON document

Max Length

Examples

[ { "name": "Favorite Store", "value": "123" }, { "name": "First Car", "value": "Toyota Camry" }]

Notes

7.1.41. redemption.start

Description Specifies start time of the amount available for redemption. If this is specified, then the amount can be redeemed only after thestart time. This is enforced by the host using the local time zone of the store identified in the request. It is not the responsibility ofthe client to enforce this. This is only provided for informational and presentation purposes.

Format ISO 8601 Date

MaxLength

N/A

Examples 2018-08-01T00:00:00Z2018-12-01T:10:00:00Z

https://en.wikipedia.org/wiki/ISO_8601


Notes

7.1.42. redemption.end

Description Specifies end (expiration) time of the amount available for redemption. If this is specified, then the amount can only be redeemedbefore the end time. This is enforced by the host using the local time zone of the store identified in the request. It is not theresponsibility of the client to enforce this. This is only provided for informational and presentation purposes.

Format ISO 8601 Date

MaxLength

N/A

Examples 2018-10-31T00:00:00Z2018-11-30T:10:00:00Z

Notes

7.1.43. promotional

Description Specifies if the amount being loaded/activated is a promotional amount or not. If an amount is promotional, then the accountholder did NOT pay for that amount.

Format Boolean

MaxLength

5

Examples truefalse

Notes

7.1.44. orderInfo

Description Specifies whether or not to include additional information about the last three orders.

Format Enumerated set of alphanumeric values

Max Length 3

Examples ALL

Notes The complete set of values is provided in the section entitled .Order Info Values

7.1.45. discount.status

Description Identifies the availability of a discount for redemption.

Format Alphanumeric

Max Length N/A

Examples FUTURE AVAILABLE

EXPIRED REDEEMED

ADJUSTED

Notes

https://en.wikipedia.org/wiki/ISO_8601


7.2. Appendix B - Enumerated Values

7.2.1. Acquired Type Values

The complete set of supported Acquired Types are provided below and are case-sensitive.

Value Description

SWIPE Identifies acquisition by a magnetic stripe reader when "swiping" a card

MANUAL Identifies acquisition by manually entering an account number via a number pad

INTERNET Identifies acquisition directly from an account holder over the internet, such as through an e-commerce website

TAP Identifies acquisition from an RFID or NFC tap

BLUETOOTH Identifies acquisition via a bluetooth acquiring device

SCAN Identifies acquisition from a 2D Barcode or QR Code scanning device

WIRELESS Identifies acquisition from a wireless device not previously specified

VOICE Identifies acquisition directly from an account holder over the phone

OTHER Identifies acquisition from any other means not previously specified

7.2.2. Account Status Values

The complete set of supported Account Status values are provided below and are case-sensitive.

Value Description

NEW Identifies a new account that has no balance and is available for purchase

ACTIVE Identifies an active account that has been activated and used

FROZEN Identifies an account that is disabled from further use until unfrozen (typically because of suspicion of fraud)

NEWFROZEN Identifies an account that is disabled from further use until unfrozen and returned to statusNEW

CLOSED Identifies an account with no balance that is permanently no longer available for use

7.2.3. Payment Type Values

The complete set of supported Payment Type values are provided below and are case-sensitive.

Value Description

CASH Cash Payment

CREDIT Credit card Payment

DEBIT Debit card Payment

ACH ACH Payment

FOODSTAMP Food stamp Payment

CASHBENEFIT Cash benefit Payment

Purchase Order Purchase Order Payment

7.2.4. Discount Status Values

The complete set of supported Discount Status values are provided below and are case-sensitive.


Value Description

FUTURE The discount cannot be redeemed until redemption.start

AVAILABLE The discount is available for redemption

EXPIRED The discount can no longer be redeemed because has passedredemption.end

REDEEMED The discount was successfully redeemed by the consumer

ADJUSTED Reserved, not yet implemented/used

7.2.5. Order Info Values

The complete set of supported Order Info values is provided below. These are case-sensitive.

Value Description

NONE No order information is supplied

IDS Ids only

ALL Ids plus additional order details are supplied


7.3. Appendix C - Errors

7.3.1. HTTP errors

Standard HTTP errors, see for others. All 5xx error codes must be reversed (automatic with the Xenial-provided archer-client jar).HTTP spec

Status Code Status Name

401 Unauthorized

403 Forbidden

404 NotFound

500 InternalServerError

503 ServiceUnavailable

7.3.2. Application errors

A collection of application and system errors that may be returned by the Archer host.

Status Code Status Name

400 AccountCreationNotAllowed

400 AccountNotActivated

400 AccountNotFound

400 AccountOrderMismatch

400 ActivateAccountMaxCountExceeded

400 ActivateNotAllowed

400 AddValueMaxAmountExceeded

400 AddValueMaxCountExceeded

400 AddValueNotAllowed

400 AliasNotAvailable

400 AlreadyVoided

400 ApiError

400 AppAlert

400 BalanceLimitExceeded

400 BalanceNotApplicable

400 BankCardNotFound

400 BatchAlreadyReleased

400 BulkOperationNotAllowed

400 BulkOperationPending

400 BulkResolveTipLimitExceeded

400 CannotCashout

400 CannotReprocessOrder

400 CardAuthorizationFailed

400 ChainNotFound

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html


400 CloseNotAllowedForUser

400 CurrencyConverterNotFound

400 CurrencyFactorOutOfRange

400 DeactivateNotAllowed

400 DebitCardVoidAuthorizationMissing

400 DereferenceFailureException

400 ForcedOrderFailure

400 ForcedOrderFailureAlert

400 FreezeNotAllowedForUser

400 GenericForcedOrderFailure

400 GroupNotFound

400 InsufficientActivationAmount

400 InsufficientFunds

400 InsufficientLoadAmount

400 InsufficientValueInStore

400 InvalidActivationAmount

400 InvalidBusinessDayBoundary

400 InvalidCardNumber

400 InvalidCardVerification

400 InvalidChainName

400 InvalidDomainName

400 InvalidExpiration

400 InvalidGroupName

400 InvalidLastFour

400 InvalidOptInType

400 InvalidPassword

400 InvalidPaymentType

400 InvalidPin

400 InvalidProgram

400 InvalidRange

400 InvalidSellerProfileId

400 InvalidTokenAction

400 LineItemNotFound

400 LoadCardWithCardDisallowed

400 MakePaymentMaxCountExceeded

400 ManagedThreadsException

400 MaxRequestDurationExceeded

400 MergeAccountStatusNotAllowed

400 MissingCvv2


400 MissingData

400 MissingOrderProcessingAccount

400 MissingSellerProfileId

400 NegativeAddValue

400 NoAccountForProfile

400 NoAccountsInRange

400 NoAssociatedCardAccount

400 NonPositiveStoredValuePayment

400 NonUniqueLineNumbers

400 ObjectNotFound

400 OrderEditFailed

400 OrderExists

400 OrderNotFound

400 PaymentTypeLimitExceeded

400 PinRequiredForRedemption

400 ProfileAlreadyExists

403 ProfileAuthorizationFailed

403 ProfileClosed

403 ProfileFrozen

403 ProfileNotFound

400 ProfileReferenceNotFound

400 ProgramDisallowsTransfer

400 ProgramDisallowsTransferToExistingAccount

400 ProgramMismatch

400 ProgramNotFound

400 PromoProgramChangeNotAllowed

400 PromoProgramExpired

400 RangeNotFound

400 RedemptionAcquiredPolicyNotMet

400 ReferenceUnavailable

400 RegistrationMismatch

400 RegistrationNotAllowed

400 RegistrationRequired

400 RegistrationRequiredToMerge

400 RegistrationRequiredToTransfer

400 RegistrationStatusNotAllowed

400 RequestNotFound

400 StateChangeNotAllowed

400 SvaRefParseException


400 TipBelowAmount

400 TokenExpired

400 TokenNotFound

400 TooLateToDeactivate

400 TooLateToVoid

400 TooManyOrderProcessingAccounts

400 TooManyPromosForProgram

400 TooManyStoredValuePayments

400 TooOldToVoid

400 TransferAccountStatusNotAllowed

400 TransferFrozen

400 TransferToSameAccountNotAllowed

400 UnableToCreateAccountReference

400 UnequalChargesAndPayments

400 UnfreezeNotAllowed

400 UnrecognizedCreditCardNumber

400 UnrecognizedCreditCardType

400 UnresolvableStore

400 ValueLimitExceeded

400 ValueStoreMismatch

400 ValueStoreNotActive

400 ValueStoreNotSupported

400 VelocityLimitExceeded

400 XmlException


7.4. Appendix D - Certification Host Response Matrix

The Archer Certification Host provides a way to force responses based on user input, typically an or . This allows a client developeramount svato test various transaction scenarios by simply using well-chosen input values.

7.4.1. Amount Response Matrix

Responses to , , , and requests can be controlled by the parameter.activate load redeem reward amount

All whole dollar amounts (e.g. , , , etc) will return a status code of and status name of . All non-whole dollar amounts (any100 200 1000 200 Okayamount that does not end in "00") will return some form of an error response (status code of or ). The request amounts enumerated in the4XX 5XXtable below will cause the corresponding error response to be returned. These request amounts will return the corresponding response for allcurrencies, including Points.

Amount Status Code Status Name

101 503 ServiceUnavailable

201 403 ProfileAuthorizationFailed

202 403 ProfileClosed

203 403 ProfileNotFound

204 403 ProfileFrozen

301 400 InsufficientFunds

302 400 InsufficientActivationAmount

303 400 InsufficientLoadAmount

304 400 InvalidPaymentType

305 400 InvalidPin

306 400 InvalidSellerProfileId

307 400 OrderExists

308 400 RegistrationRequired

309 400 AccountNotActivated

310 400 AccountNotFound

311 400 CannotCashout

500 200 OK (However, returned order.id will be "TooLateToVoid"

600 200 OK (However, returned order.id will be "OrderNotFound"

7.5. Appendix E - Certification Host Stored Value Accounts

All account numbers in the following ranges:

Start of Range End of Range

6277200000000001 6277200000000099

5022440000000000001 5022440000000000099

All aliases (phone numbers) in the following ranges:

Start of Range End of Range

XXX5550100 XXX5550199


You may use whatever area code (NPA) you would like, but the exchange (NXX) must be and the line must be in the range - or555 0100 0199the host will reject the alias with an error.AccountNotFound

7.6. Appendix F - Code Samples

This section provides some simple examples of using the Archer API to do a transaction in a variety of languages.load

7.6.1. Curl

curl https://api2.cert.chockstone.com/archer/v2/load \-iu test_user:test_password \-X POST \-d domain=test \-d request=201212312359590001 \-d store=0001 \-d terminal=0001 \-d sva=6277200000000001 \-d acquired=MANUAL \-d amount=1000 \-d currency=USD

Note: In practice, parameters should be url-encoded, so the argument should be used in place of . The version above--data-urlencode -dwas used to make the sample easier to read.


7.6.2. Java

The following Java code snippet demonstrates how easy it is to integrate with the Archer platform using the Xenial-provided archer-client.


import com.hps.archer.util.StatusException;import com.hps.archer.v1.client.ArcherClient;import com.hps.archer.v1.client.ArcherClient.Acquired;

import java.util.Map;import java.util.List;

import java.net.MalformedURLException;

...

String tmpDir = "/var/tmp/archer-client";

String endpoint = "https://api2.cert.chockstone.com";String user = "test_user";String password = "test_password";String domain = "test";String store = "1000";String terminal = "001";String terminalVersion = "testTerminal";int terminalOrder = 0;

ArcherClient client = null;try {client = new ArcherClient(tmpDir, endpoint, user,password, domain, store, terminal, terminalVersion);} catch(MalformedURLException e) {// handle error}

Map<String, String> response = null;Map<String, Integer> balances = null;Map<String, Integer> rewards = null;List<String> notes = null;try {// load $10.00 USD onto account 6277200000000001response = client.load("6277200000000001", Acquired.MANUAL, "USD",1000, String.valueOf(++terminalOrder));

balances = ArcherClient.getBalances(response);rewards = ArcherClient.getRewards(response);notes = ArcherClient.getNotes(response);

// print balancesSystem.out.println("Balances:");for (String currency : balances.keySet()) {System.out.println(currency + ": " + balances.get(currency));}

// print rewardsSystem.out.println("Rewards:");for (String currency : rewards.keySet()) {System.out.println(currency + ": " + rewards.get(currency));}

// print notesSystem.out.println("Notes:");for (String note : notes) {System.out.println(note);}

} catch (StatusException e) {// handle error}

// print out all response datafor (String key : response.keySet()) {System.out.println(key + " = " + response.get(key));}


7.7. Appendix G - HTTP headers

7.7.1. Content-type

Description Specifies the encoding type used in an Archer .request

Format Alphanumeric

Max Length N/A

Examples application/x-www-form-urlencodedapplication/json

Notes If not specified, is assumed.application/x-www-form-urlencoded

7.7.2. Accept

Description Specifies the encoding type desired in an Archer .response

Format Alphanumeric

Max Length N/A

Examples application/x-www-form-urlencodedapplication/json

Notes If not specified, will be used.application/x-www-form-urlencoded

archer developer guide v2

Documents