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. 57
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)
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
AuthorizationType string Authorisation Type value that is sent in the authorisation, Refer Authorisation look up value table.
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)
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.
MerchantCategoryCode integer Merchant category code value that is sent in authorisation
IsAuthorizationRequested bool Whether authorisation was requested real time to client or not
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 57
CardID 14023
AuthorizationID 6.36518E+17
AuthorizationAmount 100000
AcceptorNameLocation ACQUIRER NAME CITY NAME GB
AcceptorCountryCode 826
AuthorizationType 1
IsApproved 0
IsSTIP 0
AcceptorID VPP0000004043IP
MerchantCategoryCode 5999
IsAuthorizationRequested 1
DeclineReason Authorisation was declined because buffer account balance was not enough.
SecurityHash bb9b615c78276e6477e11331a0867cef22750e40c05d72f80868a696b47a35af

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&636518098174087522&100000&VPP0000004043IP&ACQUIRER NAME CITY NAME GB&826&5999&01&1&0&0&Authorisation was declined because buffer account balance was not enough.&
SecurityKey : abcdefghijklmnop
HashGenerationData : HashDataString + SecurityKey
Hash : bb9b615c78276e6477e11331a0867cef22750e40c05d72f80868a696b47a35af

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:

{
    "AcceptorCountryCode": 840,
    "AcceptorIdCode": "VIP4003IP",
    "AcceptorNameLocation": "ACQUIRER NAME CITY NAME US",
    "AuthorizationAmount": 1100,
    "AuthorizationID": 2637762136219995595,
    "AuthorizationType": "01",
    "CardID": 102331,
    "CardTransactionID": 7765598572078195,
    "MCC": 5999
}

JSON Response: For Approval

{
    "AccountBalance":10000,
    "ResponseCode":"00"
}

JSON Response: For Decline

{
    "AccountBalance":0,
    "ResponseCode":"03"
}