Testing Card PreAuth

The PreAuth operation of the Web Services API is used to reserve - but not capture - an amount from a customer's credit/debit card. The reserved amount can be later captured with a separate PostAuth.

This is often used in online situations where money for a purchase is not taken from a customer card until a purchased item is shipped.

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

1. View the PreAuth simulator
2. Build the XML body
3. Send the request to the preAuth simulator
4. Parse the preAuth response

Step 1: Open the PreAuth simulator

For the purposes of making test PreAuth transaction, you'll be using the PreAuth simulator in the Authipay Developer Playground.

To open the simulator interface, login to your Authipay Developer Playground account and click "OPEN" on the "card-preAuth" bookmark on your dashboard. You'll see the following sections in your simulator:

• Integrate: coding instructions in various languages to help you connect your code to the simulator.
• Debug: use the Live Log to watch transctions being processed in real-time. Or download the file-based logs.
• Test: a map of real PreAuth response codes that you can trigger with values in your test requests. Or custom your own.
• Reports: real-time test reports showing the frequency and coverage of your PreAuth testing.
• Settings: real-world settings you can activate for your testing, including MCC 6012, DCC, latency delays, etc.

Step 2: Build the XML body

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

The XML body of the preAuth transaction has 2 main parts: (1) the CreditCardData block and (2) Payment block.

1. The CreditCardData block holds all the credit/debit card values that your customer has filled in on your checkout form. Typically this includes: the card number (PAN), expiry month, expiry year and card code value (a.k.a. CVV)
2. The Payment block describes the amount to be reserved on the card ("ChargeTotal") and the currency (currency codes follow the ISO-4217).

Remember: your can trigger different responses from the simulator by the values you use in the requests. By default, the simulator will use ChargeTotal value as the trigger value. But you can also configure the simulator to use the card CVV value or cardholder name - go the Settings tab of the preAuth simulator.

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

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:v1="http://ipg-online.com/ipgapi/schemas/ipgapi"
    xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Body>
    <ipgapi:IPGApiOrderRequest
        xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1"
        xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi">
      <v1:Transaction>
        <v1:CreditCardTxType>
          <v1:Type>preAuth</v1:Type>
        </v1:CreditCardTxType>
        <v1:CreditCardData>
          <v1:CardNumber>5314332286004578</v1:CardNumber>
          <v1:ExpMonth>02</v1:ExpMonth>
          <v1:ExpYear>22</v1:ExpYear>
        </v1:CreditCardData>
        <v1:Payment>
          <v1:ChargeTotal>19.00</v1:ChargeTotal>
          <v1:Currency>978</v1:Currency>
        </v1:Payment>
      </v1:Transaction>
    </ipgapi:IPGApiOrderRequest>
  </env:Body>
</env:Envelope>

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 3: Send the request to the preAuth simulator

Next, your code needs to send the assembled SOAP request to the preAuth 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 preAuth 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

API_KEY is placeholder for your actual API key that you will find on your simulator pages in the Developer Playground.

Step 4: Parse the preAuth 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 preAuth response. This is an XML document that contains information about the transaction: the result from the gateway, the bank authorisation result, DCC information, etc.

The example show below shows the response to a preAuth 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:529134:A4509352455:PPXP:7881</ipgapi:ApprovalCode>
      <ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
      <ipgapi:Brand>VISA</ipgapi:Brand>
      <ipgapi:CommercialServiceProvider>AIBMS</ipgapi:CommercialServiceProvider>
      <ipgapi:OrderId>A-Tg9Z/0J+V0fjM/xv2eauCsWUiPkcOaHhmXCttg==</ipgapi:OrderId>
      <ipgapi:IpgTransactionId>4509352455</ipgapi:IpgTransactionId>
      <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
      <ipgapi:ProcessorApprovalCode>529134</ipgapi:ProcessorApprovalCode>
      <ipgapi:ProcessorCCVResponse>P</ipgapi:ProcessorCCVResponse>
      <ipgapi:ProcessorReferenceNumber>529134</ipgapi:ProcessorReferenceNumber>
      <ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
      <ipgapi:ProcessorResponseMessage>AUTH CODE:529134</ipgapi:ProcessorResponseMessage>
      
      <ipgapi:TDate>1537544672</ipgapi:TDate>
      <ipgapi:TDateFormatted>2018.09.21 15:44:32</ipgapi:TDateFormatted>
      <ipgapi:TerminalID>53182590</ipgapi:TerminalID>
      <ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
      <ipgapi:TransactionTime>1537544672</ipgapi:TransactionTime>
    </ipgapi:IPGApiOrderResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The ApprovalCode parameter tells you the result of the transaction.

• 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.

Remember: you can trigger any ApprovalCode you'd like from the simulator by the values you use in your request. By default, the simulator will use the ChargeTotal value as the trigger value. But you can also configure the simulator to use the card CVV value or cardholder name - go the Settings tab of the preAuth simulator.