API Guide – Deprecated
Notice of Deprecation
The following API was deprecated late September 2010. While it will continue to be supported it will not be updated or enhanced. The main changes between this API and the new one are:
- HMAC is now used to sign requests.
- Each request requires a unique RequestID.
- Payment reference field may contain values previously supplied or may be absent.
- Request result query added.
- Payments query service.
- Payment Events query service added.
- Payment status query removed.
Preliminary documentation of the new API is here.
Requirements
When you are setup for RAVEN real-time processing you will be provided with a PaymentRoutingNumber per merchant name, a username, a password and a shared secret. The password is used to log onto RAVEN Online and the shared secret is used when submitting payments. Do not divulge this information to unauthorized parties.
To use the RAVEN real-time system your server must meet certain requirements:
- Sales Application: You will need to supply the software that gathers payment information and submits it to RAVEN. The RAVEN system does not include a hosted form, shopping cart, secure web server or any other sales applications.
- Application integration expertise: A small amount of programming will be needed to integrate your application with RAVEN.
- Accurate system clock: The system clock of the server that submits payments must be accurate to within 15 minutes. This can be easily accomplished by using a time server such as the one operated by the US government at: time.nist.gov.
Getting Started
1) Contact Client Support and arrange for the following:
- User name
- Security Token for RAVEN Online
- Shared secret for the transaction gateway
- RAVEN Online URL
- A Payment Routing Number (PRN)
- A test channel in the correct currency
2) Download the SDK from here. This contains helper libraries in Java, PHP and C# that simplify interacting with the API.
3) Use the Connectivity Test to verify that you can connect to the RAVEN Transaction Gateway. Enter the username you were given and click on “Test UserName”. If the test is successful your username is setup and you are able to communicate with the RAVEN server.
4) Go to the RAVEN Online URL provided and confirm your username and security token are setup correctly. Instructions for logging onto RAVEN Online are provided in the RAVEN Online section.
5) If you will be using the Java library, verify that the Sun Java Runtime Edition 1.4 or better is installed on your computer.
6) Run the command file scriptshello.bat (on Mac OS or Unix/Linux use scripts/hello.sh) with the username and pass-phrase obtained in step one from Client Support. If it is successful it will display a greeting from Toronto as follows: Hello from Raven. It is now <current time> GMT. If it is unsuccessful, verify that you have entered the correct username and pass-phrase. If it is still unsuccessful, contact Client Support.
7) Now run the command file scripts/test.bat (or scripts/test.bash), supplying your username, passphrase, the payment routing number obtained from Client Support and a payment reference number of your own choosing. This will create a payment, verify that it was correctly received, and then void it.
8) Log onto RAVEN online, go to the Card section and search for batches. You should be able to view the batch created in the previous step. You should also be able to open this batch and view the associated payment. If you ran the command file more than once, you should see several payments.
9) Use RAVEN Online to close your daily file. If you run test_sample.bat again, a new batch containing a new payment will be created.
10) Use RAVEN Online to void all batches you have created.
This completes the basic setup. The next steps are for you to integrate your server or application, test this integration, and when you are ready, request that your merchant channel be taken out of test mode.
Language Options
The SDK file provides access to helper files that make it easier to submit payments to RAVEN. There are libraries for Java, C# and PHP. It is also simple to perform an HTTP POST using whatever HTTP library your environment provides.
Java Library
The Java library is located in the java directory of the SDK. It contains the following:
- build.xml An ant script to build the RAVEN library and command line tool.
- bin/ Jar files containing the RAVEN library in compiled form
- lib/ Libraries by RAVEN. These are the original distributions, in source and binary form. The jar files actually used by RAVEN are located in bin.
- src/ The source code to the RAVEN library
The Java library consists primarily of two classes: RavenRequest and RavenResponse. There is also a client of these classes, RavenRealtimeMain, which provides a command-line interface to the library. The RAVEN library makes use of several external libraries. These are part of the Apache Commons project, and the HTTP protocol implementation for communicating with the RAVEN server. See the Apache Commons website for more information. The following is a bit of sample code that illustrates creating and populating a request:
//Construct a new request supplying the site and operation name.
RavenRequest request = new RavenRequest("https://demo.{domain}.com/realtime", "submit");
//set request meta data
request.set("UserName", "pacnet-test");
request.set("SharedSecret", "all good men die young");
request.set("Reference", "ord1234");
//set request payment data
request.set("PRN", "840033");
request.set("PymtType", "cc_debit");
request.set("CardNumber", "4000000000000010");
request.set("Expiry", "0933");
request.set("CVV2", "");
request.set("Amount", "100");
request.set("Currency", "CAD");
// Transmit the request
RavenResponse response = request.send();
//Print out the response from the Raven server.
System.out.println("Operation=submit");
System.out.println("HTTPStatus="+response.get("HTTPStatus"));
System.out.println("Status="+response.get("Status"));
System.out.println("ApprovalCode="+response.get("ApprovalCode"));
System.out.println("CVV2ResponseCode="+response.get("CVV2ResponseCode"));
System.out.println("TrackingNumber="+response.get("TrackingNumber"));
C# Library
Open the solution file in Visual Studio 2005. There are 2 projects:
RavenAPI
- Raven.cs is an abstract superclass for RavenRequest and RavenResponse
- RavenRequest.cs represents a request sent to the RAVEN API.
- RavenResponse.cs represents a response from the RAVEN API.
- AssemblySettings.cs is the class to read config file into the project.
- RavenHelper.cs contains the logic to log and create signature and other helper functions.
- RavenConstants.cs contains all the constant string variables and validation logic.
- RavenException and RavenInquireException are the custom exceptions for this project.
RavenLocalTest
This presents a web interface for testing the API, with some custom user inputs and output controls. Clicking on the FullTest button will take the values from the Textboxes and then use RavenRequest. Send method to process it and then print out the responses. Static test uses the static method RavenRequest. SendPaymentRequest to process the request.
The config file must be named using the assembly name plus .config. For example, in this case RavenAPI.dll.config is the config file for this API. Here’s a code snippet that creates a request and fills in its data:
///Construct the request
RavenRequest request = new RavenRequest(RavenConstants.OP_SUBMIT);
request.Set(RavenConstants.CardNumber, "4000000000000010");
request.Set(RavenConstants.PymtType, "cc_debit");
request.Set(RavenConstants.CVV2, "");
request.Set(RavenConstants.Expiry, "0933");
request.Set(RavenConstants.Currency, "CAD");
request.Set(RavenConstants.Amount, "100");
request.Set(RavenConstants.Reference, "ord1234
///Submitting the request to the Raven Transaction Gateway:
response = ravenRequest.Send();
///Retrieving and logging the response data:
RavenHelper.PrintOut(ravenResponse.GetValue(RavenConstants.Status));
RavenHelper.PrintOut(ravenResponse.GetValue(RavenConstants.TrackingNumber));
RavenHelper.PrintOut(ravenResponse.GetValue(RavenConstants.HttpStatus));
RavenHelper.PrintOut(ravenResponse.GetValue(RavenConstants.ApprovalCode));
RavenHelper.PrintOut(ravenResponse.GetValue(RavenConstants.CVV2ResponseCode));
RavenHelper.PrintOut(ravenResponse.GetValue(RavenConstants.Message));
RavenHelper.PrintOut(ravenResponse.GetValue(RavenConstants.ErrorCode));
PHP Library
The PHP library is located in the PHP directory and contains the following:
- Raven.php This script contains the classes that make up the Raven PHP library.
- config.php This contains some constant definitions needed by the classes in Raven.php. It uses default values suitable for testing; these should be changed for deployment. This file is included from Raven.php, so there’s no need to include it directly in PHP scripts that use the RAVEN classes. This file should be located in the same directory as Raven.php.
- test.php This script submits a test payment to RAVEN. It’s meant to be run from the command line using the PHP CLI interpreter.
- docs/ Documentation generated from comments in the source code.
Like the Java and .Net libraries, the RAVEN PHP library supplies two classes, RavenRequest and RavenResponse, that make it easy to communicate with the RAVEN gateway server. The plug-in can be used two ways, by a simple singleton method, or by building and executing a RAVEN request object. The singleton method is the simplest but only works for making basic payments. Here’s an example:
$response = RavenRequest::sendPaymentRequest($cardNumber, $expiryDate, $amount, $cvv2, $reference, $cardHoldersName);
The second method, which allows for any RAVEN operation is performed by building a RAVEN request with all necessary information, and then sending the request:
$request = new RavenRequest('submit');
$request->set('CardNumber', '4000000000000010');
$request->set('PymtType', 'cc_debit');
$request->set('Expiry', '0933');
$request->set('CVV2', '');
$request->set('Currency', 'CAD');
$request->set('Amount', '100');
$request->set('Reference', 'ord1234');
$response = $request->send();
Both types will return a RAVEN request object, throw an Exception (missing information), or throw an Inquire Exception, which must be handled. An Inquire Exception will be thrown in the rare instance where a response could not be received from RAVEN, or RAVEN was not yet able to process the request.
Once a RAVEN request object is returned, it can be used to obtain the operation status and any possible errors. An example of Results:
echo "Operation was a success: ".$response->isSuccess()."<br />
";
echo "Status: ".$response->get('Status')."<br />
";
echo "HTTPStatus: ".$response->get('httpStatus')."<br />
";
echo "ApprovalCode: ".$response->get('ApprovalCode')."<br />
";
echo "CVV2ReponseCode: ".$response->get('CVV2ResponseCode')."<br />
";
echo "Raven Message: ".$response->get('Message')."<br />
";
echo "Error Code: ".$response->get('ErrorCode')."<br />
";
Raw HTTP
It is possible to interact with the RAVEN server using raw HTTP commands. This approach gives you complete flexibility but requires a bit more programming on your part. The process is as follows:
- Formatting a request: Your client application or web server validates the payment information received from your customers and properly formats the HTML FORM data that will be POSTed to RAVEN.
- Signing a request: The information POSTed to RAVEN must include a digital signature.
- Sending a request: The payment information and signature is submitted to RAVEN through your application. This is done over the Internet using HTTPS.
- Processing a response: RAVEN will respond with the result of your request. Your application or server must then process this response appropriately.
- Recovering from any errors or missing responses: If you receive an error response or do not receive a response at all you need to inquire with RAVEN to determine if the payment was processed.
RAVEN real-time requests consist of URL encoded form data. Form data consists of key value pairs. The keys to use in the request are the field names specified in the tables describing the control and payment type specific fields. Recasting our example as form data results in:
UserName=ernest
Timestamp= 2006-01-17T15:26:30.Z
Signature=C9885A4F6CEC8D08281E5EDB5946C12A089CD5C8
PRN=840033
PymtType=cc_debit
Amount=100
Currency=CAD
CardNumber=4000000000000010
Expiry=0933
CVV2=363
Reference=ord1234
The signature field has special processing requirements – see Signatures
Once the correct form data has been gathered, it needs to be posted to a URL of the form https://raven.{domain}.com/realtime/[type]. The last component of the URL path is used to indicate the type of request you are making. The form data must be encoded in the body of an HTTP request as specified by The HTML Standard and by RFC2388. Note that the information may not be encoded into the query string.
A proper POST using the above signed example:
POST /realtime/submit HTTP/1.1
Host: localhost:8008
Content-type: application/x-www-form-urlencoded
Connection: Keep-Alive
CVV2=363&UserName=ernest&Expiry=0933&Timestamp=2006%2D01%2D17T15%3A26%3A30Z
&Signature=C9885A4F6CEC8D08281E5EDB5946C12A089CD5C8&CardNumber=4000000000000010&Currency=CAD
&Reference=ord123&Amount=100&PRN=840033&PymtType=cc_debit
This is a standard HTTP POST header followed by the URL encoded information from the previous snippet.
Responses will be returned to you as form data encoded in the same way as the post. The response will include result fields as well as the values supplied in the request. The only exception to this is that key account data will be masked. Assuming a successful approval, a typical response to the preceding request might be:
HTTP/1.0 200
Content-type: text/html;charset=iso-8859-1
Cachecontrol: Private
Cachecontrol: no-cache
Expires: -1
Pragma: no-cache
Date: Tue, 17 Jan 2006 14:45:18 -0800
Server: VisualWave TinyHTTP/1.0
Mime-version: 1.0
Set-cookie: VW-WTK-sessionkey=18147133149619183314990718540
responseFormat=queryString&Timestamp=2006%2D01%2D17T15%3A26%3A30Z&Signature=47D15B269A8A4C59371FD3E6980419D699B3C3C1
&UserName=ernest&CVV2=&Reference=ord123&PRN=840033&Currency=CAD
&CardNumber=4***********0010&Amount=100&PymtType=cc_debit&Expiry=0933&Status=TestSucceeded
&TrackingNumber=993191337&ApprovalCode=091334&PaymentFileName=ernest%2DRT2006%2D01%2D17
Again the response is URL encoded. Decoding this same information as key value pair results in:
UserName=ernest@somecorp.us
Timestamp=2006-01-17T14:22:27Z
Signature= 47D15B269A8A4C59371FD3E6980419D699B3C3C1
PRN=840033
PymtType=cc_debit
Amount=100
Currency=CAD
CardNumber=4***********0010
Expiry=0933
CVV2=363
Reference=ord123
Status=Approved
TrackingNumber=993191337
ApprovalCode=091334
Filename=ernest-RT2006-01-17
Note the additional elements: Status, TrackingNumber, ApprovalCode and Filename. Also note that the signature has changed. RAVEN will sign the response using two elements: UserName, Timestamp. If you wish to confirm that the response is from RAVEN, you can reconstruct the corresponding signature and compare it to the one sent back by RAVEN.
Services
The following list contains the services you can access with the API.
Hello
URL: https://raven.{domain}.com/realtime/hello
This request will simply elicit a hello response from RAVEN. No processing will take place. It is useful for debugging communications, time stamps and signatures. If the request is made without the timestamp or signature, it tests communications and username. Adding the timestamp will test that your server time is within 15 minutes of UCT. Adding the signature tests that your server has the correct passphrase and is calculating the signature correctly.
The column ‘Req/Rsp’ indicates if the field forms part of the request to RAVEN (Req)or part of the response from RAVEN (Rsp). Except as noted, RAVEN will echo all request fields in the response. The column O/C/M indicates if a field is optional, conditional or mandatory.
| Field Names | Type | Max. Size | Req/Rsp | O/C/M | Remarks |
|---|---|---|---|---|---|
| UserName | AN | 50 | Req | M | UserName as assigned. |
| Timestamp | Timestamp | 50 | Req | C | Time at which the message was sent. Will be validated against UCT time if present. Must be present if a signature is provided. |
| Signature | N | 40 | Req | O | Based on the request values: UserName and Timestamp. Will be validated if present. See Signatures. |
| Response | AN | 200 | Rsp | M | Response will be: “Hello from Raven. <current date & time> GMT.” |
Submit Payment
URL: https://raven.{domain}.com/realtime/submit
This request type is used to submit a payment request to RAVEN.
The column ‘Req/Rsp’ indicates if the field forms part of the request to RAVEN (Req)or part of the response from RAVEN (Rsp). Except as noted, RAVEN will echo all request fields in the response. The column O/C/M indicates if a field is optional, conditional or mandatory.
| Field Names | Type | Max. Size | Req /Rsp | O/C/M | Remarks |
|---|---|---|---|---|---|
| UserName | AN | 50 | Req | M | UserName as assigned. |
| Timestamp | TS | 50 | Req | M | Time at which the message was sent. |
| Signature | N | 40 | Req | M | Based on the request values UserName, Timestamp, Amount, CurrencyCode and Reference. See Signatures. |
| Filename | AN | 150 | Req | M | Name of the file that will receive the payment. If the filename is not supplied RAVEN will use a default filename which will take the form <short username>-RT<yyyy-mm-dd> (e.g. jsmith-RT2006-03-29). “Short username” is normally the same as Username. If Username is an email address, only the first element of the address is used (e.g. for ernest@somecorp.us, ernest would be used). If the file doesn’t exist it will automatically be created. |
| Request and Response Fields | The above fields are required for the mechanics of the request. In addition, the fields specific to the payment type being submitted need to be supplied. For example, in the case of the simplest possible card payment you would also need to include: PRN, PymtType, Amount, CardNumber and Expiry. The response would include the Approval and TrackingNumber. See Introduction to Payments, and the sections dealing with payment types (Card Payments, ChequeIssuePayments, etc). for more details. | ||||
Payment Status
URL: https://raven.{domain}.com/realtime/status
The internet is not 100% reliable. Requests you make may not be received by RAVEN and you may not receive the responses RAVEN sends. When a communication failure occurs you may not know if a payment has been accepted by RAVEN. Using a status request will allow you to determine if you need to resend a payment request or if the original request was accepted and what its status is.
In addition to the fields shown in the table above, the status response will also include a number of additional fields that give the details of the indicated payment. Exactly which fields will be present is determined by the payment type.
Any combination of the parameters Filename, Reference or TrackingNumber may be provided in the request. A search by a submitter using a TrackingNumber will always result in a single match. If a submitter provides a unique Reference for each payment they submit then a status request using just the Reference will also always result in a single match. If a submitter re-uses references from file to file then both the Filename and Reference must be supplied in order to uniquely identify a payment.
If no payment is found matching the supplied search parameters or if multiple payments are found, an HTTP response with HTTP Status Code 404 Not Found will be returned. The body of the response will indicate multiple payments matched the supplied parameters, or if no payment was found.
The column ‘Req/Rsp’ indicates if the field forms part of the request to RAVEN (Req)or part of the response from RAVEN (Rsp). Except as noted, RAVEN will echo all request fields in the response. The column O/C/M indicates if a field is optional, conditional or mandatory.
| Field Names | Type | Max. Size | Req /Rsp | O/C/M | Remarks |
|---|---|---|---|---|---|
| UserName | AN | 50 | Req | M | UserName as assigned. |
| Timestamp | Timestamp | 50 | Req | M | Time at which the message was sent. |
| Signature | N | 40 | Req | M | Based on request values UserName and Timestamp. |
| Filename | AN | 150 | Req | O | Name of the file the payment was submitted to. |
| Reference | AN | 50 | Req | O | The reference provided when the payment was submitted. |
| TrackingNumber | N | 9 | Req | O | Tracking number of the payment. |
Void Payment
URL: https://raven.{domain}.com/realtime/void
From time to time you may send a payment in error. Provided the payment has not yet been submitted for further processing it is possible to void the payment by using a void request.
The column ‘Req/Rsp’ indicates if the field forms part of the request to RAVEN (Req)or part of the response from RAVEN (Rsp). Except as noted, RAVEN will echo all request fields in the response. The column O/C/M indicates if a field is optional, conditional or mandatory.
| Field Names | Type | Max. Size | Req /Rsp | O/C/M | Remarks |
|---|---|---|---|---|---|
| UserName | AN | 50 | Req | M | UserName as assigned. |
| Timestamp | Timestamp | 50 | Req | M | Time at which the message was sent. |
| Signature | N | 40 | Req | M | Based on request values: UserName, Timestamp and TrackingNumber |
| TrackingNumber | N | 9 | Req | O | As returned by a payment or inquiry request. If no payment is found this field will be empty in the response. |
Release File
URL: https://raven.{domain}.com/realtime/closefile
If your service configuration does not include “auto-release”, then you must manually release your files for settlement at the end of your processing day. This can be done via the RAVEN Online web site or it can be automated using the release file request.
The column ‘Req/Rsp’ indicates if the field forms part of the request to RAVEN (Req)or part of the response from RAVEN (Rsp). Except as noted, RAVEN will echo all request fields in the response. The column O/C/M indicates if a field is optional, conditional or mandatory.
| Field Names | Type | Max. Size | Req /Rsp | O/C/M | Remarks |
|---|---|---|---|---|---|
| UserName | AN | 50 | Req | M | UserName as assigned. |
| Timestamp | Timestamp | 50 | Req | M | Time at which the message was sent. |
| Signature | N | 40 | Req | M | Based on request values: UserName Timestamp and Filename |
| Filename | AN | 150 | Req | M | The name of the file to release. The file must not yet be released. If an unreleased file with this name does not exist, an HTTP Status code 400 will result. |
| FileStatus | One Of | 15 | Rsp | M | Status of the file after the operation. One of the file status codes:
|
Void File
URL: https://raven.{domain}.com/realtime/voidfile
If you are not set up for auto-release, you must manually release a file for processing or you can choose to void it.
The column ‘Req/Rsp’ indicates if the field forms part of the request to RAVEN (Req)or part of the response from RAVEN (Rsp). Except as noted, RAVEN will echo all request fields in the response. The column O/C/M indicates if a field is optional, conditional or mandatory.
| Field Names | Type | Max. Size | Req /Rsp | O/C/M | Remarks |
|---|---|---|---|---|---|
| UserName | AN | 50 | Req | M | UserName as assigned. |
| Timestamp | Timestamp | 50 | Req | M | Time at which the message was sent. |
| Signature | N | 40 | Req | M | Based on request values: UserName, Timestamp and Filename |
| Filename | AN | 150 | Req | M | The name of the file to be released. The file must not yet be released. If an unreleased file with this name does not exist, an HTTP Status code 400 will result. |
| FileStatus | One Of | 15 | Rsp | M | Status of the file after the operation. One of the file status codes.
|
Signatures
In order for RAVEN to ensure a payment request has been authorized, you must include a digital signature. The digital signature is a MD5 or SHA-1 hash of your user name, a timestamp and a few values from the payment. Note that signatures are calculated automatically by the RAVEN libraries. You only need to use the procedure below when making HTTP requests directly.
We’ll use the Payment request data below as an example:
UserName=ernest
Timestamp= 2006-01-17T15:26:30.Z
PRN=840033
PymtType=cc_debit
Amount=100
Currency=CAD
CardNumber=4000000000000010
Expiry=0933
CVV2=363
Reference=ord123
Given the preceding request, the Signature field is constructed (hashing with either algorithm) in the following way:
1. Create a string of comma separated values using the elements: UserName, Timestamp, Amount, CurrencyCode and Reference.
ernest,2006-01-17T15:26:30Z,100,CAD,ord123
2. Calculate the hash of this string and create a new comma separated string with this hash and your shared secret. Note: any letters in the hash MUST be upper case.
3417C54DF29B978D4E3C91590316BEB52DCC58A7,all good men die young
3. Calculate the hash of this second string. Again any letters in the hash must be in upper case. This is the signature of the payment.
BA45E29DEB54F8E7FDF25D5B28D506DFEE7D5D70
Now we can complete the above request, adding the completed signature:
UserName=ernest
Timestamp=2006-01-17T14:22:27Z
Signature=BA45E29DEB54F8E7FDF25D5B28D506DFEE7D5D70
PRN=840033
PymtType=cc_debit
Amount=100
Currency=CAD
CardNumber=4000000000000010
Expiry=0933
CVV2=363
Reference=ord123
HTTP Status Codes
HTTP status code responses are described in the table below. Note that in the case of HTTP status 200, the response will contain key value data as documented in the section ‘Response Fields’. In all other cases the body will be HTML. The HTML will describe the error situation.
| HTTP Code Name | Remarks |
|---|---|
| Timeout | Unknown failure, the request may or may not have been processed. Use the appropriate inquiry request to determine the status. |
| 200 OK | There was successful interaction with the server. In this case the body of the HTTP response will be URL encoded field-value pairs as documented. |
| 400 Invalid Request | The request does not match this specification. The request will not have been processed. Check the fields and their content and try again. |
| 401 Authentication Failed | Username is unknown, the shared secret is invalid or the user is not authorized to perform the request. The request will not have been processed. Obtain the correct username and shared secret, ensure the user has the correct authorization and try again. This response may also be due to calculating the signature incorrectly, after checking the user’s authorization and pass phrase check to ensure the signature is being calculated correctly. See Signatures for more detail. |
| 403 Request Denied | The server has denied the request for a reason it will not or cannot provide. This may be caused by an incorrect URL. |
| 412 Invalid Timestamp | The timestamp provided is not in the correct format or is outside of the 15 minute parameter. |
| 500 Server Error | Server has experienced an unexpected error. The request may or may not have been processed. Use the appropriate inquiry request to determine the status of the request. |
| 503 Bank Gateway Failure | Server’s connection to the authorizing bank infrastructure has failed. The request will not have been processed. |