Card Acquisition

Overview and Usage

As we've shown previously, this is an optional step for you. By initiating a transaction using the /cardAcquisition URI, you will be asked to decide on whether or not to proceed after the card has been Acquired.

Best practice - MiFare cards

If you wish to accept MiFare cards, this flow becomes MANDATORY as MiFare cards can only be captured during Card Acquisition.

This section will show you how to enter Card Acquisition mode, and poll for the status of Card Acquisition. Card Acquisition mode is considered complete when you've received Response Code 200. At this point, you need to decide whether to proceed with a transaction or not.

This decision is made via the Transaction Request URI in the next section, but is presented in the flow below as well. It is assumed you'll be heading to Transaction Request knowing whether you wish to initiate a transaction or cancel the Card Acquisition process.

CardAcquisition Only


POST /cardAcquisition

URL

https://(TerminalIP):8080/POSitiveWebLink/1.1.0/rest/cardAcquisition

An HTTPS POST request should be sent to the above URL with the following parameters:

POST /cardAcquisition - Query String Parameters
Field NameStateData TypeDescription
tidMandatoryString

This is the serial number of the PAX IM30 that should process the transaction.

POST /cardAcquisition - Header Parameters
AuthorizationMandatoryStringThis field should be populated with a value of
Bearer 6945595921271780
POST /cardAcquisition - Body Parameters
cardacquisitionRequestMandatoryObjectProvides the required information to initiate a card acquisition sessionth axept® PRO.
POST /cardAcquisition - /cardAquisitionRequest Parameters
amountMandatoryInteger

Amount of the transaction in minor units not including cashback/tips etc. For example, £10.00 would be represented as 1000.

languageOptionalStringMust be set to en_GB

POST Example Request

Postman Request
POST https://192.168.10.44:8080/POSitiveWebLink/1.1.0/rest/cardAcquisition?tid=1640005297
HTTP/1.1
Content-Type: application/json
disablePrinting: true
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Host: 192.168.0.75:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 45
{
"amount": 500,
"langauge": "en_GB"
}

POST Response Fields

axept® PRO will return one of five response codes:

HTTP Response CodeDescription
201Card acquisition created.
206

Card acquisition in progress – a new card acquisition cannot be started until the current one completes.

If the UTI for the “in-flight” card acquisition request is known, it is advised to poll (via GET /cardAcquisition) using that UTI to determine when a card is presented.

If the UTI is not known, DELETE can be sent to /cardAcquisition to return axept® PRO to an idle state so a new POST /cardAcquisition can be sent..

400Bad input parameter.
Details would be returned in a text description
403Not Authorised
408Request timeout.

POST Example Responses

HTTP/1.1 201 Transaction Created
Content-Type: application/json
Date: Tue, 9 Feb 2021 16:29:04 GMT
Allow: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 86400
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Allow-Headers: *
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Encoding: gzip
Transfer-Encoding: chunked
{
"amount": 500,
"uti": "57ECEF34-75D8-4E67-B00C-F578DB261998"
}
note

If the HTTP response code is 201, the body of the response will include the Unique Transaction Identifier (UTI) assigned by axept® PRO.

You can now use GET /cardAcquisition to poll the status of axept® PRO while the Card is Acquired.


GET /cardAcquisition

URL

https://(TerminalIP):8080/POSitiveWebLink/1.1.0/rest/cardAcquisition

An HTTPS GET request should be sent to the above URL with the following parameters:

GET /cardAcquisition - Query String Parameters
Field NameStateData TypeDescription
tidMandatoryString

This is the serial number of the PAX IM30 that should process the transaction.

utiMandatoryString

This is the Unique Transaction Identifier that axept® PRO provided in the body of a response to a POST on the /cardAcquisition resource.

GET /cardAcquisition - Header Parameters
AuthorizationMandatoryStringThis field should be populated with a value of
Bearer 6945595921271780

GET Example Request

Postman Request
GET https://192.168.10.44:8080/POSitiveWebLink/1.1.0/rest/cardAcquisition?tid=1640005297&uti=ED66F12F-B1D0-40C1-8EFA-CDDC42881B30
HTTP/1.1
Content-Type: application/json
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Host: 192.168.0.75:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

GET Response Fields

In response to this, axept® PRO will return one of six response codes:

HTTP Response CodeDescription
200A result has been found for the specified UTI
206

Card acquisition in progress and the card has not been read yet. Session statuses will be returned as an array of objects in the body.

400Bad input parameter.
Details would be returned in a text description
403Not Authorised
404Session not found or status is not available
408Request timeout

You can use the HTTP response code to determine whether or not axept® PRO is still waiting for a card to be presented. All the while that a 206 is returned, you will know that a card has not yet been presented and read.

GET Example Responses

HTTP/1.1 200
Content-Type: application/json
Date: Tue, 9 Feb 2021 16:37:37 GMT
Allow: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 86400
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Allow-Headers: *
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Encoding: gzip
Transfer-Encoding: chunked
{
"cardExpiryDate": "2512",
"cardPan": "************0102",
"cardScheme": "Mastercard",
"cardToken": "WwcD4zbBoseyZD4dcSjIzjNSkif2kb0c0GIKuKLY3KcfMQ==",
"cardType": "CTLS",
"errorCode": "",
"errorText": "",
"softwareVersion": "2.00.00.5038",
"uti": "ED66F12F-B1D0-40C1-8EFA-CDDC42881B30",
"DisplayData": [
{
"value": 1,
"description": "Transaction started"
},
{
"value": 14,
"description": "GetCard Screen Displayed"
},
{
"value": 8,
"description": "Card type CTLS"
},
{
"value": 13,
"description": "Transaction Finished"
}
]
}

GET Response 200 Fields

As soon as a presented card has been successfully read, axept® PRO will respond to the GET with a 200 and the body of the response can include the following fields:

GET /cardAcquisition - Query String Parameters
Field NameData TypeDescription
utiStringThis is the Unique Transaction Identifier assigned by axept® PRO.
cardPanString

The masked PAN (Primary Account Number) of the card.

For traditional payment cards (Visa/Mastercard etc), the string length reflects the length of the PAN. Only the last 4 digits will be provided, the preceding digits are obfuscated with asterisks e.g. ************5454.

For MiFare cards, this field will be populated with the UID of the presented card.
In instances where axept® PRO is configured to use an authentication service for MiFare cards it is possible that this field will be blank. This will occur in instances where the presented MiFare card has been read but not been successfully authenticated.

cardExpiryDateString

The expiry date of the card used for the transaction.

Format is YYMM e.g. a card expiring in April 2022 will be expressed as 2204.

cardSchemeString

The name of the scheme used (e.g. Visa/Mastercard).

If a MiFare card has been presented, this field will specify “MIFARE”.

cardTypeString

The methods of the card. Possible values are capture:

EMVThe card was inserted abd a chip was read.
MSRThe card was swiped and details captured via a magnetic stripe read.
CTLSThe card details were presented using contactless technology.
RFIDUsed only when a MiFare card has been presented.
ManualThe card number was manually keyed in. Please note that this is disabled when operating in Unattended environments but has been documented for completeness.
cardTokenStringThe Optomany token for the card used to complete the transaction.
DisplayDataObject ArrayAn array of statuses for the transaction to show all stages during processing the request. Details of the possible values in this field are available in Display Data.

Card Acquisition Complete

Decision Required

At this point, /cardAcquisition is considered complete.

Once axept® PRO has read a card, it will sit in a ‘Please Wait’ state until the integrated client determines what to do next – perform a cancel (via a DELETE) or initiate a transaction. These methods are detailed in the next section, Transaction Request, using the /transaction URI.

You may however wish to cancel a /cardAcquisition request prior to receiving a Response Code 200. You can use the DELETE /cardAcquisition method at any time when you receive Response Code 206, as shown below.


DELETE /cardAcquisition

note

This functionality should only be used if your POST /cardAcquisition has returned Response Code 206 - card acquisition in progress. If you wish to cancel a /cardAcquisition after Response Code 200 has been received, you should use the Transaction Request DELETE found in the next section.

URL

https://(TerminalIP):8080/POSitiveWebLink/1.1.0/rest/cardAcquisition

An HTTPS DELETE request should be sent to the above URL with the following parameters:

DELETE /cardAcquisition - Query String Parameters
Field NameStateData TypeDescription
tidMandatoryString

This is the serial number of the PAX IM30 that should process the transaction.

DELETE /cardAcquisition - Header Parameters
AuthorizationMandatoryStringThis field should be populated with a value of
Bearer 6945595921271780

DELETE Example Request

Postman Request
DELETE https://192.168.10.44:8080/POSitiveWebLink/1.1.0/rest/cardAcquisition?tid=1640005297
HTTP/1.1
Content-Type: application/json
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Host: 192.168.0.75:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

DELETE Response

The below HTTP response status codes may be returned in response to the DELETE:

HTTP Response CodeDescription
200Request successfully posted and transactions has been cancelled
400Bad input parameter.
Details would be returned in a text description
403Not Authorised

The DELETE can be sent at any point after axept® PRO responds to the GET on /cardAcquisition with response code 200.

Best practice

axept® PRO will currently respond as below to a DELETE sent when Response Code 200 (Card Acquired Successfully) has been returned. We require you however to utilise the /transaction URI in the next section in this case as we cannot guarantee that future software versions will retain this functionality.

DELETE Example Response

HTTP/1.1 200
Content-Type: text/plain
Date: Tue, 9 Feb 2021 16:37:23 GMT
Allow: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 86400
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Allow-Headers: *
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Encoding: gzip
Transfer-Encoding: chunked