I'm experiencing issues with my Simple Order API. How can I resolve these issues?


 

Answer

Below are the general steps for setting up the Simple Order API:

  1. Download client package that is most suited for your business requirements from the Matrix Page - http://www.cybersource.com/support_center/implementation/downloads/simple_order/matrix.html
    • Also, download the Read Me file and the documentation accompanying the API client package.
  2. Ensure your system meets the prerequisites
  3. Unpackage the .zip and run the install script or wizard
  4. Follow installation / setup procedure in client documentation (found directly below client download). Note: Installation / setup procedure varies greatly from client to client
  5. Generate your security key in the EBC
  6. Modify your properties file
  7. Specify the CyberSource merchant id (required); Note: this is not the banking mid and should be the same as the p12 key file name without the p12 extension
  8. Specify the keys directory (required); Note: this is where you placed your .p12 key
  9. Update the Target API Version (optional)
  10. Enable logging (only enable if troubleshooting an issue, or if you're curious)
  11. Run the prebuilt sample transaction. Note: this process varies greatly from client to client
  12. Verify your transaction shows in the EBC
  13. If the sample code works correctly, customize the sample code to suit your business environment.
  14. After customizing the code, run tests using the modified code to ensure it meets your requirements.
  15. By default, you will be in the test mode when you initially configure your settings. When you are ready to process orders from your customers, you need to manually change the value of sendtoproduction to either "true" or "1", depending on your API client. To determine what the correct value for sendtoproduction is, please refer to the documentation for your API.
  16. After going live, submit a few test orders to ensure that you are able to process orders from your customers.

For more information, go to the developer's guide for your API client by clicking on the following link:
http://www.cybersource.com/support_center/implementation/downloads/simple_order/matrix.html

 

For the general Simple Order API documentation (which includes all the field names to use in your requests), click on the following link:

http://apps.cybersource.com/library/documentation/dev_guides/CC_Svcs_SO_API/html -or-

http://apps.cybersource.com/library/documentation/dev_guides/CC_Svcs_SO_API/Credit_Cards_SO_API.pdf 
 

Below are some of the commonly reported errors with the API, along with a description of the issue and resolution:

1862 IO Error/Failed to sign the document (0x746):
    This error indicates that something in the API's configuration file is incorrect. To resolve this issue, please double-check and correct the following: 

  1. Is the merchant ID entered correctly? Please note that it is case-sensitive and should be in all lowercase. If your merchant ID is v1234567 but you entered V1234567, an error will occur.
  2. Is your p12 security key properly configured? Check the following:
    • The keys directory should be specified in the configuration file and the keys directory should exist.
    • The p12 key is actually in the keys directory.
    • The p12 key filename is the same as the CyberSource merchant ID (if your merchant id is v1234567 then the p12 key filename should be v1234567.p12).
    • For Linux users: The p12 key and all the directories leading to that key should have read and executable permissions.
    • If there are multiple configuration files on the server. Make sure the API is using the correct configuration file.

Error while reading reply from ICS. ICS received request, but we can't read the reply from ICS. HTTP response: 503 Service unavailable.

The 503 error is being generated by your server. If your website is hosted by another company, it's possible they're doing some maintenance on their server. We suggest waiting until the server is up and running for the error to go away. If you still encounter this error after a few hours, we suggest speaking with your hosting company or your server administrator (if it's an in-house server).

The type initializer for CyberSource.WSSecurity.Signature threw an exception.

Security and signature errors typically deal with the dll (Windows; Dynamic Linked Library) or so (Linux: Shared Object) files. The issue is usually that the files are not registered on the computer. The easiest solution for this is to be sure to run the installer for the API, rather than just copying files from one system to another. Also, make sure to uninstall old versions of the API before installing new versions or you may end up with dlls/so file mismatches.

For Windows you can register the dlls through the command prompt.  To register them, open the command prompt and go to the directory where the binaries are located on the destination machine and type:

  • regsvr32 CybsWSSecurity.dll
  • regsvr32 CyberSourceWS.dll

Note: Our APIs require root access, which aren't given on shared environments. If you're on a shared environment, you may consider using a different connection method like Secure Acceptance - Web/Mobile or Secure Acceptance - Simple Order Post (SOP).

Java Simple Order (Handshake Exception):
com.cybersource.ws.client.ClientException: FATAL Alert:HANDSHAKE_FAILURE - The handshake handler was unable to negotiate an acceptable set of security parameters. at com.cybersource.ws.client.Connection.checkForFault(Connection.java:166)

Make sure to import the Root CA Certificate. You might also try redownloading our public ssl certificate: You can obtain the production copy by going to https://ics2ws.ic3.com/commerce/1.x/transactionProcessor/ and exporting the certificate to a file.

Firefox

  • Right-click on the page
  • "View Page Info"
  • "Security"
  • "View Certificate"
  • "Details
  • Select certificate
  • "Export..."


Internet Explorer

  • Right-click on the page
  • "Properties"
  • "Certificates"
  • "Certification Path"
  • Select certificate
  • "View Certificate"
  • "Details"
  • "Copy to File..." > follow the wizard prompts
     

In certain versions of java, SSL certificates need to have a carriage return at the end of the certificate or an error gets thrown:

"input not an x.509 certificate"; java.io.filenotfoundexception

SSL certificates are text-based. If you save the file as a binary file (or upload to your server as a binary file) you will get errors. An example error would be:

keytool error: java.security.cert.certificate parsing exception:java.io.ioexception:subject key, java.security.spec.invalid key spec exception:unknown key spec; using 1.6.0_16
 

PHP session_start() function not working:

New version of PHP install themselves into "C:\Program Files\..." instead of "C:\PHP". Some times, the "Program Files" directory is hidden which may cause an issue when using the PHP Store Sample which uses a session variable. The store sample will show PHP warnings and errors that the session_start() function was not able to run due to permission issues and will cause the sample to fail. To fix this, create a new directory that the API can access like "C:\PHP\Session" and change the variable "session.save_path" in the php.ini file (in the PHP installation directory) to the newly created session directory.