Testing Card Credit

The Credit operation of the Web Services API is used to forcibly credit an amount back to a given customer's credit/debit card.

Credit transactions are typically difficult to test because their use normally require special permissions. However, the Credit simulator in your Playground changes all that, making it super easy for you to test Credit transactions. Just follow the steps below. All examples here uses a simple cURL request, but the same steps apply to any coding language.

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

Step 1: Open the Credit simulator

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

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

The XML body of the forceTicket transaction has 2 parts: (1) the CreditCardData block, (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 Credit simulator.

Below is an example SOAP request containing the minimum XML fields needed for a Credit 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>credit</v1:Type>
        </v1:CreditCardTxType>
        <v1:CreditCardData>
          <v1:CardNumber>4532682570433353</v1:CardNumber>
          <v1:ExpMonth>05</v1:ExpMonth>
          <v1:ExpYear>21</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, "credit.xml".

Step 3: Send the request to the Credit 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 Credit transaction using cURL. The "example.xml" contains the constructed SOAP request.

curl -X POST -d @credit.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 Credit 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 Credit 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 Credit 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:456864:A1781316290:PPXP:8363</ipgapi:ApprovalCode>
      <ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
      <ipgapi:Brand>VISA</ipgapi:Brand>
      <ipgapi:CommercialServiceProvider>AIBMS</ipgapi:CommercialServiceProvider>
      <ipgapi:OrderId>A-RAGzP1/yVgI50TuCr7qoC4BvWW0tHZNGMZyzwA==</ipgapi:OrderId>
      <ipgapi:IpgTransactionId>1781316290</ipgapi:IpgTransactionId>
      <ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
      <ipgapi:ProcessorApprovalCode>456864</ipgapi:ProcessorApprovalCode>
      <ipgapi:ProcessorReferenceNumber>456864</ipgapi:ProcessorReferenceNumber>
      <ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
      <ipgapi:ProcessorResponseMessage>AUTH CODE:456864</ipgapi:ProcessorResponseMessage>
      <ipgapi:ReferencedTDate>-2062448793</ipgapi:ReferencedTDate>
      <ipgapi:TDate>1537551207</ipgapi:TDate>
      <ipgapi:TDateFormatted>2018.09.21 17:33:27</ipgapi:TDateFormatted>
      <ipgapi:TerminalID>5119778</ipgapi:TerminalID>
      <ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
      <ipgapi:TransactionTime>1537551207</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 Credit simulator.