Buffer Account – Client integration

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 Authorization Type ID. Refer Lookup AuthorizationTypes.
CardTransactionID M Integer
Unique identifier of the card’s transaction.

ResponseInfo

RESPONSEINFO FIELDS NOTATION TYPE SIZE DESCRIPTION
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 authorization
AuthorizationAmount integer Authorized Amount value that is sent in the authorization. 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 authorization
AcceptorCountryCode integer Acceptor’s Country Code value that is sent in the authorization
MerchantCategoryCode integer Merchant category code value that is sent in authorization
AuthorizationType string Authorization Type value that is sent in the authorization, Refer Authorization look up value table.
IsAuthorizationRequested bool Whether authorization was requested real time to client or not
IsApproved bool Final decision on the authorization, Its Value = 1 (i.e. true) or 0 (i.e. false)
IsSTIP bool If authorization went into STIP(Stand-In-Processing), then value will be 1 (i.e. true) else 0 (i.e. false)
DeclineReason string Why particular authorization was declined. This field will be blank in case authorization 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 Authorization 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:
     {
       "AcceptorNameLocation":"test Location US",
       "AuthorizationID":9223372036854775807,
       "AuthorizationAmount":92233,
   "AuthorizationType":"01",
       "AcceptorCountryCode":840,
       "CardID":21474
       "CardTransactionID":21455574
    }

    JSON Response: For Approval
    {
       "AccountBalance":10000,
       "ResponseCode":"00"
    }
   
    JSON Response: For Decline
    {
      "AccountBalance":0,
      "ResponseCode":"03"
    }