Testing Card Sale

The Sale operation of the Web Services API is used to authorise and take an amount from a customer's credit/debit card in one go.

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

1. Open the Sale simulator
2. Build the XML body
3. Send the request to the Sale simulator
4. Parse the Sale response

Step 1: Open the Sale simulator

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

To open the simulator interface, login to your Authipay Developer Playground account and click "OPEN" on the "card-sale" 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 Sale 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 Sale 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 Sale transaction, then wrap the XML into the body of a SOAP request.

The XML body of the Sale 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 debited ("ChargeTotal") and the currency (currency codes follow the ISO-4217).

Remember: you 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 Sale simulator.

Below is an example SOAP request containing the minimum XML fields needed for a Sale 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>sale</v1:Type>
        </v1:CreditCardTxType>
        <v1:CreditCardData>
          <v1:CardNumber>4314452386004578</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 Sale simulator

Next, your code needs to send the assembled SOAP request to the Sale 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 Sale 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 Sale 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 Sale 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 Sale 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>
    <SOAP-ENV:Fault>
      <faultcode>SOAP-ENV:Client</faultcode>
      <faultstring xml:lang="en">ProcessingException</faultstring>
      <detail>
        <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>N:-5005;The credit card you are using has been blocked_mask_card</ipgapi:ApprovalCode>
          <ipgapi:Brand>VISA</ipgapi:Brand>
          <ipgapi:CommercialServiceProvider>AIBMS</ipgapi:CommercialServiceProvider>
          <ipgapi:ErrorMessage>SGS-5005;The credit card you are using has been blocked_mask_card</ipgapi:ErrorMessage>
          <ipgapi:OrderId>A-z8SIJDx2UMb2BydORiIfE99F6kmAebTNp+FDPw==</ipgapi:OrderId>
          <ipgapi:IpgTransactionId>2137711057</ipgapi:IpgTransactionId>
          <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
          <ipgapi:TDate>1537478017</ipgapi:TDate>
          <ipgapi:TDateFormatted>2018.09.20 21:13:37</ipgapi:TDateFormatted>
          <ipgapi:TransactionResult>FAILED</ipgapi:TransactionResult>
          <ipgapi:TransactionTime>1537478017</ipgapi:TransactionTime>
        </ipgapi:IPGApiOrderResponse>
      </detail>
    </SOAP-ENV:Fault>
  </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.

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