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 Name	State	Data Type	Description
tid	Mandatory	String	This is the serial number of the PAX IM30 that should process the transaction.
POST /cardAcquisition - Header Parameters
Authorization	Mandatory	String	This field should be populated with a value of Bearer 6945595921271780
POST /cardAcquisition - Body Parameters
cardacquisitionRequest	Mandatory	Object	Provides the required information to initiate a card acquisition sessionth axept® PRO.
POST /cardAcquisition - /cardAquisitionRequest Parameters
amount	Mandatory	Integer	Amount of the transaction in minor units not including cashback/tips etc. For example, £10.00 would be represented as 1000.
language	Optional	String	Must 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 Code	Description
201	Card 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..
400	Bad input parameter. Details would be returned in a text description
403	Not Authorised
408	Request 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"
}

HTTP/1.1 206 Transaction in progress
Content-Type: application/json
Date: Mon, 28 Jun 2021 13:01:08 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

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 Name	State	Data Type	Description
tid	Mandatory	String	This is the serial number of the PAX IM30 that should process the transaction.
uti	Mandatory	String	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
Authorization	Mandatory	String	This 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 Code	Description
200	A 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.
400	Bad input parameter. Details would be returned in a text description
403	Not Authorised
404	Session not found or status is not available
408	Request 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"
        }
    ]
}

HTTP/1.1 206 Transaction in progress
Content-Type: application/json
Date: Mon, 28 Jun 2021 13:01:08 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
 
{
  "DisplayData": 
  [
    {
      "value": 1,
      "description": "Transaction started"
    },
    {
      "value": 14,
      "description": "GetCard Screen Displayed"
    }
  ],
  "uti": "57ECEF34-75D8-4E67-B00C-F578DB261998"
}

`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 Name

Data Type

Description

uti

String

This is the Unique Transaction Identifier assigned by axept® PRO.

cardPan

String

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.

cardExpiryDate

String

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.

cardScheme

String

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

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

cardType

String

The methods of the card. Possible values are capture:

EMV	The card was inserted abd a chip was read.
MSR	The card was swiped and details captured via a magnetic stripe read.
CTLS	The card details were presented using contactless technology.
RFID	Used only when a MiFare card has been presented.
Manual	The card number was manually keyed in. Please note that this is disabled when operating in Unattended environments but has been documented for completeness.

cardToken

String

The Optomany token for the card used to complete the transaction.

DisplayData

Object Array

An 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 Name	State	Data Type	Description
tid	Mandatory	String	This is the serial number of the PAX IM30 that should process the transaction.
DELETE /cardAcquisition - Header Parameters
Authorization	Mandatory	String	This 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 Code	Description
200	Request successfully posted and transactions has been cancelled
400	Bad input parameter. Details would be returned in a text description
403	Not 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

Overview and Usage​

POST /cardAcquisition​

POST Example Request​

POST Response Fields​

POST Example Responses​

GET /cardAcquisition​

GET Example Request​

GET Response Fields​

GET Example Responses​

GET Response 200 Fields​

Card Acquisition Complete​

DELETE /cardAcquisition​

DELETE Example Request​

DELETE Response​

DELETE Example Response​

Overview and Usage

`POST` /cardAcquisition

`POST` Example Request

`POST` Response Fields

`POST` Example Responses

`GET` /cardAcquisition

`GET` Example Request

`GET` Response Fields

`GET` Example Responses

`GET` Response 200 Fields

Card Acquisition Complete

`DELETE` /cardAcquisition

`DELETE` Example Request

`DELETE` Response

`DELETE` Example Response