Testing Card ForceTicket
The ForceTicket operation of the Web Services API is used to forcibly capture an amount from a customer who has provided his/her card details and his/her authorisation outside of your online checkout, perhaps over the phone. However the authorisation and card data is collected from the customer, you must also get a six-digit code to include in the ForceTicket.
The steps below will show you how to use the ForceTicket simulator to build a transaction. Our examples here uses a simple cURL request, but the same steps apply to any coding language.
Step 1: Open the ForceTicket simulator
For the purposes of making test ForceTicket transaction, you'll be using the ForceTicket simulator in the Authipay Developer Playground.
To open the simulator interface, login to your Authipay Developer Playground account and click "OPEN" on the "card-forceTicket" 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 ForceTicket 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 ForceTicket 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 ForceTicket transaction, then wrap the XML into the body of a SOAP request.
The XML body of the forceTicket transaction has 3 parts: (1) the CreditCardData block, (2) Payment block, (3) the TransactionDetails block.
- 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)
- The Payment block describes the amount to be reserved on the card ("ChargeTotal") and the currency (currency codes follow the ISO-4217).
- The TransactionDetails block is crucial. It contains the ReferenceNumber which is the 6-digit number that you retained from your offline authorisation and must be included in the request.
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 ForceTicket simulator.
Below is an example SOAP request containing the minimum XML fields needed for a ForceTicket 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>forceTicket</v1:Type>
</v1:CreditCardTxType>
<v1:CreditCardData>
<v1:CardNumber>5316820017498899</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:TransactionDetails>
<v1:ReferenceNumber>001122</v1:ReferenceNumber>
</v1:TransactionDetails>
</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, "forceticket.xml".
Our Tip: include all xmlns
Make sure you include all xmlns attributes (aka XML namespaces) mentioned in this guide. Without these the XML may not be parsed correctly on the server end.
Step 3: Send the request to the ForceTicket 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 ForceTicket transaction using cURL. The "example.xml" contains the constructed SOAP request.
curl -X POST -d @forceticket.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 ForceTicket 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 ForceTicket 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:297719:A9511503854:PPXP:4967</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>VISA</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>AIBMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-UFhnEArlaetHBYbSL9qHlam6Cobc30goEjiUjA==</ipgapi:OrderId>
<ipgapi:IpgTransactionId>9511503854</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>297719</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReferenceNumber>297719</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>AUTH CODE:297719</ipgapi:ProcessorResponseMessage>
<ipgapi:TDate>1537549997</ipgapi:TDate>
<ipgapi:TDateFormatted>2018.09.21 17:13:17</ipgapi:TDateFormatted>
<ipgapi:TerminalID>79111048</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1537549997</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 ForceTicket simulator.
Our Tip: remember the OrderId
Each transaction will get its own OrderId. Your code should store this in persistent storeage. It's an important reference if any future dispute or chargeback arises. You could also store the IpgTransactionId as well; this will help you in any support requests to Authipay.