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"
    }

Development