API Guide

This is version 2 of the Raven API. Documentation of the prior API is here.

Prerequisites

To access the RAVEN real-time system you must have credentials to either the demonstration system or the production system as described here. 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: www.time.gov.
Credentials to access to either a test channel in the production system or to access the shared RAVEN test system.

Using the Raven API

The Raven API is a HTTP Post API. Each interaction involves the same 5 steps:

Constructing 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 missing responses: If due to a network error, client error or server error you do not receive a response from RAVEN you need to inquire with RAVEN to determine if the payment was processed.

Constructing a Request

Your client application or web server validates the payment information received from your customers and assembles the HTML FORM data that will be POSTed to RAVEN. 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. As a working example we will use the submit call to post a $1.00 CAD debit against the card 4000000000000010. A Raven API consists of two groups of fields. The first group of fields is required by every API call and is used to support authorization and authentication:
UserName=ernest Timestamp=2006-01-17T15:26:30.Z RequestID=asdf9090asdlasdfaslds Signature=5f9c35fc17b1b05ab03dc7351c0b155968640a4b
In addition each API call has its own specific set of fields. The fields needed to submit a simple card payment are:
PRN=840033 PymtType=cc_debit Amount=100 Currency=CAD CardNumber=4000000000000010 Expiry=0933
With the exception of the Signature these fields are straight forward and are described with each API call. The signature is described in the following section.

Signing a Request

Each request to the API must be signed. The Raven API uses a HMAC message hash as defined in RFC2104 for signing. The HMAC hash should be supplied as lowercase hexadecimal digits (hexits). Functions to calculate HMAC are widely available and typically take three parameters:

A shared secret – this is the shared secret associated with your username.
The data to be hashed – selected fields from the API call concatenated together into one string. The fields to use are described with each API call.
What hash algorithm to use – RAVEN prefers SHA1

In the case of a submit request the fields used in the HMAC are UserName, Timestamp, RequestID, PaymentType, Amount and Currency. For example, assuming the shared secret is ‘shazam’ the HMAC can be calculated in PHP as follows:
hash_hmac('sha1','ernest2006-01-17T15:26:30.Zasdf9090asdlasdfasldscc_debit100CAD','shazam')

Sending a Request

RAVEN API 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. Once a request complete with signature has been constructed, it needs to be posted to the API. Using the example above, we have the following request:
UserName=ernest Timestamp=2006-01-17T15:26:30.Z RequestID=asdf9090asdlasdfaslds Signature=5f9c35fc17b1b05ab03dc7351c0b155968640a4b PymtType=cc_debit Amount=100 Currency=CAD PRN=840033 CardNumber=4000000000000010 Expiry=0933
This will be posted to a URL of the form https://raven.{domain}.com/realtime/<service>. 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 (carriage returns added for formatting)::
POST /realtime/submit HTTP/1.1 Host: localhost:8008 Content-type: application/x-www-form-urlencoded Connection: Keep-Alive
UserName=ernest&Timestamp=2006%2D01%2D17T15%3A26%3A30Z &RequestID=asdf9090asdlasdfaslds&Signature=5f9c35fc17b1b05ab03dc7351c0b155968640a4b &PymtType=cc_debit&Amount=100&Currency=CAD&PRN=840033 &Expiry=0933&CardNumber=4000000000000010
This is a standard HTTP POST header followed by the URL encoded information from the previous snippet.

Processing a Response

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. If the response has HTTP status 200 then it was processed normally and the body of the response will contain the results of processing. See this table to determine how to respond to other status codes. Assuming an HTTP status of 200 and a successful approval, a typical response to the preceding request might be (carriage returns added for formatting):
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&UserName=ernest&Timestamp=2006%2D01%2D17T15%3A26%3A30Z &RequestID=asdf9090asdlasdfaslds&Signature=ad9ca3ef8c04b4082b3b9d5f712ffa8f545df7f6 &PymtType=cc_debit&Currency=CAD&Amount=100&PRN=840033 &CardNumber=4***********0010&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 RequestID=asdf9090asdlasdfaslds Signature= ad9ca3ef8c04b4082b3b9d5f712ffa8f545df7f6 PymtType=cc_debit Amount=100 Currency=CAD PRN=840033 CardNumber=4***********0010 Expiry=0933 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 3 elements: UserName, Timestamp and RequestID. 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.

Recovering from missing responses

If, due to a network error, client error or a server error as indicated by an HTTP status of 500, you do not receive a response from RAVEN you need to inquire with RAVEN to determine if the payment was processed. In response you will either receive the exact response you missed, to be handled appropriately, or a notification that no such request exists in which case you can safely send the request again.

Services

The RAVEN API consists of several services each with its own URL but sharing the same base URL. Services available include:

Hello – to establish that communication exists
Result Request – used to request the result of a previous interaction
Submit Payment – to submit a payment request
Void Payment – to void a previously submitted payment
Release File – if your UserName is not configured to automatically close and send for settlement then you must close each file of payments yourself
Void File – can be used to void an entire batch of processing
Payment Search – can be used to query the current status of payments submitted
Payment Event Search (beta) – can be used to query for payment events such as returns or stop payments

Each service is described in detail below.

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
RAPIVersion	AN	10	Req	M	Must be 2.
UserName	AN	50	Req	M	UserName, as assigned.
Timestamp	Timestamp	50	Req	O	Time at which the message was sent. Will be validated against UCT time if present.
RequestID	AN	50	Req	O	Any value unique for the UserName i.e. a given username may never submit the same RequestID twice. This can be implemented using a UUI, GUID or even the machine name followed by a microsecond timestamp. If no RequestID is provided one will be assigned.
Signature	N	40	Req	M	SHA1 HMAC of the following values concatenated: UserName
RequestResult	AN	100	Rsp	M	Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.
Response	AN	200	Rsp	M	Response will be: “Hello from Raven. <current date & time> GMT.”

Request Result

URL: https://raven.{domain}.com/realtime/response

The internet is not 100% reliable. Requests you make may not be received by RAVEN, you may not receive the responses RAVEN sends or RAVEN may send a server 500 error. In any case, you will not know if a request has been processed by RAVEN. Using a result request will give you the response you missed. If no request with the supplied RequestID is found, the response will echo the values supplied and include a status with the value Invalid:NoSuchRequestID. In this case you can be confident the original request was not processed.

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
RAPIVersion	AN	10	Req	M	Must be 2.
UserName	AN	50	Req	M	UserName as assigned.
Timestamp	Timestamp	50	Req	M	Time at which the message was sent.
RequestID	AN	50	Req	M	Not a new RequestID but rather the RequestID that was used to submit the original payment.
Signature	N	40	Req	M	SHA1 HMAC of the following values concatenated: UserName TimeStamp RequestID
RequestResult	AN	100	Rsp	M	Will be OK in normal cases, other wise will be an error code as described in the table of HTTP status codes below.
Response Fields					If a request with a RequestID matching the one supplied is found, the exact response that was originally sent will be returned again. If no request with the supplied RequestID is found, the response will echo the values supplied and include a status with the value Invalid:NoSuchRequestID. It is not possible to request the result of a result request.

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
RAPIVersion	AN	10	Req	M	Must be 2.
UserName	AN	50	Req	M	UserName as assigned.
Timestamp	TS	50	Req	M	Time at which the message was sent.
RequestID	AN	50	Req	M	Any value unique for the UserName i.e. a given username may never submit the same RequestID twice. This can be implemented using a UUI, GUID or even the machine name followed by a microsecond timestamp.
Signature	N	40	Req	M	SHA1 HMAC of the following values concatenated: UserName TimeStamp RequestID PaymentType Amount Currency
Filename	AN	150	Req	O	Name of the file (batch of payments) that the payment will be put in. 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.
RequestResult	AN	100	Rsp	M	Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.
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

Using a status request will allow you to determine what the current status of a payment is. The response will contain all of the same fields as the original request but include the current status.

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.

Field Names	Type	Max. Size	Req /Rsp	O/C/M	Remarks
RAPIVersion	AN	10	Req	M	Must be 2.
UserName	AN	50	Req	M	UserName as assigned.
Timestamp	Timestamp	50	Req	M	The time that the message was sent.
RequestID	AN	50	Req	M	Any value unique for the UserName i.e. a given username may never submit the same RequestID twice. This can be implemented using a UUI, GUID or even the machine name followed by a microsecond timestamp.
Signature	N	40	Req	M	SHA1 HMAC of the following values concatenated: UserName TimeStamp RequestID
TrackingNumber	N	9	Req	M	As returned by a payment or inquiry request. If no payment is found this field will be empty in the response.
PymtType	AN	25	Req	M	Type of the payment as specified in the original submit request.
RequestResult	AN	100	Rsp	M	Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.

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 using a void request. Please note that the window to void a payment may be very small. For example, if the original request is submitted just prior to the cutoff.

Field Names	Type	Max. Size	Req /Rsp	O/C/M	Remarks
RAPIVersion	AN	10	Req	M	Must be 2.
UserName	AN	50	Req	M	UserName, as assigned.
Timestamp	Timestamp	50	Req	M	The time that the message was sent.
RequestID	AN	50	Req	M	Any value unique for the UserName i.e. a given username may never submit the same RequestID twice. This can be implemented using a UUI, GUID or even the machine name followed by a microsecond timestamp.
Signature	N	40	Req	M	SHA1 HMAC of the following values concatenated: UserName TimeStamp RequestID TrackingNumber
TrackingNumber	N	9	Req	M	As returned by a payment or inquiry request. If no payment is found this field will be empty in the response.
PymtType	AN	25	Req	M	Type of the payment as specified in the original submit request.
RequestResult	AN	100	Rsp	M	Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.

Release File

URL: https://raven.{domain}.com/realtime/closefile

If your service configuration is not set to “auto-release”, then you must manually release your files for settlement at the end of your processing interval. This is typically done on a daily basis, but can also be done more or less frequently. It is not recommended to release your files after each payment, creating one file for each individual payment. This will not speed up processing times and also results in cluttered reports. Whichever release schedule you choose, files must be released before 7 days have elapsed from the time the first payment was added to the file. After 7 days any open file will be voided. File release can be done via the RAVEN Online web site or it can be automated using the release file request.

Field Names	Type	Max. Size	Req /Rsp	O/C/M	Remarks
RAPIVersion	AN	10	Req	M	Must be 2.
UserName	AN	50	Req	M	UserName, as assigned.
Timestamp	Timestamp	50	Req	M	Time at which the message was sent.
RequestID	AN	50	Req	M	Any value unique for the UserName i.e. a given username may never submit the same RequestID twice. This can be implemented using a UUI, GUID or even the machine name followed by a microsecond timestamp.
Signature	N	40	Req	M	SHA1 HMAC of the following values concatenated: UserName TimeStamp RequestID 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.
RequestResult	AN	100	Rsp	M	Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.
FileStatus	One Of	15	Rsp	M	Status of the file after the operation, either: open or released

Void File

URL: https://raven.{domain}.com/realtime/voidfile

If you are not set up for auto-release, or you may void a file, should it be necessary .

Field Names	Type	Max. Size	Req /Rsp	O/C/M	Remarks
RAPIVersion	AN	10	Req	M	Must be 2.
UserName	AN	50	Req	M	UserName, as assigned.
Timestamp	Timestamp	50	Req	M	Time at which the message was sent.
RequestID	AN	50	Req	M	Any value unique for the UserName i.e. a given username may never submit the same RequestID twice. This can be implemented using a UUI, GUID or even the machine name followed by a microsecond timestamp.
Signature	N	40	Req	M	SHA1 HMAC of the following values concatenated: UserName TimeStamp RequestID 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.
RequestResult	AN	100	Rsp	M	Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.
FileStatus	One Of	15	Rsp	M	Status of the file after the operation, either: open or released

Payments

URL: https://raven.{domain}.com/realtime/payments

The service first echoes the query parameters in URL encoded form and then returns a RAVEN result file containing all payments matching the search parameters supplied.

Field Names	Type	Max. Size	Req /Rsp	O/C/M	Remarks
RAPIVersion	AN	10	Req	M	Must be 2.
UserName	AN	50	Req	M	UserName, as assigned. Only events for payments the user has submitter or has submitter manager authority for will be provided, regardless of any other query parameters supplied.
Timestamp	Timestamp	50	Req	M	Time at which the message was sent.
RequestID	AN	50	Req	M	Any value unique for the UserName i.e. a given username may never submit the same RequestID twice. This can be implemented using a UUI, GUID or even the machine name followed by a microsecond timestamp.
Signature	N	40	Req	M	SHA1 HMAC of the following values concatenated: UserName TimeStamp RequestID
ReportFormat	One of	50	Req	M	The following formats are supported: RavenPaymentFile_v1.0
StartTime	Timestamp	50	Req	M	Only payments created after this time will be returned. Payments are only available for 18 months prior to the current date, starting from Aug 15, 2010.
EndTime	Timestamp	50	Req	M	Only payments created before this time will be returned.
ResultFields	AN	500	Req	M	A space separated list of Field names. These fields will be included in the result in the order given. For a list of all possible fields, see the description of each payment type.
Accounts	AN	250	Req	O	A space separated list of RAVEN account numbers.
PaymentRoutingNumbers	AN	250	Req	O	A space separated list of RAVEN payment routing numbers.
PaymentTypes	AN	250	Req	O	A space separated list of RAVEN payment types.
TrackingNumbers	AN	250	Req	O	A space separated list of payment tracking numbers.
RequestResult	AN	100	Rsp	M	Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.
ResultCount	N	25	Rsp	M	Number of records returned.
PaymentReport			Rsp	O	A report in RAVEN result file format of the payments found. This will include those fields specified in ResultFields.

Payment Events (BETA)

URL: https://raven.{domain}.com/realtime/events

The service first echoes the query parameters in URL encoded form and will then return a csv RAVEN report containing all payment events matching the supplied search parameters.

Field Names	Type	Max. Size	Req /Rsp	O/C/M	Remarks
RAPIVersion	AN	10	Req	M	Must be 2.
UserName	AN	50	Req	M	UserName as assigned. Only events for payments the user has submitter or submitter manager authority for will be provided, regardless of any other query parameters supplied.
Timestamp	Timestamp	50	Req	M	Time at which the message was sent.
RequestID	AN	50	Req	M	Any value unique for the UserName i.e. a given username may never submit the same RequestID twice. This can be implemented using a UUI, GUID or even the machine name followed by a microsecond timestamp.
Signature	N	40	Req	M	SHA1 HMAC of the following values concatenated: UserName TimeStamp RequestID
ReportFormat	One of	50	Req	M	The following formats are supported: RavenEventFile_v1.0
StartTime	Timestamp	50	Req	M	Only events recorded after this time will be returned. There are no events available prior to August 15, 2010.
EndTime	Timestamp	50	Req	M	Only events recorded before this time will be returned.
ResultFields	AN	500	Req	M	A space separated list of Field names. These fields will be included in the result in the order given. For a list of all possible fields see each of the payment types.
Accounts	AN	250	Req	O	A space separated list of RAVEN account numbers.
PaymentRoutingNumbers	AN	250	Req	O	A space separated list of RAVEN payment routing numbers.
PaymentTypes	AN	250	Req	O	A space separated list of RAVEN payment types.
PaymentEventTypes	One of	100	Req	O	A space separated list of event types: receipt resolved result cleared returned Clearing events are only available for some payment types, such as UK CHAPS payments.
RequestResult	AN	100	Rsp	M	Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.
ResultCount	N	25	Rsp	M	Number of records returned.
PaymentEventReport			Rsp	O	A report in RAVEN file format of all payment events for the given query parameters. The report will begin on the first line after the query parameters. This will include those fields specified in ResultFields followed by these two fields: EventType EventDate

Request Result and HTTP Status

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 contain a single key value pair RequestResult=<value> where value describes the error situation. Possible values are described in the table below.

HTTP Status	RequestResult	Remarks
timeout		A client side http timeout with no results returned. The request may or may not have been processed and you should use a request result inquiry to retrieve any results.
200	ok	There was successful interaction with the server. In this case the body of the HTTP response will be as documented for each service.
400	duplicateRequestIDinvalidParameters	The request does not match the specification. The request will not have been processed. Check the fields and their content and try again.
401	authenticationFailed	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	submitterNotAuthorized	The server has denied the request because the user is not authorized to perform the action.
404	noSuchItemunableToResolveRequest	Unable to process the request because some resource has not been found.
412	invalidTimestamp	The timestamp provided is not in the correct format or is outside of the 15 minute parameter.
500	serverError	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	bankGatewayUnavailable	Server’s connection to the authorizing bank infrastructure has failed. The request will not have been processed.

Language Options

The following sections demonstrate how to access the RAVEN API from a variety of programming languages. In some cases there are files containing frameworks that make it easier to submit payments to RAVEN.

Please note that these are all simply wrapper APIs to the real RAVEN HTTP Request/Response API, explained in detail above. As such they primarily serve as examples of how you would target RAVEN services from different programming languages and environments. You can target RAVEN services by writing your own API, possibly using the wrappers as templates/guides, you can use the supplied wrapper APIs directly, or you can copy and modify the wrappers to accommodate your specific needs.

PHP Library (developed with PHP 5.3.9)

The linked archive contains three files

src/Raven.php is a small library that makes interacting with the API very easy
src/config.php determines what username, shared secret and url is used
demo/pymt_lifecycle_demo.php provides some examples of interacting with the API base services (non-reporting) using the library
demo/pymt_reporting_demo.php provides some examples of interacting with the API reporting services using the library
demo/prog_magic_card_demo.php provides some examples of interacting with the API base services using the library and magic test cards

As an example, a credit card debit (sale) is as simple as doing the following:

// Include the library require_once('Raven.php');

// Create and populate a request object $pymtReq = new RavenRequest('submit'); $pymtReq->set('PRN', '840033'); $pymtReq->set('Currency', 'USD'); $pymtReq->set('CardNumber', '4000000000000010'); $pymtReq->set('PymtType', 'cc_debit'); $pymtReq->set('ExpiryDate', '0919'); $pymtReq->set('Amount', 2000);

// Submit the request $pymtResp = $pymtReq->send();

Java Library

The linked archive contains the following files

lib/RAPI.jar – is a small library that makes interacting with the API very easy
lib/ravenconfig.xml – determines what username, shared secret and url is used
lib – contains the library jars required by RAPI.jar
src – contains the java source files
test – contains sample JUnit tests and related config files
test/PymtLifecycleDemoCmdLine.java – provides some examples of interacting with the API base services (non-reporting) using the library
test/pymt_lifecycle_demo.bat – provides an example of running PymtLifecycleDemoCmdLine, complete with classpath
test/PymtReportingDemoCmdLine.java – provides some examples of interacting with the API reporting services using the library
test/pymt_reporting_demo.bat- provides an example of running PymtReportingDemoCmdLine, complete with classpath

As an example, a credit card debit (sale) is as simple as doing the following:

Copy RAPI.jar and ravenconfig.xml into your application’s library folder, along with any dependent library JARs that you do not already have (e.g. commons-codec-1.3.jar).
Edit the ravenconfig.xml file to reflect your user name and secret, etc.
Include RAPI.jar and any missing dependent library JARs in your application’s classpath. For example, the following illustrates how the supplied PymtLifecycleDemoCmdLine application would be invoked from a Windows command prompt in the unzipped test directory:

java -cp .;../lib;../lib/commons-codec-1.3.jar;../lib/commons-collections-3.2.1.jar;../lib/commons-configuration-1.6.jar;../lib/commons-httpclient-3.0.jar;../lib/commons-lang-2.5.jar;../lib/commons-logging-api.jar;../lib/commons-logging-api.jar;../lib/RAPI.jar PymtLifecycleDemoCmdLine

// Import the RAVEN API classes into your application import com.deepcovelabs.raven.api;

// Create and populate a request object RavenRequest request = new RavenRequest("submit");

request.set("PRN", "840033"); request.set("Currency", "USD"); request.set("CardNumber", "4000000000000010"); request.set("PymtType", "cc_debit"); request.set("ExpiryDate", "0919"); request.set("Amount", "2000");

// Submit the request RavenResponse response = request.send();

C# .NET Library

The linked archive contains the following files

lib/RAPI.dll – is a small .NET Framework 4 library that makes interacting with the API very easy
lib/ravenconfig.xml - determines what username, shared secret and url is used
demo/RAPIDemo.ps1 - provides a simple example of interacting with the API using the library from a Windows powershell script
src – contains the C# source files
demo – contains the C# demo/test files

As an example, a credit card debit (sale) is as simple as doing the following:

Copy RAPI.dll, RAPI.dll.config and ravenconfig.xml into your application’s library folder.
Edit the ravenconfig.xml file to reflect your user name and secret etc.

// Import the Raven API classes into your application

using Raven.API;

// Create and populate a request object RavenRequest request = new RavenRequest("submit");

// Submit the request RavenResponse response = request.send();

Python Library (beta, developed with Python 2.72)

The linked archive contains three files

src/Raven.py – is a small library that makes interacting with the API very easy
src/Config.py – determines what username, shared secret and url is used
demo/pymt_lifecycle_demo.py – provides some examples of interacting with the API base services (non-reporting) using the library
demo/pymt_reporting_demo.py – provides some examples of interacting with the API reporting services using the library
demo/prog_magic_card_demo.py – provides some examples of interacting with the API base services using the library and magic test cards

As an example, a credit card debit (sale) is as simple as doing the following:

# Include the library import Raven

# Create and populate a request object pymtReq = Raven.RavenRequest('submit') pymtReq.set('PRN', '840033') pymtReq.set('Currency', 'USD') pymtReq.set('CardNumber', '4000000000000010') pymtReq.set('PymtType', 'cc_debit') pymtReq.set('ExpiryDate', '0919') pymtReq.set('Amount', 2000)

# Submit the request pymtResp = pymtReq.send()

Shell Script Examples

There are examples for both the Unix bash shell and the Windows Powershell. There are three calls in each: an unsigned call to the hello service, a signed call to hello and finally a signed card debit. These examples are directed against the RAVEN demo system and should work as written. If you have a card test channel configured and want to direct the examples there you need to change the username ernest to your username, the shared secret all good men die young to your shared secret and the PRN 840033 to your PRN.

If you want to test a payment type other than card debit you will need to change the other parameters appropriately.

These scripts are a simple way to ensure your channel is properly configured. Both examples assume cURL is installed.

Bash Shell Card Debit Example

The linked file contains three example calls. As a demonstration of a card debit you should be able to copy and past the following code example directly into a bash shell and run it.
#!/bin/bash # Tested with OSX 10.6.4, bash 3.2, cURL v7.19.7, OpenSSL v0.9.8 # Tested with Ubuntu 10.04 LTS, bash 4.1-2ubuntu3, cURL v7.19.7, OpenSSL 0.9.8k-7ubuntu8

echo -e "\nDebit Test - Signed" url="https://demo.deepcovelabs.com/realtime/submit" user="ernest" requestid=$(uuidgen) timestamp=$(date -u +"%Y-%m-%dT%H:%M:%S.Z") file="dailyfile" routing="840033" type="cc_debit" amount="100" currency="CAD" card="4000000000000010" expiry="0933" valuestosign=$user$timestamp$requestid$type$amount$currency signature=$(echo -n $valuestosign | openssl dgst -sha1 -hmac "all good men die young") echo $(curl --silent \ --data-urlencode RAPIVersion=2 \ --data-urlencode UserName=$user \ --data-urlencode TimeStamp=$timestamp \ --data-urlencode RequestID=$requestid \ --data-urlencode Signature=$signature \ --data-urlencode Filename=$file \ --data-urlencode PaymentRoutingNumber=$routing \ --data-urlencode PaymentType=$type \ --data-urlencode Amount=$amount \ --data-urlencode CurrencyCode=$currency \ --data-urlencode CardNumber=$card \ --data-urlencode Expiry=$expiry \ $url)

Windows Powershell Example

The linked file contains three example calls. As a demonstration of a card debit you should be able to copy and past the following code example directly into a PowerShell editor and run it.
# PowerShell test script for Raven API Version 2 # 2010-10-04 initial version

function hmacsha1($params, $secret) { $hmacsha = New-Object System.Security.Cryptography.HMACSHA1 $hmacsha.key = [Text.Encoding]::ASCII.GetBytes($secret) $signature = $hmacsha.ComputeHash([System.Text.Encoding]::ASCII.GetBytes($params)) $hex = [string]::join("", ($signature | % {([int]$_).toString('x2')})) return $hex } function post($url, $data) { $wc = New-Object System.Net.WebClient $wc.QueryString = $data $webpage = $wc.UploadValues($url, "POST", $data) $response = [System.Text.Encoding]::ASCII.GetString($webpage) return $response } function signedDebitTest() { $url = "https://demo.deepcovelabs.com/realtime/submit" $user = "ernest" $secret = "all good men die young" $requestid = [guid]::NewGuid() $timestamp = Get-Date -date (Get-Date).ToUniversalTime() -format s $file = "dailyfile" $routing = "840033" $type = "cc_debit" $amount = "100" $currency = "CAD" $card = "4000000000000010" $expiry = "0933" $valuestosign = $user + $timestamp + $requestid + $type + $amount + $currency $signature = hmacsha1 $valuestosign $secret $data = new-object System.Collections.Specialized.NameValueCollection $data.Add("RAPIVersion","2") $data.Add("UserName",$user) $data.Add("TimeStamp",$timestamp) $data.Add("RequestID",$requestid) $data.Add("Signature",$signature) $data.Add("Filename",$file) $data.Add("PaymentRoutingNumber",$routing) $data.Add("PaymentType",$type) $data.Add("Amount",$amount) $data.Add("CurrencyCode",$currency) $data.Add("CardNumber",$card) $data.Add("Expiry",$expiry) $response = post $url $data Write-Host $response }

Write-Host "`nDebit Test - Signed" -foregroundcolor green signedDebitTest Write-Host "`nPress any key to continue ..." $key = $host.UI.RawUI.ReadKey("NoEcho,IncludeKeyDown")

API Guide

Prerequisites

Using the Raven API

Constructing a Request

Signing a Request

Sending a Request

Processing a Response

Recovering from missing responses

Services

Hello

Request Result

Submit Payment

Payment Status

Void Payment

Release File

Void File

Payments

Payment Events (BETA)

Request Result and HTTP Status

Language Options

PHP Library (developed with PHP 5.3.9)

Java Library

C# .NET Library

Python Library (beta, developed with Python 2.72)

Shell Script Examples

Bash Shell Card Debit Example

Windows Powershell Example

Raven Integration