Skip to Navigation | Skip to Content

Real-time Processing

This section describes how to use the RAVEN API to submit payments one at a time over the Internet. Although it may be used to submit payments of any type, this mechanism is commonly used to process card payments because it provides an immediate response.

RAVEN will accept payments and add them to a file containing all payments submitted for that specific processing day. When you submit a request, RAVEN will process as much of the payment as it can. For example, for credit card payments, RAVEN will immediately request an approval and respond appropriately. Processing that cannot happen immediately, such as the printing of a paper cheque or submission for settlement, will be deferred until after the file has been released. You can choose to have RAVEN automatically release the processing at the end of each day, or you can choose to release files manually.

processing

API Processing Cycle

As illustrated above, the API processing cycle is as follows:

  1. Submitting a request: Your client application or web server validates the payment information received from your customer and submits a request to RAVEN. You can submit a request using our plug-in code or by performing your own HTTP POST.
  2. Processing a response: RAVEN will respond with the result of processing. Your application or server must then process this response appropriately. If no response is received you will need to inquire with RAVEN to determine if RAVEN received your request and to learn the status of the response.
  3. (Optional) Review payments online: If you are not setup for auto-release then at the end of the day you should review your payments online, void any as necessary and manually release your file so that it may be finalized.
  4. Review returned payments: Payments that have been processed may be returned, for example if a customer charges a credit card payment back. You are notified of returned payments by a Return file. You should log into RAVEN Online daily to review your returned payments.

Submitting a Request and Processing the Response

To submit payments you need to integrate the “buy” page on your web server with the RAVEN server. We recommend you do this by using one of the available plug-ins. These deal with much of the complexity of interfacing to the RAVEN server, and are available in several programming languages. If there is no suitable plug-in available, it is also possible to interface to the RAVEN server by composing your own messages and posting them to the RAVEN server using HTTPS.

The recommended interaction is as follows:

  1. Based on the information received by your server from your “buy” page, compose an approval request and send it to the RAVEN server.
    • If you’re unable to connect, you can try again.
    • If the request times out before you receive a response, the request may or may not have been processed. Use the appropriate status request to find out.
  2. Once you’ve received a response, check the HTTP Status Code:
    • HTTP Status Code 200: Move to step 3 and check the Status field of the response.
    • If the HTTP Status Code is not 200: This is likely the result of a software or configuration error. See the table of HTTP Status Codes and take corrective action.
  3. Check the Payment Status Code
    • Approved, Declined or InProgress
    • Rejected: The request was incorrect and should not be repeated.
    • Invalid:Some of the data submitted by the user was not valid; you may choose to give the customer an opportunity to update the data.
    • Error: Depending on the error, the request may or may not have been processed. Contact Client Support for assistance.

Releasing Payments

When the first payment of the day is received by RAVEN from any submitter, RAVEN will create a new file using either the name supplied with the payment or, if no filename was supplied, a default name based on the submitter’s username and the date. Throughout the day payments entered by the submitter will be added to this file.

Submitters may be configured for auto-release or manual release of files.

  • If the submitter is configured to have their files released daily, then at the end of the day the file will be released for final processing. What that entails depends on the type of file but generally speaking it involves settling, shipping or taking whatever action is required to finalize the payment. No further action is required from you, nor is it possible to review your payments, choosing to settle some and not others.
  • If the submitter is not configured to have files released daily then at the end of the processing day you may review the payments you have submitted, void any as you deem appropriate and mark the file as “released”. Once the file is marked as released the payments will be settled. The file may be released using the API or by using RAVEN Online. If the file is not released for seven days after the first payment was submitted the file will either be automatically released or voided, depending on if the submitter is configured to have expired payments voided or have them released. Once a file is voided any approvals are lost.

Raven Integration