Skip to main content

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​

rawResponseExtractsTypeDescription
parameterNamestringThe name of the response parameter to be displayed in the rawResponseExtracts.
regexstringRegular expression to locate relevant information within the gatewayResponse.rawResponse.

See Regex Handling for additional information.

Example Request​

Request
{
  ... // other request parameters
  "rawResponseExtracts": [
    {
      "parameterName": "rawAVS",
      "regex": "(?<=\\\"avsResultRaw\\\":\\\")([0-9])"
    },
    {
      "parameterName": "rawCVC",
      "regex": "(?<=\\\"cvcResultRaw\\\":\\\")([A-Z0-9])"
    }
  ]
}

Response Object​

rawResponseExtractsTypeDescription
successfularray of stringsThis array contains a list of the parameterNames for which the respective regex found one or more matches within the gatewayResponse.rawResponse.
extractsobject containing key-value-pairsEach parameter* that returned a match as "<parameterName>":"<regex match>" key-value pairs.
*See Multiple Match Handling
issuesarray of parameterName and message stringsThis 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.
- parameterNamestringparameterName as specified in the request
- messagestringDetails 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"
}

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.

Last updated on