How-to Guide - Rest API - Gift Cards
Gift Card API
This section provides examples and explanations of the Enactor Card Authorisation Service, used to provide Gift Card (Stored Value Card) functionality. The purpose is to allow third party applications to use the Enactor Gift Card capabilities. Following is the list of Gift Card APIs covered in this section:
-
Activate / Issue new Gift Card.
-
Gift Card Balance Enquiry.
-
Gift Card Top Up.
-
Gift Card Payment Request.
-
Gift Card Payment Reversal Request.
General Notes
This section will cover the Estate Manager configurations that need to be done, importing of existing Gift Cards, and the API structure for the requests and responses of the Gift Card services.
Estate Manager Configurations
The example Gift Card APIs in this document will work only if the following configuration has been carried out on the Enactor Estate Manager (and distributed to the Authorisation Servers if they do not share the same database).
Note: These configurations are part of Enactor's Standard Configurations.
| Configuration Area | Details | Notes |
|---|---|---|
| Gift Card Type | Gift Card Type ID: GC_UK Region: United Kingdom  | Multiple Gift Card types may be maintained where there are different business rules, or where cards are valid in one region/fascia and not in another. The Gift Card type includes the card currency. This will be fixed for all cards issued of this type. Any currency conversion for cards allowed in multiple currencies must be done by the client POS before the auth call is made. Note that the Behaviour tab only controls behaviour on the Enactor POS. It will not, for example, disable top ups sent from other POS systems. |
| Acquirer | Acquirer ID: GIFT_CARD Region: All Regions Type: Gift Card  | A single Acquirer is used for all Gift Card functions. |
| IIN Ranges | Range 1441-1441. PAN length 8.  IIN range set as Payment Card and Gift Card, linked to Gift Card type GC_UK. | IIN Ranges should be configured for all ranges for which the cards are issued. |
Data Migration
Existing Gift Cards may be imported into the Enactor database via the standard XML File Importer. Files should be structured using the Enactor Gift Card XML and Account Balance XML structure.
There are two records for each card; one for the Gift Card, and one for the matching Account Balance.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Batch>
<!--CARD 14410050-->
<retail:giftCard xmlns:core="http://www.enactor.com/core" xmlns:retail="http://www.enactor.com/retail" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:accountId>14410050</retail:accountId>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:status>ACTIVE</retail:status>
<retail:balance>999</retail:balance>
<retail:locationId>0001</retail:locationId>
<retail:dateCreated>2020-02-22T10:33:43Z</retail:dateCreated>
<retail:dateActivated>2020-02-22T10:33:43Z</retail:dateActivated>
<retail:lastTransactionDate>2020-02-22T10:33:43Z</retail:lastTransactionDate>
</retail:giftCard>
<retail:accountBalance xmlns:core="http://www.enactor.com/core" xmlns:retail="http://www.enactor.com/retail" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:accountId>14410050</retail:accountId>
<retail:accountType>giftCard</retail:accountType>
<retail:accountBalance>999</retail:accountBalance>
<retail:balanceDate>2020-02-22T10:33:43Z</retail:balanceDate>
</retail:accountBalance>
<!--CARD 14410051-->
<retail:giftCard xmlns:core="http://www.enactor.com/core" xmlns:retail="http://www.enactor.com/retail" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:accountId>14410051</retail:accountId>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:status>ACTIVE</retail:status>
<retail:balance>1000</retail:balance>
<retail:locationId>0001</retail:locationId>
<retail:dateCreated>2020-02-20T17:32:12Z</retail:dateCreated>
<retail:dateActivated>2020-02-20T17:32:12Z</retail:dateActivated>
<retail:lastTransactionDate>2020-02-21T12:19:13Z</retail:lastTransactionDate>
</retail:giftCard>
<retail:accountBalance xmlns:core="http://www.enactor.com/core" xmlns:retail="http://www.enactor.com/retail" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:accountId>14410051</retail:accountId>
<retail:accountType>giftCard</retail:accountType>
<retail:accountBalance>1000</retail:accountBalance>
<retail:balanceDate>2020-02-21T12:19:13Z</retail:balanceDate>
</retail:accountBalance>
</Batch>
It is recommended that there are a maximum of 1,000 records per file.
The namespaces may be applied to the Batch element to avoid duplication.
Following table contains the description of each Gift Card and Account Balance data elements:
| Element | Required / Optional | Type | Description |
|---|---|---|---|
| giftCard/ | |||
| accountId | Required | String | Contains the account id/card number (PAN). |
| giftCardTypeId | Required | String | Gift Card Type - This should be set to the ID of the appropriate Gift Card Type that has been configured (e.g. GC_UK). |
| status | Required | String | Should be set to ACTIVE to indicate the card has been issued to a customer and has a valid balance. |
| balance | Required | Integer | Current Balance (in pence) of card. For non-GBP cards, this is in the lowest denomination of the currency. |
| locationId | Optional | String | Store ID of the store where the card was last used. |
| dateCreated | Optional | dateTime | Date/Time when the card was created. All Date Time Formats are of the structure YYYY-MM-DDTHH:MM:SSZ T is hardcoded Z is offset to UTC (e.g. Z for GMT, +01:00 for BST) |
| dateActivated | Optional | dateTime | Date the card was issued. Required if Enactor needs to expire the card automatically based on issue date. |
| lastTransactionDate | Optional | dateTime | Last date/time the card was used. Required if enactor needs to expire the card automatically based on last usage date. |
| pinNumber | Optional | String | PIN number provided in cleartext. If provided, will be hashed (see algorithm details below) and stored in the Gift Card record. |
| accountBalance/ | |||
| accountId | Required | String | This is the same as giftCard/accountId above. |
| accountType | Required | String | Hardcoded to giftCard. |
| accountBalance | Required | Integer | This is the same as giftCard/balance above. |
| balanceDate | Required | DateTime | Last date/time the balance was changed. |
API Structure
The API is exposed by the Enactor Card Authorisation Service.
The API is accessed using XML calls over HTTP. There is no SOAP or other wrapper required.
The path of the Servlet that provides the service is /WebCardAuthorisation/CardAuthorisationServlet
In the information below, the following values are present. These will need to be modified to the appropriate settings for the live/test environments where the solution is deployed.
-
13.74.147.16: This is the IP Address/DNS Address of the Enactor Card authorisation server. There may be multiple card auth servers, or a single load balancer address.
-
39856: TCP Port for the Enactor Card Auth Service.
All calls are executed using HTTP POST messages. An example of the HTTP Headers (Applicable to all calls):
POST /WebCardAuthorisation/CardAuthorisationServlet HTTP/1.1
Content-Type: text/xml; charset=utf-8
User-Agent: Java/1.8.0_222
Host: 13.74.147.16:39856
Accept: text/html, image/gif, image/jpeg, \*; q=.2, /; q=.2
An example of a service client using Postman would be structured as follows:
All calls use the cardAuthRequestResponse XML structure for both request and response. The detail of the content is dependent on the function being executed (defined by the request type attribute)
There is no additional security around the service, beyond network access control to the Card Auth Server address and port.
Determining the Operation Type
This section describes on how the request type is determined.
The POS client calls the same endpoint URLs for all request message types (multiple URLs are defined only to support load balancing / resilience). No parameters are added to the http requests and the operation type must be determined from the request body. The API examples below show a summary of this:
- A Balance Enquiry request will be of type:
<retail:request xsi:type="retail:GiftCardBalanceRequest"\>
- All other operations will be of type
<retail:request xsi:type="retail:GiftCardAuthorisationRequest"\>
Within this request type, the actual operation is determined by the content of the transactionType tag. For example, the following values are possible:
-
<retail:transactionType>LOAD</retail:transactionType>Load (or top up) a card. -
<retail:transactionType>LOAD_NEW_CARD\</retail:transactionType>Activate and load a new card. Can be treated as LOAD if no distinction is required. -
<retail:transactionType\>REDEEM\</retail:transactionType\>Redeem all or part of card's stored value. -
<retail:transactionType\>CANCEL\</retail:transactionType\>Redeem any value and mark card as no longer used (if supported).
Within the GiftCardAuthorisationRequest, the actionType tag must then be taken into account. This can have values:
-
<retail:actionType\>VALIDATE</retail:actionType\>Validate all parameters and return an authorisation response, but do not update the card's value or status (used depending on system configuration). -
<retail:actionType\>UPDATE\</retail:actionType\>Validate and Update the card's value and status and return a confirmation response. -
<retail:actionType\>REVERSE\</retail:actionType\>Reverse an update (if possible).
Card Auth Service Implementation
If a customer wishes to configure the Enactor POS to interact with their
existing services and need to expose their API to the Enactor POS, the
requirements described below should be followed.
The Response should include the original Request where as described in
this document, the Request and Response used by the Enactor POS and
Enactor Gift Card Services have the same overall structure as shown
below:
Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core"
xmlns:retail="http://www.enactor.com/retail" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>2d1a1e6db665c083:41fff526:1706ad14d79:-13a4</retail:requesterId>
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<!-- This contains the request -->
</retail:request>
<retail:attempts>1</retail:attempts>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
Response
<retail:cardAuthRequestResponse>
<retail:requesterId>2d1a1e6db665c083:41fff526:1706ad14d79:-13a4</retail:requesterId>
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<!-- This should be the exact same xml as the original request -->
</retail:request>
<retail:response xsi:type="retail:GiftCardAuthorisationResponse">
<!-- This contains the response -->
</retail:response>
<retail:attempts>1</retail:attempts>
<!--Timestamps-->
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following fields must be repeated in the retail:cardAuthRequestResponse response, if they were present in the retail:cardAuthRequestResponse request:
- requesterId
- expectResponse
- attempts
Note: If the original request or the fields above are not included in the response, the Enactor POS application may reject/ignore the response.
Notes for API Examples
There is a request and response for each function and in each of the responses, the request is repeated in the beginning.
The full namespace settings include several namespace definitions. Namespaces have not been included on the field names in the Data Element tables. The Namespace may be determined from the examples. Normally it is retail: but there are a few exceptions. Eg: xsi:type for the Request type and core:exception for the Authorisation exception message.
Some additional data elements may be used in the calls. These have not all been included. All the mandatory data elements are included in this document.
There are a set of timestamps returned in all responses - these may be used for performance management.
Activate / Issue new Gift Card
This is used when a card is activated, loaded and issued to the customer. This may be from a Gift Card sale, or as the result of a refund onto a new card.
The Request Type is GiftCardAuthorisationRequest.
Request
Following is a sample GiftCardAuthorisationRequest request:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core"
xmlns:retail="http://www.enactor.com/retail" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:transactionDateTime>2020-02-20T16:56:41Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000042002171649190</retail:transactionId>
<retail:transactionLineNumber>1</retail:transactionLineNumber>
<retail:transactionNumber>1</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:actionType>VALIDATE</retail:actionType>
<retail:transactionType>LOAD_NEW_CARD</retail:transactionType>
<retail:amount>750</retail:amount>
</retail:request>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
Note: This request is sent twice. Once during issue with actionType = VALIDATE and shown above and then at the end of transaction (after tendering), the same request should be sent again where the actionType = UPDATE as shown below:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core"
xmlns:retail="http://www.enactor.com/retail" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:transactionDateTime>2020-02-20T16:56:41Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000042002171649190</retail:transactionId>
<retail:transactionLineNumber>1</retail:transactionLineNumber>
<retail:transactionNumber>1</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:actionType>UPDATE</retail:actionType>
<retail:transactionType>LOAD_NEW_CARD</retail:transactionType>
<retail:amount>750</retail:amount>
</retail:request>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of the GiftCardAuthorisationRequest request:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| request | String | Hardcoded to retail:GiftCardAuthorisationRequest. |
| cardAuthRequestResponse/request/ | ||
| deviceID | String | Unique identifier of the device generating the request (e.g. Till PC ID). This does not need to be maintained by Enactor. |
| transactionDateTime | Date/Time | Date/Time of the request. All Date Time Formats are of the structure YYYY-MM-DDTHH:MM:SSZ. T is hardcoded. Z is offset to UTC (e.g. Z for GMT, +01:00 for BST). |
| accountId | String | This should be set to the Gift Card PAN Number. |
| cardNumber | String | This should be set to the Gift Card PAN Number. |
| giftCardTypeId | String | This should be set to the ID of the appropriate Gift Card Type that has been configured. |
| transactionCurrencyId | String | Currency of the transaction. |
| acquirerId | String (String/Group) | The acquirerId should be set to the ID of the Gift Card Acquirer that has been configured. The groupId should be set to the ID of the region to which the Gift Card Acquirer belongs. |
| locationId | String | Store Number from which the request originates. |
| terminalNumber | String | Till Number from which the request originates. |
| transactionId | String | Unique ID of the POS transaction. This has a standard Enactor format in the example above, but this does not necessarily need to be followed. Enactor Transaction ID format: SSSSTTTTNNNNNYYMMDDHHMMSSC Where: SSSS=Store Number TTTT=Till Number NNNNN=TransactionNumber YYMMDDHHMMSS=Date/Time of Transaction C=Check Digit |
| transactionLineNumber | Integer | These should be set to the line of the transaction from which the request originates. |
| transactionNumber | Integer | These should be set to the Transaction number of the transaction from which the request originates. |
| userId | String | User who is executing the transaction. |
| actionType | String | Set to VALIDATE or UPDATE for Card Activation.
|
| transactionType | String | Set to LOAD_NEW_CARD for Card Activation. |
| amount | Long | Set to the required value in the lowest domination of the applicable currency (e.g. for GBP 666=£6.66). The currency of the load amount is always the card currency (defined in the Gift Card Type), even if the transaction currency is different. |
| pinNumber | String | Cleartext PIN Number (optional). If provided, will be validated against the PIN number recorded for the Card. |
Response - Success
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns5="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>dccee2b351e75e42:-c260ab8:18d867a989a:-3832</retail:requesterId>
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-20T16:56:41Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000042002171649190</retail:transactionId>
<retail:transactionLineNumber>1</retail:transactionLineNumber>
<retail:transactionNumber>1</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:additionalData/>
<retail:actionType>UPDATE</retail:actionType>
<retail:transactionType>LOAD_NEW_CARD</retail:transactionType>
<retail:amount>750</retail:amount>
</retail:request>
<retail:response xsi:type="retail:GiftCardAuthorisationResponse" amount="750" updateId="142" minimumValue="500" displayMessage="Authorised by Enactor" giftCardTypeId="GC_UK" giftCardDescription="Gift Card UK" cardCurrencyId="GBP" balance="750" accountId="14410050">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-20T16:56:41Z</retail:transactionDateTime>
<retail:authorisationCode>254565</retail:authorisationCode>
<retail:dateActivated>2020-02-20T16:56:41Z</retail:dateActivated>
<retail:expiryDate/>
<retail:validFrom/>
</retail:response>
<retail:attempts>1</retail:attempts>
<retail:timeRequestCreated>1707376456444</retail:timeRequestCreated>
<retail:timeRequestReceived>1707376456444</retail:timeRequestReceived>
<retail:timeRequestAccepted>1707376456444</retail:timeRequestAccepted>
<retail:timeRequestAllocated>1707376456456</retail:timeRequestAllocated>
<retail:timeRequestSent>1707376456456</retail:timeRequestSent>
<retail:timeResponseReceived>1707376457367</retail:timeResponseReceived>
<retail:timeResponseSent>1707376457367</retail:timeResponseSent>
<retail:hasFailedOver>false</retail:hasFailedOver>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of a successful GiftCardAuthorisationRequest response:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/response/ | ||
| response@amount | Long | Value (in pence) of the confirmed activation amount. Pence for GBP; for other currencies this is in the minimum denomination. |
| response@updateId | Integer | ID of the update on the Enactor card auth system. Stored in item.giftCardDetails.updateId. |
| response@maximumValue | Long | Value (in pence) of the maximum permitted balance value of the activated Gift Card. |
| response@ giftCardTypeId | String | Gift Card type of the activated card. Stored in item.giftCardDetails.giftCardTypeId. |
| response@ giftCardDescription | String | Description of Gift Card Type. |
| response@cardCurrencyId | String | ISO Currency ID of the activated card. |
| response@displayMessage | String | Message returned by Auth Service (may be displayed on POS if desired). Stored in item.giftCardDetails.hostMessage. |
| response@balance | Long | New balance (in pence) of activated card. Stored in item.giftCardDetails.newBalance. |
| response@accountId | String | ID of the new gift card account. Stored in item.giftCardDetails.accountId. |
| response@status | String | Optional status of the card before the load/ issue was applied. Not included if the status was already ACTIVE. |
| deviceID | String | Unique identifier of the device generating the request. Eg: Till PC ID. Does not need to be maintained in Enactor. |
| transactionDateTime | Date/Time | Date/Time of last transaction on this account (this will be the current activation transaction). |
| authorisationCode | String | Identifier of the response - this may be used to match with the auth record in the Card Auth system. Stored in item.giftCardDetails.authorisationCode. |
| dateActivated | Date | Date on which the activation occurred. |
| response@displayMessage | String | Optional Message from host. Not in example XML (Attribute). Stored in item.giftCardDetails.hostMessage. |
| response@hostReference | String | Optional Reference from host. Not in example XML (Attribute). Stored in item.giftCardDetails.hostReference. |
| response@previousBalance | Long | Optional The previous balance. Not in example XML (Attribute). Stored in item.giftCardDetails.previousBalance |
| expiryDate | Date/Time | Optional Expiry Date/Time. Not in example XML. Store in item.giftCardDetails.expiryDate All Date Time Formats are of the structure YYYY-MM-DDTHH:MM:SSZT is hardcodedZ is offset to UTC (e.g. Z for GMT, +01:00 for BST). |
| validFrom | Date/Time | Optional The gift card will only be acitve from this date. Store in item.giftCardDetails.validFrom All Date Time Formats are of the structure YYYY-MM-DDTHH:MM:SSZT is hardcodedZ is offset to UTC (e.g. Z for GMT, +01:00 for BST). |
| decline | Boolean | Optional Decline the request. Not in example XML. |
| response@refer | Boolean | Optional Referral requested. Not in example XML. |
| cardAuthRequestResponse/ | ||
| timeRequestCreated etc | Java Epoch time (ms since 1/1/1970) | Timestamps of authorisation activities. For performance information only. |
Response - Failure
In this example the failure is a result of an invalid Acquirer ID being provided in the request.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns5="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>dccee2b351e75e42:-c260ab8:18d867a989a:-3607</retail:requesterId>
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-20T16:56:41Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>EG_UK</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000042002171649190</retail:transactionId>
<retail:transactionLineNumber>1</retail:transactionLineNumber>
<retail:transactionNumber>1</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:additionalData/>
<retail:actionType>VALIDATE</retail:actionType>
<retail:transactionType>LOAD_NEW_CARD</retail:transactionType>
<retail:amount>750</retail:amount>
</retail:request>
<retail:response xsi:type="retail:AuthorisationExceptionMessage">
<core:exception>
<core:errorCode>InvalidAcquirer</core:errorCode>
<core:errorData></core:errorData>
<core:description>ValidateApacs30Process. Failed to load Gift Card Acquirer 'acquirerId=EG_UK;groupTypeId=region;groupId=ALL;groupHierarchyId=All;'</core:description>
</core:exception>
</retail:response>
<retail:attempts>0</retail:attempts>
<retail:timeRequestCreated>1707376991947</retail:timeRequestCreated>
<retail:timeRequestReceived>1707376991948</retail:timeRequestReceived>
<retail:timeRequestAccepted>1707376991948</retail:timeRequestAccepted>
<retail:timeRequestAllocated>0</retail:timeRequestAllocated>
<retail:timeRequestSent>0</retail:timeRequestSent>
<retail:timeResponseReceived>0</retail:timeResponseReceived>
<retail:timeResponseSent>1707376991955</retail:timeResponseSent>
<retail:hasFailedOver>false</retail:hasFailedOver>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of a failed GiftCardAuthorisationRequest response:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/response/exception | exception.toString is logged as error. | |
| errorCode | String | ID of the error returned by the Card Auth Service. Following are the possible outcome values:
|
| description | String | Description of the error. |
| causeStack | String | Full Stack trace for the error. |
Gift Card Balance Request
This is used to check the status and balance of a gift card. The Request Type is GiftCardBalanceRequest.
Request
Following is a sample GiftCardBalanceRequest request:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns10="http://www.enactor.com/retail/storedRestaurantSaleTransaction/service" xmlns:ns11="http://www.enactor.com/crm/customerLoyalty/service" xmlns:ns12="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:ns13="http://www.enactor.com/addressLookup/service" xmlns:ns5="http://www.enactor.com/crm" xmlns:ns7="http://www.enactor.com/retail/restaurantTableStatus/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:request xsi:type="retail:GiftCardBalanceRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-20T17:37:56Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:cardTrack2></retail:cardTrack2>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:merchantId>100</retail:merchantId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000102002201723566</retail:transactionId>
<retail:transactionNumber>10</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:serverUserName></retail:serverUserName>
<retail:serverPassword></retail:serverPassword>
<retail:pinNumber></retail:pinNumber>
<retail:pinType></retail:pinType>
</retail:request>
<retail:attempts>1</retail:attempts>
<retail:timeRequestCreated>1582220276191</retail:timeRequestCreated>
<retail:timeRequestReceived>0</retail:timeRequestReceived>
<retail:timeRequestAccepted>0</retail:timeRequestAccepted>
<retail:timeRequestAllocated>0</retail:timeRequestAllocated>
<retail:timeRequestSent>0</retail:timeRequestSent>
<retail:timeResponseReceived>0</retail:timeResponseReceived>
<retail:timeResponseSent>0</retail:timeResponseSent>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of the GiftCardBalanceRequest request:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| request@type | String | Hardcoded to retail:GiftCardBalanceRequest |
| cardAuthRequestResponse/request/ | ||
| deviceID | String | Unique identifier of the device generating the request (e.g. Till PC ID). This does not need to be maintained by Enactor. |
| transactionDateTime | Date/Time | Date/Time of the request. All Date Time Formats are of the structure YYYY-MM-DDTHH:MM:SSZ T is hardcoded Z is offset to UTC (e.g. Z for GMT, +01:00 for BST) |
| accountId | String | This should be set to the Gift Card PAN Number. |
| cardNumber | String | This should be set to the Gift Card PAN Number. |
| giftCardTypeId | String | This should be set to the ID of the appropriate Gift Card Type that has been configured. |
| transactionCurrencyId | String | Currency of the transaction. |
| acquirerId | String (String/Group) | The acquirerId should be set to the ID of the Gift Card Acquirer that has been configured. The groupId should be set to the ID of the region to which the Gift Card Acquirer belongs. |
| locationId | String | Store Number from which the request originates. |
| terminalNumber | String | Till Number from which the request originates. |
| transactionId | String | Unique ID of the POS transaction. This has a standard Enactor format in the example above, but this does not necessarily need to be followed. Enactor Transaction ID format: SSSSTTTTNNNNNYYMMDDHHMMSSC Where: SSSS=Store Number TTTT=Till Number NNNNN=TransactionNumber YYMMDDHHMMSS=Date/Time of Transaction C=Check Digit |
| transactionNumber | Integer | These should be set to the Transaction number of the transaction from which the request originates. |
| userId | String | User who is executing the transaction. |
Response - Success
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns5="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>dccee2b351e75e42:-c260ab8:18d867a989a:-3520</retail:requesterId>
<retail:request xsi:type="retail:GiftCardBalanceRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-20T17:37:56Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:cardTrack2></retail:cardTrack2>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:merchantId>100</retail:merchantId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000102002201723566</retail:transactionId>
<retail:transactionNumber>10</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:serverUserName></retail:serverUserName>
<retail:serverPassword></retail:serverPassword>
<retail:pinNumber></retail:pinNumber>
<retail:pinType></retail:pinType>
<retail:additionalData/>
</retail:request>
<retail:response xsi:type="retail:GiftCardBalanceResponse" minimumValue="500" giftCardTypeId="GC_UK" giftCardDescription="Gift Card UK" cardCurrencyId="GBP" balance="1000" status="ACTIVE" accountId="14410050">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-20T17:37:56Z</retail:transactionDateTime>
<retail:dateActivated>2020-02-20T16:56:41Z</retail:dateActivated>
<retail:expiryDate/>
<retail:validFrom>2020-02-20T16:56:41Z</retail:validFrom>
<retail:customerName/>
<retail:customerAddress>
<retail:countryCodeId></retail:countryCodeId>
<retail:typeId></retail:typeId>
<retail:isTemplate>false</retail:isTemplate>
</retail:customerAddress>
</retail:response>
<retail:attempts>1</retail:attempts>
<retail:timeRequestCreated>1582220276191</retail:timeRequestCreated>
<retail:timeRequestReceived>1707377221937</retail:timeRequestReceived>
<retail:timeRequestAccepted>1707377221937</retail:timeRequestAccepted>
<retail:timeRequestAllocated>1707377221964</retail:timeRequestAllocated>
<retail:timeRequestSent>1707377221964</retail:timeRequestSent>
<retail:timeResponseReceived>1707377222021</retail:timeResponseReceived>
<retail:timeResponseSent>1707377222022</retail:timeResponseSent>
<retail:hasFailedOver>false</retail:hasFailedOver>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of a successful GiftCardBalanceRequest response:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| response@maximumValue | Long | Value (in pence) of the maximum permitted balance value of the activated Gift Card. |
| response@giftCardTypeId | String | Gift Card type of the activated card. Stored in item.giftCardDetails.giftCardTypeId. |
| response@giftCardDescription | String | Description of Gift Card Type. |
| response@cardCurrencyId | String | ISO Currency ID of the activated card |
| response@balance | Long | New balance (in pence) of activated card. Stored in item.giftCardDetails.newBalance. |
| response@status | String | Status of the gift card - NOT_IN_USE, AVAILABLE, ACTIVE, CLOSED, INVALID |
| response@accountId | String | ID of the gift card account. Stored in item.giftCardDetails.accountId. |
| response@displayMessage | String | Optional Message from host. Not in example XML (Attribute). Stored in item.giftCardDetails.hostMessage. |
| response@hostReference | String | Optional Reference from host. Not in example XML. (Attribute). Stored in item.giftCardDetails.hostReference. |
| response@status | String | Optional Displays NOT_AUTHORISED_NOT_ACTIVE message in Pos/GiftCard/GiftCardMessages if value is not ‘AVAILABLE' or ‘ACTIVE'. Not in example XML. Following are the possible outcome values: NOT_IN_USE AVAILABLE ACTIVE CLOSED INVALID |
| cardAuthRequestResponse/response/ | ||
| transactionDateTime | Date/Time | Date/Time of last transaction on this account (this will be the current activation transaction). |
| deviceID | String | Unique identifier of the device generating the request. Eg: Till PC ID. Does not need to be maintained in Enactor. |
| dateActivated | Date | Date on which the activation occurred. |
| customerName customerAddress | String Address | These will be populated if the Gift Card has been assigned to a customer (not normally the case). These are available to the enquiry details screen. |
| timeRequestCreated etc | Java Epoch time (ms since 1/1/1970) | Timestamps of authorisation activities. For performance information only. |
| expiryDate | Date/Time | Optional Expiry date. Not in example XML. Stored in item.giftCardDetails.expiryDate. |
| validFrom | Date/Time | Optional The gift card will only be valid from this date. Stored in item.giftCardDetails.validFrom. |
| decline | Boolean | Optional Decline the request. Displays NOT_AUTHORISED_NO_ACCOUNT message in Pos/GiftCard/GiftCardMessages. Not in example XML. |
Response - Failure
In this example the failure is a result of Gift Card Not Found.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns5="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>dccee2b351e75e42:-c260ab8:18d867a989a:-34e0</retail:requesterId>
<retail:request xsi:type="retail:GiftCardBalanceRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-20T17:37:56Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410059</retail:accountId>
<retail:cardNumber>14410059</retail:cardNumber>
<retail:cardTrack2></retail:cardTrack2>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:merchantId>100</retail:merchantId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000102002201723566</retail:transactionId>
<retail:transactionNumber>10</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:serverUserName></retail:serverUserName>
<retail:serverPassword></retail:serverPassword>
<retail:pinNumber></retail:pinNumber>
<retail:pinType></retail:pinType>
<retail:additionalData/>
</retail:request>
<retail:response xsi:type="retail:GiftCardBalanceResponse" status="INVALID" accountId="14410059">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-20T17:37:56Z</retail:transactionDateTime>
<retail:decline>true</retail:decline>
<retail:expiryDate/>
<retail:validFrom/>
</retail:response>
<retail:attempts>1</retail:attempts>
<retail:timeRequestCreated>1582220276191</retail:timeRequestCreated>
<retail:timeRequestReceived>1707377281980</retail:timeRequestReceived>
<retail:timeRequestAccepted>1707377281980</retail:timeRequestAccepted>
<retail:timeRequestAllocated>1707377281991</retail:timeRequestAllocated>
<retail:timeRequestSent>1707377281991</retail:timeRequestSent>
<retail:timeResponseReceived>1707377281996</retail:timeResponseReceived>
<retail:timeResponseSent>1707377281996</retail:timeResponseSent>
<retail:hasFailedOver>false</retail:hasFailedOver>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of a failed GiftCardBalanceRequest response:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| response@status | String | INVALID. Indicates an invalid response. |
| response@accountId | String | Account ID that was searched for. |
| cardAuthRequestResponse/response/ | ||
| decline | Boolean | If true, it indicates that the request has been rejected by the Card Auth service. |
Gift Card Top Up
This is used to load more funds onto a gift card, or as the result of a refund onto an existing active card.
The Request Type is GiftCardAuthorisationRequest.
Request
Following is a sample GiftCardAuthorisationRequest request for a Gift Card Top Up:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:retail="http://www.enactor.com/retail"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:transactionDateTime>2020-02-22T09:01:29Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000082002201700196</retail:transactionId>
<retail:transactionLineNumber>1</retail:transactionLineNumber>
<retail:transactionNumber>8</retail:transactionNumber>
<retail:userId>0001</retail:userId>
<retail:actionType>UPDATE</retail:actionType>
<retail:transactionType>LOAD</retail:transactionType>
<retail:amount>250</retail:amount>
</retail:request>
<retail:attempts>1</retail:attempts>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of the GiftCardAuthorisationRequest request:
| Element | Type | Description |
|---|---|---|
| transactionCurrencyId | String | Currency of the transaction. |
| acquirerId | String (String/Group) | The acquirerId should be set to the ID of the Gift Card Acquirer that has been configured. The groupId should be set to the ID of the region to which the Gift Card Acquirer belongs. |
| locationId | String | Store Number from which the request originates. |
| terminalNumber | String | Till Number from which the request originates. |
| transactionId | String | Unique ID of the POS transaction. This has a standard Enactor format in the example above, but this does not necessarily need to be followed. Enactor Transaction ID format: SSSSTTTTNNNNNYYMMDDHHMMSSC Where: SSSS=Store Number TTTT=Till Number NNNNN=TransactionNumber YYMMDDHHMMSS=Date/Time of Transaction C=Check Digit |
| transactionLineNumber | Integer | These should be set to the line of the transaction from which the request originates. |
| transactionNumber | Integer | These should be set to the Transaction number of the transaction from which the request originates. |
| userId | String | User who is executing the transaction. |
| actionType | String | Set to VALIDATE or UPDATE for Card Activation.
|
| transactionType | String | Set to LOAD_NEW_CARD for Card Activation. |
| amount | Long | Set to the required value in the lowest domination of the applicable currency (e.g. for GBP 666=£6.66). The currency of the load amount is always the card currency (defined in the Gift Card Type), even if the transaction currency is different. |
Response - Success
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns5="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>dccee2b351e75e42:-c260ab8:18d867a989a:-37e5</retail:requesterId>
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T09:01:29Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000082002201700196</retail:transactionId>
<retail:transactionLineNumber>1</retail:transactionLineNumber>
<retail:transactionNumber>8</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:additionalData/>
<retail:actionType>UPDATE</retail:actionType>
<retail:transactionType>LOAD</retail:transactionType>
<retail:amount>250</retail:amount>
</retail:request>
<retail:response xsi:type="retail:GiftCardAuthorisationResponse" amount="250" previousBalance="750" updateId="143" minimumValue="500" displayMessage="Authorised by Enactor" giftCardTypeId="GC_UK" giftCardDescription="Gift Card UK" cardCurrencyId="GBP" balance="1000" status="ACTIVE" accountId="14410050">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T09:01:29Z</retail:transactionDateTime>
<retail:authorisationCode>102400</retail:authorisationCode>
<retail:dateActivated>2020-02-20T16:56:41Z</retail:dateActivated>
<retail:expiryDate/>
<retail:validFrom/>
<retail:customerName/>
<retail:customerAddress>
<retail:countryCodeId></retail:countryCodeId>
<retail:typeId></retail:typeId>
<retail:isTemplate>false</retail:isTemplate>
</retail:customerAddress>
</retail:response>
<retail:attempts>1</retail:attempts>
<retail:timeRequestCreated>1707376512903</retail:timeRequestCreated>
<retail:timeRequestReceived>1707376512903</retail:timeRequestReceived>
<retail:timeRequestAccepted>1707376512904</retail:timeRequestAccepted>
<retail:timeRequestAllocated>1707376512910</retail:timeRequestAllocated>
<retail:timeRequestSent>1707376512911</retail:timeRequestSent>
<retail:timeResponseReceived>1707376513113</retail:timeResponseReceived>
<retail:timeResponseSent>1707376513114</retail:timeResponseSent>
<retail:hasFailedOver>false</retail:hasFailedOver>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of a successful GiftCardAuthorisationRequest response:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| response@amount | Long | Value (in pence) of the confirmed activation amount. Pence for GBP; for other currencies this is in the minimum denomination. |
| response@previousBalance | Long | Card balance before the top up was applied. Stored in item.giftCardDetails.previousBalance. |
| response@updateId | Integer | ID of the update on the Enactor card auth system. Stored in item.giftCardDetails.updateId. |
| response@maximumValue | Long | Value (in pence) of the maximum permitted balance value of the Gift Card. |
| response@giftCardTypeId | String | Gift Card type of the card. Stored in item.giftCardDetails.giftCardTypeId. |
| response@giftCardDescription | String | Description of Gift Card Type. |
| response@cardCurrencyId | String | ISO Currency ID of the activated card. |
| response@displayMessage | String | Message returned by Auth Service (may be displayed on POS if desired). Stored in item.giftCardDetails.hostMessage. |
| response@balance | Long | New balance (in pence) of topped up card. Stored in item.giftCardDetails.newBalance. |
| response@status | String | Status of the topped-up gift card - NOT_IN_USE, AVAILABLE, ACTIVE, CLOSED, INVALID |
| response@accountId | String | ID of the gift card account. Stored in item.giftCardDetails.accountId. |
| response@hostReference | String | Optional Reference from host. Not in example XML (Attribute). Stored in item.giftCardDetails.hostReference. |
| response@refer | Boolean | Optional Referral requested. Not in example XML. |
| cardAuthRequestResponse/response/ | ||
| deviceID | String | Unique identifier of the device generating the request. Eg: Till PC ID. Does not need to be maintained in Enactor. |
| transactionDateTime | Date/Time | Date/Time of last transaction on this account (this will be the current activation transaction). |
| authorisationCode | String | Identifier of the response - this may be used to match with the auth record in the Card Auth system. Stored in item.giftCardDetails.authorisationCode. |
| dateActivated | Date | Date on which the activation occurred. |
| customerName customerAddress | String Address | These will be populated if the Gift Card has been assigned to a customer (not normally the case). These are available to the enquiry details screen. |
| timeRequestCreated etc | Java Epoch time (ms since 1/1/1970) | Timestamps of authorisation activities. For performance information only. |
| decline | Boolean | Optional Decline the request. Displays NOT_AUTHORISED_NO_ACCOUNT message in Pos/GiftCard/GiftCardMessages. Not in example XML. |
| response@refer | Boolean | Optional Referral requested. Not in example XML. |
| expiryDate | Date/Time | Optional Expiry date. Not in example XML. Stored in item.giftCardDetails.expiryDate. |
| validFrom | Date/Time | Optional The gift card will only be valid from this date. Stored in item.giftCardDetails.validFrom. |
Response - Failure
In this example the failure is a result of Gift Card Not Active, Not Found or Over Limit.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns5="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>dccee2b351e75e42:-c260ab8:18d867a989a:-3403</retail:requesterId>
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T09:01:29Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410059</retail:accountId>
<retail:cardNumber>14410059</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000082002201700196</retail:transactionId>
<retail:transactionLineNumber>1</retail:transactionLineNumber>
<retail:transactionNumber>8</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:additionalData/>
<retail:actionType>UPDATE</retail:actionType>
<retail:transactionType>LOAD</retail:transactionType>
<retail:amount>250</retail:amount>
</retail:request>
<retail:response xsi:type="retail:GiftCardAuthorisationResponse" outcome="NoAccount" status="INVALID" accountId="144100500">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T09:01:29Z</retail:transactionDateTime>
<retail:decline>true</retail:decline>
<retail:expiryDate/>
<retail:validFrom/>
</retail:response>
<retail:attempts>1</retail:attempts>
<retail:timeRequestCreated>1707377500810</retail:timeRequestCreated>
<retail:timeRequestReceived>1707377500810</retail:timeRequestReceived>
<retail:timeRequestAccepted>1707377500810</retail:timeRequestAccepted>
<retail:timeRequestAllocated>1707377500822</retail:timeRequestAllocated>
<retail:timeRequestSent>1707377500822</retail:timeRequestSent>
<retail:timeResponseReceived>1707377500834</retail:timeResponseReceived>
<retail:timeResponseSent>1707377500834</retail:timeResponseSent>
<retail:hasFailedOver>false</retail:hasFailedOver>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of a failed GiftCardAuthorisationRequest response:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| response@status | String | INVALID. Indicates an invalid response. |
| response@accountId | String | Account ID that was searched for. |
| cardAuthRequestResponse/response/ | ||
| decline | Boolean | If true, it indicates that the request has been rejected by the Card Auth service. |
Gift Card Payment Request
This is used to tender using a gift card.
The Request Type is GiftCardAuthorisationRequest, where the actionType = UPDATE.
Request
Following is a sample GiftCardAuthorisationRequest request for a Gift Card Payment Request:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core"
xmlns:retail="http://www.enactor.com/retail" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:transactionDateTime>2020-02-22T10:20:29Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000092002201701408</retail:transactionId>
<retail:transactionLineNumber>2</retail:transactionLineNumber>
<retail:transactionNumber>1</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:actionType>UPDATE</retail:actionType>
<retail:transactionType>REDEEM</retail:transactionType>
<retail:amount>500</retail:amount>
</retail:request>
<retail:attempts>1</retail:attempts>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of the GiftCardAuthorisationRequest request:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| request@type | String | Hardcoded to retail:GiftCardAuthorisationRequest |
| cardAuthRequestResponse/request/ | ||
| deviceID | String | Unique identifier of the device generating the request (e.g. Till PC ID). This does not need to be maintained by Enactor. |
| transactionDateTime | Date/Time | Date/Time of the request. All Date Time Formats are of the structure YYYY-MM-DDTHH:MM:SSZ T is hardcoded Z is offset to UTC (e.g. Z for GMT, +01:00 for BST) |
| accountId | String | This should be set to the Gift Card PAN Number. |
| cardNumber | String | This should be set to the Gift Card PAN Number. |
| giftCardTypeId | String | This should be set to the ID of the appropriate Gift Card Type that has been configured. |
| transactionCurrencyId | String | Currency of the transaction. |
| acquirerId | String (String/Group) | The acquirerId should be set to the ID of the Gift Card Acquirer that has been configured. The groupId should be set to the ID of the region to which the Gift Card Acquirer belongs. |
| locationId | String | Store Number from which the request originates. |
| terminalNumber | String | Till Number from which the request originates. |
| transactionId | String | Unique ID of the POS transaction. This has a standard Enactor format in the example above, but this does not necessarily need to be followed. Enactor Transaction ID format: SSSSTTTTNNNNNYYMMDDHHMMSSC Where: SSSS=Store Number TTTT=Till Number NNNNN=TransactionNumber YYMMDDHHMMSS=Date/Time of Transaction C=Check Digit |
| transactionLineNumber | Integer | These should be set to the line of the transaction from which the request originates. |
| transactionNumber | Integer | These should be set to the Transaction number of the transaction from which the request originates. |
| userId | String | User who is executing the transaction. |
| actionType | String | Set to UPDATE for Card Payment Auth. |
| transactionType | String | Set to REDEEM for Card Payment Auth. |
| amount | Long | Set to the required value in the lowest domination of the applicable currency (e.g. for GBP 666=£6.66). The currency of the load amount is always the card currency (defined in the Gift Card Type), even if the transaction currency is different. |
Response - Success
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns5="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>dccee2b351e75e42:-c260ab8:18d867a989a:-309b</retail:requesterId>
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T10:20:29Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000092002201701408</retail:transactionId>
<retail:transactionLineNumber>2</retail:transactionLineNumber>
<retail:transactionNumber>1</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:additionalData/>
<retail:actionType>UPDATE</retail:actionType>
<retail:transactionType>REDEEM</retail:transactionType>
<retail:amount>500</retail:amount>
</retail:request>
<retail:response xsi:type="retail:GiftCardAuthorisationResponse" amount="500" previousBalance="1000" updateId="144" minimumValue="500" displayMessage="Authorised by Enactor" giftCardTypeId="GC_UK" giftCardDescription="Gift Card UK" cardCurrencyId="GBP" balance="500" status="ACTIVE" accountId="14410050">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T10:20:29Z</retail:transactionDateTime>
<retail:authorisationCode>102574</retail:authorisationCode>
<retail:dateActivated>2020-02-20T16:56:41Z</retail:dateActivated>
<retail:expiryDate/>
<retail:validFrom/>
<retail:customerName/>
<retail:customerAddress>
<retail:countryCodeId></retail:countryCodeId>
<retail:typeId></retail:typeId>
<retail:isTemplate>false</retail:isTemplate>
</retail:customerAddress>
</retail:response>
<retail:attempts>1</retail:attempts>
<retail:timeRequestCreated>1707378378105</retail:timeRequestCreated>
<retail:timeRequestReceived>1707378378105</retail:timeRequestReceived>
<retail:timeRequestAccepted>1707378378105</retail:timeRequestAccepted>
<retail:timeRequestAllocated>1707378378106</retail:timeRequestAllocated>
<retail:timeRequestSent>1707378378106</retail:timeRequestSent>
<retail:timeResponseReceived>1707378378213</retail:timeResponseReceived>
<retail:timeResponseSent>1707378378213</retail:timeResponseSent>
<retail:hasFailedOver>false</retail:hasFailedOver>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of a successful GiftCardAuthorisationRequest response:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| response@amount | Long | Value (in pence) of the confirmed activation amount. Pence for GBP; for other currencies this is in the minimum denomination. |
| response@previousBalance | Long | Card balance before the top up was applied. Stored in item.giftCardDetails.previousBalance. |
| response@updateId | Integer | ID of the update on the Enactor card auth system. Stored in item.giftCardDetails.updateId. |
| response@maximumValue | Long | Value (in pence) of the maximum permitted balance value of the Gift Card. |
| response@giftCardTypeId | String | Gift Card type of the card. Stored in item.giftCardDetails.giftCardTypeId. |
| response@giftCardDescription | String | Description of Gift Card Type. |
| response@cardCurrencyId | String | ISO Currency ID of the activated card. |
| response@displayMessage | String | Message returned by Auth Service (may be displayed on POS if desired). Stored in item.giftCardDetails.hostMessage. |
| response@balance | Long | New balance (in pence) of topped up card. Stored in item.giftCardDetails.newBalance. |
| response@status | String | Status of the topped-up gift card - NOT_IN_USE, AVAILABLE, ACTIVE, CLOSED, INVALID |
| response@accountId | String | ID of the gift card account. Stored in item.giftCardDetails.accountId. |
| response@hostReference | String | Optional Reference from host. Not in example XML (Attribute). Stored in item.giftCardDetails.hostReference. |
| response@refer | Boolean | Optional Referral requested. Not in example XML. |
| authorisationCode | String | Identifier of the response - this may be used to match with the auth record in the Card Auth system. Stored in item.giftCardDetails.authorisationCode. |
| dateActivated | Date | Date on which the activation occurred. |
| customerName customerAddress | String Address | These will be populated if the Gift Card has been assigned to a customer (not normally the case). These are available to the enquiry details screen. |
| timeRequestCreated etc | Java Epoch time (ms since 1/1/1970) | Timestamps of authorisation activities. For performance information only. |
| expiryDate | Date/Time | Optional Expiry date. Not in example XML. Stored in item.giftCardDetails.expiryDate. |
| validFrom | Date/Time | Optional The gift card will only be valid from this date. Stored in item.giftCardDetails.validFrom. |
| decline | Boolean | Optional Decline the request. Displays NOT_AUTHORISED_NO_ACCOUNT message in Pos/GiftCard/GiftCardMessages. Not in example XML. |
Response - Failure
In this example the failure is a result of Gift Card Not Active, Not Found or Insufficient Balance.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns5="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>dccee2b351e75e42:-c260ab8:18d867a989a:-2f43</retail:requesterId>
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T10:20:29Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000092002201701408</retail:transactionId>
<retail:transactionLineNumber>2</retail:transactionLineNumber>
<retail:transactionNumber>1</retail:transactionNumber>
<retail:userId>000101</retail:userId>
<retail:additionalData/>
<retail:actionType>UPDATE</retail:actionType>
<retail:transactionType>REDEEM</retail:transactionType>
<retail:amount>500000</retail:amount>
</retail:request>
<retail:response xsi:type="retail:GiftCardAuthorisationResponse" previousBalance="500" outcome="BalanceNotSufficient" minimumValue="500" giftCardTypeId="GC_UK" giftCardDescription="Gift Card UK" cardCurrencyId="GBP" balance="500" status="INVALID" accountId="14410050">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T10:20:29Z</retail:transactionDateTime>
<retail:decline>true</retail:decline>
<retail:expiryDate/>
<retail:validFrom/>
<retail:customerName/>
<retail:customerAddress>
<retail:countryCodeId></retail:countryCodeId>
<retail:typeId></retail:typeId>
<retail:isTemplate>false</retail:isTemplate>
</retail:customerAddress>
</retail:response>
<retail:attempts>1</retail:attempts>
<retail:timeRequestCreated>1707378715988</retail:timeRequestCreated>
<retail:timeRequestReceived>1707378715988</retail:timeRequestReceived>
<retail:timeRequestAccepted>1707378715988</retail:timeRequestAccepted>
<retail:timeRequestAllocated>1707378715997</retail:timeRequestAllocated>
<retail:timeRequestSent>1707378715997</retail:timeRequestSent>
<retail:timeResponseReceived>1707378716027</retail:timeResponseReceived>
<retail:timeResponseSent>1707378716027</retail:timeResponseSent>
<retail:hasFailedOver>false</retail:hasFailedOver>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of a failed GiftCardAuthorisationRequest response:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| response@outcome | String | Provides the reason for the failure:
|
| response@status | String | INVALID. Indicates an invalid response. |
| response@accountId | String | Account ID that was searched for. |
| cardAuthRequestResponse/response/ | ||
| decline | Boolean | If true, it indicates that the request has been rejected by the Card Auth service. |
Gift Card Payment Reversal Request
This is used to reverse of a tender using a gift card. The Request Type is GiftCardAuthorisationRequest, where the actionType = REVERSE.
Request
Following is a sample GiftCardAuthorisationRequest request for a Gift Card Payment Reversal Request:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core"
xmlns:retail="http://www.enactor.com/retail" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:transactionDateTime>2020-02-22T10:20:29Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000092002201701408</retail:transactionId>
<retail:transactionLineNumber>2</retail:transactionLineNumber>
<retail:transactionNumber>9</retail:transactionNumber>
<retail:userId>0001</retail:userId>
<retail:actionType>REVERSE</retail:actionType>
<retail:transactionType>REDEEM</retail:transactionType>
<retail:amount>500</retail:amount>
</retail:request>
<retail:attempts>1</retail:attempts>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of the GiftCardAuthorisationRequest request:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| request@type | String | Hardcoded to retail:GiftCardAuthorisationRequest |
| cardAuthRequestResponse/request/ | ||
| deviceID | String | Unique identifier of the device generating the request (e.g. Till PC ID). This does not need to be maintained by Enactor. |
| transactionDateTime | Date/Time | Date/Time of the request. All Date Time Formats are of the structure YYYY-MM-DDTHH:MM:SSZ T is hardcoded Z is offset to UTC (e.g. Z for GMT, +01:00 for BST) |
| accountId | String | This should be set to the Gift Card PAN Number. |
| cardNumber | String | This should be set to the Gift Card PAN Number. |
| giftCardTypeId | String | This should be set to the ID of the appropriate Gift Card Type that has been configured. |
| transactionCurrencyId | String | Currency of the transaction. |
| acquirerId | String (String/Group) | The acquirerId should be set to the ID of the Gift Card Acquirer that has been configured. The groupId should be set to the ID of the region to which the Gift Card Acquirer belongs. |
| locationId | String | Store Number from which the request originates. |
| terminalNumber | String | Till Number from which the request originates. |
| transactionId | String | Unique ID of the POS transaction. This has a standard Enactor format in the example above, but this does not necessarily need to be followed. Enactor Transaction ID format: SSSSTTTTNNNNNYYMMDDHHMMSSC Where: SSSS=Store Number TTTT=Till Number NNNNN=TransactionNumber YYMMDDHHMMSS=Date/Time of Transaction C=Check Digit |
| transactionLineNumber | Integer | These should be set to the line of the transaction from which the request originates. |
| transactionNumber | Integer | These should be set to the Transaction number of the transaction from which the request originates. |
| userId | String | User who is executing the transaction. |
| actionType | String | Set to REVERSE for Card Payment Auth reversal. |
| transactionType | String | Set to REDEEM for Card Payment Auth. |
| amount | Long | Set to the required value in the lowest domination of the applicable currency (e.g. for GBP 666=£6.66). The currency of the load amount is always the card currency (defined in the Gift Card Type), even if the transaction currency is different. |
Response - Success
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns5="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>dccee2b351e75e42:-c260ab8:18d867a989a:-29db</retail:requesterId>
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T10:20:29Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000092002201701408</retail:transactionId>
<retail:transactionLineNumber>2</retail:transactionLineNumber>
<retail:transactionNumber>9</retail:transactionNumber>
<retail:userId>0001</retail:userId>
<retail:additionalData/>
<retail:actionType>REVERSE</retail:actionType>
<retail:transactionType>REDEEM</retail:transactionType>
<retail:amount>500</retail:amount>
</retail:request>
<retail:response xsi:type="retail:GiftCardAuthorisationResponse" amount="500" previousBalance="1000" updateId="144" minimumValue="500" displayMessage="Authorised by Enactor" giftCardTypeId="GC_UK" giftCardDescription="Gift Card UK" cardCurrencyId="GBP" balance="500" status="ACTIVE" accountId="14410050">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T10:20:29Z</retail:transactionDateTime>
<retail:authorisationCode>102574</retail:authorisationCode>
<retail:dateActivated>2020-02-20T16:56:41Z</retail:dateActivated>
<retail:expiryDate/>
<retail:validFrom>2020-02-20T16:56:41Z</retail:validFrom>
<retail:customerName/>
<retail:customerAddress>
<retail:countryCodeId></retail:countryCodeId>
<retail:typeId></retail:typeId>
<retail:isTemplate>false</retail:isTemplate>
</retail:customerAddress>
</retail:response>
<retail:attempts>1</retail:attempts>
<retail:timeRequestCreated>1707379589111</retail:timeRequestCreated>
<retail:timeRequestReceived>1707379589112</retail:timeRequestReceived>
<retail:timeRequestAccepted>1707379589112</retail:timeRequestAccepted>
<retail:timeRequestAllocated>1707379589121</retail:timeRequestAllocated>
<retail:timeRequestSent>1707379589121</retail:timeRequestSent>
<retail:timeResponseReceived>1707379589210</retail:timeResponseReceived>
<retail:timeResponseSent>1707379589210</retail:timeResponseSent>
<retail:hasFailedOver>false</retail:hasFailedOver>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of a successful GiftCardAuthorisationRequest response:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| response@amount | Long | Value (in pence) of the confirmed activation amount. Pence for GBP; for other currencies this is in the minimum denomination. |
| response@previousBalance | Long | Card balance before the top up was applied. Stored in item.giftCardDetails.previousBalance. |
| response@updateId | Integer | ID of the update on the Enactor card auth system. Stored in item.giftCardDetails.updateId. |
| response@maximumValue | Long | Value (in pence) of the maximum permitted balance value of the Gift Card. |
| response@giftCardTypeId | String | Gift Card type of the card. Stored in item.giftCardDetails.giftCardTypeId. |
| response@giftCardDescription | String | Description of Gift Card Type. |
| response@cardCurrencyId | String | ISO Currency ID of the activated card. |
| response@displayMessage | String | Message returned by Auth Service (may be displayed on POS if desired). Stored in item.giftCardDetails.hostMessage. |
| response@balance | Long | New balance (in pence) of topped up card. Stored in item.giftCardDetails.newBalance. |
| response@status | String | Status of the topped-up gift card - NOT_IN_USE, AVAILABLE, ACTIVE, CLOSED, INVALID |
| response@accountId | String | ID of the gift card account. Stored in item.giftCardDetails.accountId. |
| response@hostReference | String | Optional Reference from host. Not in example XML (Attribute). Stored in item.giftCardDetails.hostReference. |
| response@refer | Boolean | Optional Referral requested. Not in example XML. |
| authorisationCode | String | Identifier of the response - this may be used to match with the auth record in the Card Auth system. Stored in item.giftCardDetails.authorisationCode. |
| dateActivated | Date | Date on which the activation occurred. |
| customerName customerAddress | String Address | These will be populated if the Gift Card has been assigned to a customer (not normally the case). These are available to the enquiry details screen. |
| timeRequestCreated etc | Java Epoch time (ms since 1/1/1970) | Timestamps of authorisation activities. For performance information only. |
| expiryDate | Date/Time | Optional Expiry date. Not in example XML. Stored in item.giftCardDetails.expiryDate. |
| validFrom | Date/Time | Optional The gift card will only be valid from this date. Stored in item.giftCardDetails.validFrom. |
| decline | Boolean | Optional Decline the request. Displays NOT_AUTHORISED_NO_ACCOUNT message in Pos/GiftCard/GiftCardMessages. Not in example XML. |
Response - Failure
In this example the failure is a result of Gift Card Not Active, Not Found or Insufficient Balance.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<retail:cardAuthRequestResponse xmlns:core="http://www.enactor.com/core" xmlns:hta="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/api/200803" xmlns:htd="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/200803" xmlns:htt="http://docs.oasis-open.org/ns/bpel4people/ws-humantask/types/200803" xmlns:ns5="http://www.enactor.com/retail/storedRetailTransaction/service" xmlns:retail="http://www.enactor.com/retail" xmlns:sref="http://docs.oasis-open.org/wsbpel/2.0/serviceref" xmlns:tools="http://www.enactor.com/tools" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<retail:requesterId>dccee2b351e75e42:-c260ab8:18d867a989a:-2a1a</retail:requesterId>
<retail:request xsi:type="retail:GiftCardAuthorisationRequest">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T10:20:29Z</retail:transactionDateTime>
<retail:expectResponse>true</retail:expectResponse>
<retail:accountId>14410050</retail:accountId>
<retail:cardNumber>14410050</retail:cardNumber>
<retail:giftCardTypeId>GC_UK</retail:giftCardTypeId>
<retail:transactionCurrencyId>GBP</retail:transactionCurrencyId>
<retail:acquirerId>
<retail:acquirerId>GIFT_CARD</retail:acquirerId>
<retail:groupId groupHierarchyId="All" groupTypeId="region">ALL</retail:groupId>
</retail:acquirerId>
<retail:locationId>0001</retail:locationId>
<retail:terminalNumber>1</retail:terminalNumber>
<retail:transactionId>02920059000092002201701408</retail:transactionId>
<retail:transactionLineNumber>2</retail:transactionLineNumber>
<retail:transactionNumber>9</retail:transactionNumber>
<retail:userId>0001</retail:userId>
<retail:additionalData/>
<retail:actionType>REVERSE</retail:actionType>
<retail:transactionType>REDEEM</retail:transactionType>
<retail:amount>5000</retail:amount>
</retail:request>
<retail:response xsi:type="retail:GiftCardAuthorisationResponse" previousBalance="500" outcome="BalanceNotSufficient" minimumValue="500" giftCardTypeId="GC_UK" giftCardDescription="Gift Card UK" cardCurrencyId="GBP" balance="500" status="INVALID" accountId="14410050">
<retail:deviceID>pos1@0001.enactor</retail:deviceID>
<retail:messageNumber>0</retail:messageNumber>
<retail:retryCount>0</retail:retryCount>
<retail:terminalId></retail:terminalId>
<retail:transactionDateTime>2020-02-22T10:20:29Z</retail:transactionDateTime>
<retail:decline>true</retail:decline>
<retail:expiryDate/>
<retail:validFrom/>
<retail:customerName/>
<retail:customerAddress>
<retail:countryCodeId></retail:countryCodeId>
<retail:typeId></retail:typeId>
<retail:isTemplate>false</retail:isTemplate>
</retail:customerAddress>
</retail:response>
<retail:attempts>1</retail:attempts>
<retail:timeRequestCreated>1707379534327</retail:timeRequestCreated>
<retail:timeRequestReceived>1707379534327</retail:timeRequestReceived>
<retail:timeRequestAccepted>1707379534327</retail:timeRequestAccepted>
<retail:timeRequestAllocated>1707379534328</retail:timeRequestAllocated>
<retail:timeRequestSent>1707379534328</retail:timeRequestSent>
<retail:timeResponseReceived>1707379534336</retail:timeResponseReceived>
<retail:timeResponseSent>1707379534336</retail:timeResponseSent>
<retail:hasFailedOver>false</retail:hasFailedOver>
<retail:expectResponse>true</retail:expectResponse>
</retail:cardAuthRequestResponse>
The following table describes each element of a failed GiftCardAuthorisationRequest response:
| Element | Type | Description |
|---|---|---|
| cardAuthRequestResponse/ | ||
| response@outcome | String | Provides the reason for the failure:
|
| response@status | String | INVALID. Indicates an invalid response. |
| response@accountId | String | Account ID that was searched for. |
| cardAuthRequestResponse/response/ | ||
| decline | Boolean | If true, it indicates that the request has been rejected by the Card Auth service. |