Adding Response Parameters
Use regular expressions to extract data from the gateway's raw response
Overview
The recommended approach to handling the result of a transaction through Payment Services is to deserialize the 3rd-party API's raw response so that the results can be processed by your application with the most flexibility.
An alternative to deserializing the raw response is to extract relevant pieces using regular expressions specific to each 3rd-party's API. This alternative - when applied to one or many gateways - can provide a set of consistent response parameters that are applicable to your application's use of Payment Services.
The rawResponseExtracts request parameter is applicable to all Payment Services requests. It is an array of parameterName and regex pairs. When sent, a corresponding rawResponseExtracts object is returned in the gatewayResponse below the gatewayResponse.rawResponse.
Request Object
| rawResponseExtracts | Type | Description |
|---|---|---|
| parameterName | string | The name of the response parameter to be displayed in the rawResponseExtracts. |
| regex | string | Regular expression to locate relevant information within the gatewayResponse.rawResponse.See Regex Handling for additional information. |
Example Request
{
... // other request parameters
"rawResponseExtracts": [
{
"parameterName": "rawAVS",
"regex": "(?<=\\\"avsResultRaw\\\":\\\")([0-9])"
},
{
"parameterName": "rawCVC",
"regex": "(?<=\\\"cvcResultRaw\\\":\\\")([A-Z0-9])"
}
]
}
Response Object
| rawResponseExtracts | Type | Description |
|---|---|---|
| successful | array of strings | This array contains a list of the parameterNames for which the respective regex found one or more matches within the gatewayResponse.rawResponse. |
| extracts | object containing key-value-pairs | Each parameter* that returned a match as "<parameterName>":"<regex match>" key-value pairs.*See Multiple Match Handling |
| issues | array of parameterName and message strings | This array contains a list of the parameterNames for which a match was not returned or other issue occurred - such as being an invalid regex or evaluation timeout. |
| - parameterName | string | parameterName as specified in the request |
| - message | string | Details the issue that occurred during processing which prevented the parameter from being added to the extracts. |
Example Responses
{
"gatewayResponse": {
"rawResponse": "{\"additionalData\":{\"liabilityShift\":\"false\",\"authCode\":\"007616\",\"avsResult\":\"2 Neither postal code nor address match\",\"PaymentAccountReference\":\"1udPUR06K21T2pK15sZICRDNH3i7l\",\"threeDOffered\":\"false\",\"networkTxReference\":\"8R5EU8USE1219\",\"refusalReasonRaw\":\"AUTHORISED\",\"expiryDate\":\"3\/2030\",\"cvcResult\":\"5 Issuer not certified for CVC\/CVV\",\"avsResultRaw\":\"2\",\"threeDAuthenticated\":\"false\",\"paymentMethod\":\"mc\",\"retry.attempt1.shopperInteraction\":\"Ecommerce\",\"cvcResultRaw\":\"U\",\"acquirerCode\":\"TestPmmAcquirer\",\"acquirerReference\":\"c999iiVdDDG\"},\"pspReference\":\"RH3QB8XG3HNG5S82\",\"resultCode\":\"Authorised\",\"amount\":{\"currency\":\"USD\",\"value\":13},\"merchantReference\":\"merchantResponseParamDemo\",\"paymentMethod\":{\"brand\":\"mc\",\"type\":\"scheme\"}}",
"rawResponseExtracts": {
"successful": [
"rawAVS",
"rawCVC"
],
"extracts": {
"rawAVS": "2",
"rawCVC": "U"
}
},
... // other gatewayResponse parameters
},
"referenceNumber": "23121910202791562606",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"gatewayResponse": {
"rawResponse": "{\"additionalData\":{\"liabilityShift\":\"false\",\"authCode\":\"054879\",\"avsResult\":\"2 Neither postal code nor address match\",\"PaymentAccountReference\":\"tc5eEJbpqabYyNTZMBG7Aq2p1OLDM\",\"threeDOffered\":\"false\",\"networkTxReference\":\"VXDIBTAUR1219\",\"refusalReasonRaw\":\"AUTHORISED\",\"expiryDate\":\"3\/2030\",\"cvcResult\":\"5 Issuer not certified for CVC\/CVV\",\"avsResultRaw\":\"2\",\"threeDAuthenticated\":\"false\",\"paymentMethod\":\"mc\",\"retry.attempt1.shopperInteraction\":\"Ecommerce\",\"cvcResultRaw\":\"U\",\"acquirerCode\":\"TestPmmAcquirer\",\"acquirerReference\":\"388483Z3TMS\"},\"pspReference\":\"D35X2L9CCF8B8P65\",\"resultCode\":\"Authorised\",\"amount\":{\"currency\":\"USD\",\"value\":13},\"merchantReference\":\"merchantResponseParamDemo\",\"paymentMethod\":{\"brand\":\"mc\",\"type\":\"scheme\"}}",
"rawResponseExtracts": {
"successful": [
"rawAVS",
"rawCVC"
],
"issues": [
{
"parameterName": "retryAdvice",
"message": "(?<=\\\"retryAdvice\\\":\\\")([A-Z0-9]{1,2}) failed to return a match."
}
],
"extracts": {
"rawAVS": "2",
"rawCVC": "U"
}
},
... // other gatewayResponse parameters
},
"referenceNumber": "23121910234677457598",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"gatewayResponse": {
"rawResponse": "{\"additionalData\":{\"liabilityShift\":\"false\",\"authCode\":\"025069\",\"avsResult\":\"2 Neither postal code nor address match\",\"PaymentAccountReference\":\"DyvGpymAz4Jw29sbWCiGYtc8Nmk7e\",\"threeDOffered\":\"false\",\"networkTxReference\":\"CKPQDVGCQ1219\",\"refusalReasonRaw\":\"AUTHORISED\",\"expiryDate\":\"3\/2030\",\"cvcResult\":\"5 Issuer not certified for CVC\/CVV\",\"avsResultRaw\":\"2\",\"threeDAuthenticated\":\"false\",\"paymentMethod\":\"mc\",\"retry.attempt1.shopperInteraction\":\"Ecommerce\",\"cvcResultRaw\":\"U\",\"acquirerCode\":\"TestPmmAcquirer\",\"acquirerReference\":\"XCXCMZWKHSJ\"},\"pspReference\":\"XBZ8KVZ4F7TG5S82\",\"resultCode\":\"Authorised\",\"amount\":{\"currency\":\"USD\",\"value\":13},\"merchantReference\":\"merchantResponseParamDemo\",\"paymentMethod\":{\"brand\":\"mc\",\"type\":\"scheme\"}}",
"rawResponseExtracts": {
"successful": [
"rawCVC",
"AVSValues"
],
"extracts": {
"rawCVC": "U",
"AVSValues1": "2 Neither postal code nor address match",
"AVSValues2": "2"
}
},
... // other gatewayResponse parameters
},
"referenceNumber": "23121910290213647798",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
{
"gatewayResponse": {
"rawResponse": "{\"additionalData\":{\"liabilityShift\":\"false\",\"authCode\":\"085877\",\"avsResult\":\"2 Neither postal code nor address match\",\"PaymentAccountReference\":\"wM67LEcYKDQ0A7Cvm37ppNiQclr58\",\"threeDOffered\":\"false\",\"networkTxReference\":\"7OO8NM2131219\",\"refusalReasonRaw\":\"AUTHORISED\",\"expiryDate\":\"3\/2030\",\"cvcResult\":\"5 Issuer not certified for CVC\/CVV\",\"avsResultRaw\":\"2\",\"threeDAuthenticated\":\"false\",\"paymentMethod\":\"mc\",\"retry.attempt1.shopperInteraction\":\"Ecommerce\",\"cvcResultRaw\":\"U\",\"acquirerCode\":\"TestPmmAcquirer\",\"acquirerReference\":\"CX5ZZCX6N8W\"},\"pspReference\":\"LJMN98PV7NK2WN82\",\"resultCode\":\"Authorised\",\"amount\":{\"currency\":\"USD\",\"value\":13},\"merchantReference\":\"merchantResponseParamDemo\",\"paymentMethod\":{\"brand\":\"mc\",\"type\":\"scheme\"}}",
"rawResponseExtracts": {
"successful": [
"rawCVC"
],
"issues": [
{
"parameterName": "AVSValues",
"message": "Regex failed processing: Invalid pattern '(?<=\\\"avs[a-zA-Z]+\\\":\\\")([a-zA-Z0-9 ]+' at offset 38. Not enough )'s."
}
],
"extracts": {
"rawCVC": "U"
}
},
... // other gatewayResponse parameters
},
"referenceNumber": "2312191031106105958",
"success": true,
"error": "",
"message": "",
"thirdPartyStatusCode": "200"
}
Multiple Match Handling
When a regex returns multiple matches, the parameterName is added to the successful array and the matches are added to the extracts with the parameterName incremented + 1 for each match. See the Multiple Matches example response above.
Updated 3 months ago