API method specifications
API call method: process authorisation request
Description: Contis will call the client’s URL to post the authorisation details. The post will contain the fields mentioned under RequestInfo object below.
The client processes the authorisation request from Contis and responds with either approved or declined authorisation message.
Example:
If the request is valid, then ResponseCode is = 00 (i.e. approved). If the request is declined, the ResponseCode is either 07, 12 or 13 (i.e. declined).
METHOD NAME | INPUT PARAMETERS | OUTPUT PARAMETERS |
ProcessAuthorizationRequest | RequestInfo | ResponseInfo |
RequestInfo
REQUESTINFO FIELDS | NOTATION | TYPE | SIZE | DESCRIPTION |
CardID | M | integer | Card ID for which the authorisation is requested. | |
AuthorizationID | M | integer | Unique ID for authorisation. | |
AuthorizationAmount | M | integer |
The amount authorised for the transfer. The amount will be passed as a minor unit. Example: If Authorisation Amount = 11.20, then the field value will be passed as = 11.20 *100 = 1120 |
|
AcceptorNameLocation | M | string | 64 | Card acceptor’s location. |
AcceptorCountryCode | M | integer |
Card acceptor’s country code. It is the 3-digit ISO Code. For Example: If location is US, then its CountryCode = 840. |
|
AuthorizationType | M | string | 2 | Authorisation Type ID. Refer Lookup AuthorizationTypes. |
CardTransactionID | M | integer | Unique identifier of the card’s transaction. | |
MCC | O | integer | 4 | Merchant Category Code |
AcceptorIdCode | O | string | 20 | Merchant Id |
ResponseInfo
RESPONSEINFO FIELDS | NOTATION | TYPE | SIZE | DESCRIPTION |
ResponseCode | M | string | 2 |
ResponseCode=00 indicates that the requested action is successful (i.e. approved). Other Response Codes indicate that the requested action is not successful as shown below (i.e. declined). |
AccountBalance | C | integer |
This field needs to be provided for all successful responses, with the balance amount in the cardholder’s account. The amount has to be in minor unit, For Example: Balance amount = 11.20 then AccountBalance = 1120 (i.e. 11.20 *100). |
Contis API service notifies the client about approved and declined buffer account authorisations.
Notations
NOTATION | MEANING |
M | Mandatory |
O | Optional |
C | Conditional |
RESPONSE CODES | MEANING |
00 | Approved |
07 | Declined |
13 | Closed |
12 | Suspended |
Buffer account webhook parameters
PARAMETERS | TYPE | DESCRIPTION | DEFAULT VALUE |
NotificationType | string | Three-digit unique identifier of notification. Numeric value “057” denotes the Buffer account notification. | 057 |
CardID | integer | Unique Identifier of the card | |
AuthorizationID | integer | Unique Identifier of the authorisation | |
AuthorizationAmount | integer | Authorised Amount value that is sent in the authorisation. Amount is in minor unit. For Example: Value = 11.20, then AuthorizationAmount field value = 1120 (i.e., 11.20*100) |
|
AcceptorID | string | Unique identifier of facility, merchant or POS that accepts the consumer’s card for payment. It is a number that can be 1 to 15 digits long and in some cases contains a dash, “-“. Provided by VISA. | |
AcceptorNameLocation | string | Name and location of Acceptor that is sent in the authorisation | |
AcceptorCountryCode | integer | Acceptor’s Country Code value that is sent in the authorisation | |
MerchantCategoryCode | integer | Merchant category code value that is sent in authorisation | |
AuthorizationType | string | Authorisation Type value that is sent in the authorisation, Refer Authorisation look up value table. | |
IsAuthorizationRequested | bool | Whether authorisation was requested real time to client or not | |
IsApproved | bool | Final decision on the authorisation, Its Value = 1 (i.e. true) or 0 (i.e. false) | |
IsSTIP | bool | If authorisation went into STIP(Stand-In-Processing), then value will be 1 (i.e. true) else 0 (i.e. false) | |
DeclineReason | string | Why particular authorisation was declined. This field will be blank in case authorisation is approved | Blank |
SecurityHash | string | String value generated through hash logic with all of the above parameters(To verify the values posted on URL) with SHA2 | Blank |
Example of buffer account webhooks
PARAMETER NAME | VALUE |
NotificationType | 057 |
CardID | 14023 |
AuthorizationID | 636518098174087522 |
AuthorizationAmount | 100000 |
AcceptorID | VPP0000004043IP |
AcceptorNameLocation | ACQUIRER NAME CITY NAME GB |
AcceptorCountryCode | 826 |
MerchantCategoryCode | 5999 |
AuthorizationType | 01 |
IsAuthorizationRequested | 1 |
IsApproved | 0 |
IsSTIP | 0 |
DeclineReason | Authorisation was declined because buffer account balance was not enough. |
SecurityHash | d2b4ac8c39098991b0edf773007f14d13f4318f926c5ec86efc27d4a9af06645 |
Lookup table for Authorisation types
AUTHORISATION TYPE | DESCRIPTION |
01 | Purchase |
02 | E-commerce |
03 | ATM Withdrawal |
04 | Purchase Cashback |
06 | Balance Inquiry |
08 | Auto fuel dispense |
09 | Bill Payment |
10 | E-COMM without CVV2 |
11 | Mail phone order |
12 | Recurring |
13 | Quasi Cash Tran |
17 | Estimated |
18 | Estimated Partial |
19 | COF (Credential-On-File) |
To generate the Security Hash
Hash sequence : NotificationType&CardID&AuthorizationID&AuthorizationAmount&AcceptorID&AcceptorNameLocation&AcceptorCountryCode&MerchantCategoryCode&AuthorizationType&IsAuthorizationRequested&IsApproved&IsSTIP&DeclineReason&HashPAN Key
HashDataString :057&14023&636737562510588825&100&ACQUIRER NAME CITY NAME US&840&03&1&0&IP &5999&0&& SecurityKey : abcdefghijklmnop HashGenerationData : HashDataString + SecurityKey Hash : d2b4ac8c39098991b0edf773007f14d13f4318f926c5ec86efc27d4a9af06645
Note: In this example, the SecurityKey = is the “Hash PAN Key” provided to the client in the API configuration file.
Sample request and response codes
JSON Request:
{ "Username": "testUser", "Password": "JwhxoahH+qH0DT3bF4JgzfdM33aIKXwdmv+NZNK+EE4Vigp26Shi Q4W+GOh+gKISF7L2BUhP0F4lNVxSUqJtuL6uWLkZG3ExNNDdqG17 /Qw28udxe0hj0y//JXmB7reLC15SN68cJr6wUATC0R4oGmZ4/NoE M3xtvtMfh9ar/WYGpR1vEYEX3wpq/z6id5N7ISuxepJDNpv6cFI5 Rhae0IWEMqsE6T9PXo4py/cArclfFZ+fec3oSR4gQ1spTc+4cSjr W2KtUyZxhddLJlWw3CcQyXirasZW5DM6SUyuQPq/DA3Y829OuqNi 5MM/r/R/qkEGgnFBH2NNjpxWxf20zg==", "RequestReference": "Test Request" }
JSON Response: For Approval
{ "AccountBalance":10000, "ResponseCode":"00" }
JSON Response: For Decline
{ "AccountBalance":0, "ResponseCode":"03" }