Testing Card PostAuth

The PostAuth operation of the Web Services API is used to finalise the capture of an amount from a customer's credit/debit card that was previously reserved with preAuth.

This is often used in online situations to capture money only when a product is shipped to a customer, some time after the initial purchase was made on the web store.

The steps below will show you how to use the PostAuth 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 PostAuth simulator
2. Make a preAuth transaction
3. Build the XML body
4. Send the request to the postAuth simulator
5. Parse the postAuth response

Step 1: Open the PostAuth simulator

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

To open the simulator interface, login to your Authipay Developer Playground account and click "OPEN" on the "card-postAuth" 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 postAuth 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 postAuth testing.
• Settings: real-world settings you can activate for your testing, including MCC 6012, DCC, latency delays, etc.

Step 2: Make a preAuth transaction

A postAuth goes hand-in-hand with a preAuth. The preAuth transaction reserves the charge amount to be captured by the subsequent postAuth transaction. They are connected by the OrderId parameter.

Complete a preAuth transaction. Record the OrderId value in the response. Use this in the next step below.

Step 3: Build the XML body

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

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

1. The Payment block describes the amount that was previously reserved on the card ("ChargeTotal") and the currency (currency codes follow the ISO-4217).
2. The TransactionDetails block is crucial. It contains the OrderID that was returned by the corresponding preAuth.

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 postAuth simulator.

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

    <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>postAuth</v1:Type>
         </v1:CreditCardTxType>
         <v1:Payment>
            <v1:ChargeTotal>59.00</v1:ChargeTotal>
            <v1:Currency>978</v1:Currency>
         </v1:Payment>
         <v1:TransactionDetails>
            <v1:OrderId>
               703d2723-99b6-4559-8c6d-797488e8977
            </v1:OrderId>
         </v1:TransactionDetails>
      </v1:Transaction>
    </ipgapi:IPGApiOrderRequest>

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 postAuth simulator

Next, your code needs to send the assembled SOAP request to the postAuth 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 postAuth 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 postAuth 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 postAuth 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 postAuth 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:747370:A3864055474:PPXP:3009</ipgapi:ApprovalCode>
      <ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
      <ipgapi:Brand>VISA</ipgapi:Brand>
      <ipgapi:CommercialServiceProvider>AIBMS</ipgapi:CommercialServiceProvider>
      <ipgapi:OrderId>A-/6tzRT+AwSaskp8tJkk0fxZxHQBBR6fRJkCy6w==</ipgapi:OrderId>
      <ipgapi:IpgTransactionId>3864055474</ipgapi:IpgTransactionId>
      <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
      <ipgapi:ProcessorApprovalCode>747370</ipgapi:ProcessorApprovalCode>
      
      <ipgapi:ProcessorReferenceNumber>747370</ipgapi:ProcessorReferenceNumber>
      <ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
      <ipgapi:ProcessorResponseMessage>AUTH CODE:747370</ipgapi:ProcessorResponseMessage>
      <ipgapi:ReferencedTDate>-2062452670</ipgapi:ReferencedTDate>
      <ipgapi:TDate>1537547330</ipgapi:TDate>
      <ipgapi:TDateFormatted>2018.09.21 16:28:50</ipgapi:TDateFormatted>
      <ipgapi:TerminalID>38812414</ipgapi:TerminalID>
      <ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
      <ipgapi:TransactionTime>1537547330</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 postAuth simulator.