Troubleshooting Production Issues
Your code is all working and you’re successfully processing payments using the test gateway. You then add a production gateway and try to run a purchase but it doesn’t work. What might the issue be? It turns out this is almost always a credentials issue - a case of not providing the proper authentication parameters to the production gateway. Each gateway requires different credentials and they’re often called different things.
However, beyond speculation, the best way to debug production issues is to look at the communication Spreedly had with the remote party (either a gateway or receiver). Spreedly provides full transparency via the transaction transcript.
Using the transcript
For every Spreedly transaction that involves a remote API call, the details of that remote call are recorded as the transaction transcript. The human-readable, text-based transcript provides low-level insight into the actual details of the remote call including the request headers, body, response status:
curl https://core.spreedly.com/v1/transactions/7DShFlwqVtUvhyackYN2Jtw2UGn/transcript \ -u 'Ll6fAtoVSTyVMlJEmtpoJV8S:RKOCG5D8D3fZxDSg504D0IxU2XD4Io5VXmyzdCtTivHFTTSy'
env = Spreedly::Environment.new('Ll6fAtoVSTyMlJEm', 'RKcG5D8D3fZxDSg504U2XD4Io5VXz') env.find_transcript("7DShFlwqVtUvhyackYN2Jtw2UGn")
The transcript is scrubbed of sensitive information so you can email it to your support representative at your gateway or receiver.
This gives you an opportunity to simply say that “this is what we sent and how you responded - might you help me understand why you responded this way?” The response you get back can help you to know if there’s something else you need to pass to them or if there’s some requirement setting you might need to adjust in your control panel.
For example, you may want to turn off the CVV requirement or turn off the billing address requirement if your gateway defaults to requiring them. Or, if your gateway requires you to whitelist an IP address, you may need to add Spreedly’s IP Address to your gateway UI.
You may be interested to know the meaning of the codes available for CVV and/or AVS responses. These can help determine the reason a transaction was declined and inform your next steps.
CVV Response Codes
|I||Failed data validation check|
|S||Should have been present|
|U||Issuer unable to process request|
|X||Card does not support verification|
AVS Response Codes
|A||Street address matches, but 5-digit and 9-digit postal code do not match.|
|B||Street address matches, but postal code not verified.|
|C||Street address and postal code do not match.|
|D||Street address and postal code match. Code “M” is equivalent.|
|E||AVS data is invalid or AVS is not allowed for this card type.|
|F||Card member’s name does not match, but billing postal code matches.|
|G||Non-U.S. issuing bank does not support AVS.|
|H||Card member’s name does not match. Street address and postal code match.|
|I||Address not verified.|
|J||Card member’s name, billing address, and postal code match.|
|K||Card member’s name matches but billing address and billing postal code do not match.|
|L||Card member’s name and billing postal code match, but billing address does not match.|
|M||Street address and postal code match. Code “D” is equivalent.|
|N||Street address and postal code do not match.|
|O||Card member’s name and billing address match, but billing postal code does not match.|
|P||Postal code matches, but street address not verified.|
|Q||Card member’s name, billing address, and postal code match.|
|S||Bank does not support AVS.|
|T||Card member’s name does not match, but street address matches.|
|U||Address information unavailable. Returned if the U.S. bank does not support non-U.S. AVS or if the AVS in a U.S. bank is not functioning properly.|
|V||Card member’s name, billing address, and billing postal code match.|
|W||Street address does not match, but 9-digit postal code matches.|
|X||Street address and 9-digit postal code match.|
|Y||Street address and 5-digit postal code match.|
|Z||Street address does not match, but 5-digit postal code matches.|
It’s extremely important to us that the Spreedly API is fast. When you make a call to the API, we want to respond as quickly as possible.
The question is, how long should you wait before making the determination in your code that the Spreedly service isn’t operating as it should? Or, to put it another way, how long should you wait to determine that your application is having difficulty talking to the Spreedly service?
Let’s start by focusing on the API calls which are dependent on an external service like a payment gateway. We’re talking here about calls like purchase and authorize. You want to ensure in cases like this that you don’t set your timeout too low because if you do, that timeout could be reached before your gateway has responded. So from your application’s perspective, the transaction failed because it timed out. The reality though is that the transaction succeeded but took longer than expected to do so.
So how long is a reasonable amount of time to wait? We have seen gateways take up to 60 seconds to respond to requests when under heavy load. Therefore, when Spreedly talks to a gateway, we use an internal timeout of 61 seconds. At that point, we stop waiting for the gateway to respond and we mark the transaction as failed because we timed out talking to the gateway. This means that for your code, you’ll want to use a timeout at least a second or two more than that (perhaps 64 seconds) for the API calls which interact with a gateway. If you set your timeout for less than that, it could lead to cases where your customer has successfully paid you but your application thinks the payment has failed.
For the API calls that don’t interact with a gateway like showing a transaction or retaining a payment method, a much shorter timeout is necessary. We recommend a timeout of 5-10 seconds to determine that there’s an issue talking to the Spreedly service.