Buffer Account – Partner Integration
API integration overview
Solaris calls the URL specified by the partner, sending the authorization request details. This payload will contain the fields detailed in the Request Payload table below.
The partner processes the authorization request and responds with either an approved or declined authorization message, as shown in the Response Payload section.
Request Payload
AuthorizationID Field
The AuthorizationID field holds an integer value. Values in this field may however exceed the maximum value of standard integer (int) and Number types common in some environments and need to be parsed as long or big integer etc., depending on your particular environment to avoid issues.
| Field | Type | Description |
|---|---|---|
| CardID | integer | Card ID for which the authorization is requested. |
| AuthorizationID | integer | Unique ID for the authorization. |
| AuthorizationAmount | integer | The amount authorized for the transfer, inclusive of fees and converted into the partner's program base currency. This value is represented in minor units - for example a value of 11.20 will be sent as 1120. |
| AcceptorNameLocation | string | Card acceptor's location. |
| AcceptorCountryCode | integer | Card acceptor's country code. It is the 3-digit ISO Code. For Example: If location is US, then its CountryCode = 840. |
| AuthorizationType | string | Authorization Type - refer to the Authorization Types lookup table. |
| CardTransactionID | integer | Unique identifier of the card's transaction. |
| MCC | integer | Merchant Category Code. |
| AcceptorIdCode | string | Merchant Id. |
Example Request Payload
{
"AcceptorCountryCode": 840,
"AcceptorIdCode": "VIP4003IP",
"AcceptorNameLocation": "ACQUIRER NAME CITY NAME US",
"AuthorizationAmount": 1100,
"AuthorizationID": 2637762136219995595,
"AuthorizationType": "01",
"CardID": 102331,
"CardTransactionID": 7765598572078195,
"MCC": 5999
}Response Payload
| Field | Type | Description |
|---|---|---|
| ResponseCode | string | Response from the partner indiciating whether the request was successful (approved) or not. Code "00" Indicates that the requested action approved. Refer to the Response Code lookup table for more information. |
| AccountBalance | integer | The balance amount in the cardholder's account. This value is represented in minor units - for example a value of 11.20 should be sent as 1120 . |
Example approval response payload
{
"AccountBalance":10000,
"ResponseCode":"00"
}Example decline response payload
{
"AccountBalance":0,
"ResponseCode":"13"
}Lookup Tables
Authorization Types lookup table
| authorization 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) |
Response Code lookup table
| Response Code | Status |
|---|---|
| 00 | Approved |
| 07 | Declined |
| 12 | Suspended |
| 13 | Closed |
Buffer account webhook parameters
| Parameter | Type | Description |
|---|---|---|
| NotificationType | string | Three-digit identifier of the notification type. "057" denotes the Buffer account notification. |
| CardID | integer | Unique Identifier of the card |
| AuthorizationID | integer | Unique Identifier of the authorization |
| AuthorizationAmount | integer | The amount authorised for the transfer, inclusive of fees and converted into the partner's program base currency. This value is represented in minor units - for example a value of 11.20 will be sent as 1120. |
| 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 |
| AuthorizationType | string | Authorization Type value that is sent in the authorization, Refer to the Authorization look up value table. |
| 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) |
| 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 authorization |
| IsAuthorizationRequested | bool | Whether authorization was requested real time to partner or not |
| DeclineReason | string | Why particular authorization was declined. This field will be blank in case authorization is approved |
| CardTransactionID | string | Unique identifier of the card's transaction. |
| TransactionFeeVariable | integer | The total value of all fees (such as POS and ATM withdrawal fees) applied to the transaction, in the partner's program base currency. |
| InstructionType | string | Advises the receiving partner of the nature and circumstances of the incoming notification. Possible values are:
|
| BufferMoneyMoveAmount | integer | A signed numerical value (with 2 implied decimal places) reflecting the value and direction of the money movement |
| OriginalAuthorizationID | string | Provided where a complete transaction (one that is made up of multiple sequences of acquirer-side actions - such as reversals or Automated Fuel Dispensers (AFD)) causes the generation of an additional AuthorizationID. In these cases, the Original Authorization ID is provided. |
| SecurityHash | string | Contains the hash of the payload values and your webhook security key, to verify the origin and integrity of the notification. |
Example Buffer account webhook
{
"NotificationType": "057",
"CardID": "14023",
"AuthorizationID": "636518098174087522",
"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.",
"CardTransactionID": "7765598572078195",
"TransactionFeeVariable": "1000",
"InstructionType": "Authorization",
"BufferMoneyMoveAmount": "217",
"OriginalAuthorizationID": "2372305181447146021",
"SecurityHash": "e3c20886fc794cbb4c6d870466fd16c4d2bae114f56e4d84768a5ad3a9ef38c1"
}Validating the notification security hash
Security Hash validation
See the respective guide for more information on calculating and verifying the notification security hash.
To compute the hash of the notification payload, concatenate the payload values in the following sequence, with your webhook security key as the final item:
<NotificationType>&<CardID>&<AuthorizationID>&<AuthorizationAmount>&<AcceptorNameLocation>&<AcceptorCountryCode>&<AuthorizationType>&<IsApproved>&<IsSTIP>&<AcceptorID>&<MerchantCategoryCode>&<IsAuthorizationRequested>&<DeclineReason>&<CardTransactionID>&<TransactionFeeVariable>&<InstructionType>&<BufferMoneyMoveAmount>&<OriginalAuthorizationID>&<webhook-security-key>The payload values above and example webhook security key of abcdefghijklmnop, will produce the following hash input:
057&14023&636518098174087522&100000&ACQUIRER NAME CITY NAME GB&826&1&0&0&VPP0000004043IP&5999&1&Authorisation was declined because buffer account balance was not enough.&7765598572078195&1000&Authorization&217&2372305181447146021&abcdefghijklmnop