Testing Card Return

The Return operation of the Web Services API is used to return the result of a Sale, PreAuth, ForceTicket or Credit transaction.

The steps below will show you how to use the Return simulator to build a transaction. Our examples here uses a simple cURL request, but the same steps apply to any coding language.

1. Build the XML body
2. Send the request to the Return simulator
3. Parse the Return response

Step 1: Build the XML body

In a nutshell: your code must first assemble a XML document with the fields for a Return transaction, then wrap the XML into the body of a SOAP request.

The XML body of a Return transaction requires an OrderId and a Payment block. These are used to identify the transaction which you want to return.

1. The OrderId identifies a particular transaction that should be returned.
2. The Payment block describes the amount to be debited ("ChargeTotal") and the currency (currency codes follow the ISO-4217).

Remember you can trigger different responses from the simulator by varying the values you send in. By default the simulator will use ChargeTotal as the trigger value.

Below is an example SOAP request containing the minimum XML fields needed for a Return transaction.

For the purposes of making a manual cURL transaction, paste the above example into a text editor and save it locally as an XML file, say, example.xml.

Step 2: Send the request to the Return simulator

Next, your code needs to send the assembled SOAP request to the Return simulator. The URL to POST to can be found under the "Integration" tab of the simulator - make sure to copy&paste this URL from your simulator as it contains your unique API_KEY.

The example show below shows how to make a Return transaction using cURL. The example.xml contains the constructed SOAP request.

curl -X POST -d @example.xml \
    https://api.testingpays.com/API_KEY/authipay/v1/ipgapi/services

Step 3: Parse the Return response

The simulator will first validate your request. If it detects any issues, you'll see a verbose response indicating what is wrong with the request.

If the simulator detects no issues, then it will simulate a Return response that contains information about the transaction such as: the result from the gateway, the bank authorisation result, DCC information, etc.

The example show below shows the response to a Return transaction sent manually by cURL command to the simulator.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header/>
  <SOAP-ENV:Body>
    <ipgapi:IPGApiOrderResponse xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
    <ipgapi:ApprovalCode>Y:701855:A3876712893:PPXP:3169</ipgapi:ApprovalCode>
    <ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
    <ipgapi:Brand>VISA</ipgapi:Brand>
    <ipgapi:CommercialServiceProvider>AIBMS</ipgapi:CommercialServiceProvider>
    <ipgapi:OrderId>A-1rcaectwzYQr8Hd764BgFl7HhmuHjCnl2zpQSQ==</ipgapi:OrderId>
    <ipgapi:IpgTransactionId>3876712893</ipgapi:IpgTransactionId>
    <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
    <ipgapi:ProcessorApprovalCode>701855</ipgapi:ProcessorApprovalCode>
    <ipgapi:ProcessorReferenceNumber>701855</ipgapi:ProcessorReferenceNumber>
    <ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
    <ipgapi:ProcessorResponseMessage>AUTH CODE:701855</ipgapi:ProcessorResponseMessage>
    <ipgapi:ReferencedTDate>-2062454204</ipgapi:ReferencedTDate>
    <ipgapi:TDate>1537545796</ipgapi:TDate>
    <ipgapi:TDateFormatted>2018.09.21 16:03:16</ipgapi:TDateFormatted>
    <ipgapi:TerminalID>93487987</ipgapi:TerminalID>
    <ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
    <ipgapi:TransactionTime>1537545796</ipgapi:TransactionTime>
    </ipgapi:IPGApiOrderResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The important parameter to look for in the response is the ApprovalCode.

• If it starts with ‘Y’, then the transaction was approved.
• If it starts with ‘N’ followed by a colon ‘:’ and a negative number, that means the transaction failed and the negative number is the response code.