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