Getting Started

Card processing is the real-time approval and subsequent settlement of credit card payments.

The following types of integrations are available for integrating Card processing into your business, each with its own capabilities:

File Exchange

Upload payments, get results, and receive notice of returns.
---
Learn more about our File Exchange

API

Submit payments, void items, and get reports.
---
Explore the API documentation

Hosted Payment Page

Submit payments.
---
View Hosted Payment Page documentation

Client Portal

Submit payments, void items, get reports and view statements.
---
Log in to Raven Online Log in to Raven Online Log in to Raven Online Log in to Raven Online

Third Party Shopping Cart

Submit payments via a variety of third party shopping carts.
---
Explore our recommended solutions

Regardless of the type of integration chosen, account statements are typically supplied via the client portal or email.

PCI Considerations

Each type of Raven integration implies a particular security compliance burden.

The card schemes, MasterCard, Visa etc., mandate that all processors and merchants handle card holder data as specified by the Payment Card Industry Data Security Standard (PCI DSS).

Raven meets all requirements of the DSS and is audited annually to ensure this remains the case.

Self Assessment Questionnaire (SAQ)

You also have a role to play in data security. If you are a small to medium-sized merchant you are required to demonstrate compliance with the PCI DSS by submitting a Self Assessment Questionnaire (SAQ). There are four SAQ's that apply to merchants integrating to Raven:

SAQ Type Description
A This applies if you have outsourced all handling of the card holder and never transmit, process or store a credit card number, nor do your systems impact the integrity of the systems that collect payment data.
A-EP This applies if you have outsourced handling of the card holder and never transmit, process or store a credit card number, but your systems do impact the integrity of the payment page. This SAQ was added in 2016 to add additional security requirements for mechanisms that used to be eligible for the SAQ A but no longer are due to new threats.
C-VT This applies if you use an internet connected browser based Virtual Terminal to enter payments one by one. The Virtual Terminal must be on a network isolated from the rest of the corporate network.
D This applies if you transmit, process or store credit card numbers electronically.

SAQ by Type of Integration

By choosing a particular type of integration you may be able to reduce the amount of effort it takes to be PCI compliant. The following table shows which SAQ is implied by each type of Raven integration.

Mechanism SAQ to Complete Rationale
Raven File Exchange D Typically your systems are in possession of card numbers. Complete SAQ A if only submitting tokenized transactions
Raven API D Typically your systems are in possession of card numbers. Complete SAQ A if only submitting tokenized transactions
Secure Fields A-EP Even though you are never in possession of the card number, your page enables the encryption and if your site is compromised the encryption might be disabled.
iFrame A
Hosted Payment Pages A
Shopping Carts depends Depending on how the shopping cart is hosted and integrated, your compliance effort may range from an SAQ A to SAQ D. For example, Raven is integrated to some hosted carts which handle card data in a compliant way. If you use those carts you only need to complete a SAQ A. However if you host your own card with a direct API integration you will need to complete a SAQ D. And finally if you host a cart with an iFrame integration you will be back to a SAQ A.
Virtual Terminal C-VT SAQ A is not applicable because the card number is being entered on systems controlled by you and hence those systems need to be secured. This SAQ applies both if your staff are entering the card numbers or if the data is entered by the cardholder in a face-to-face environment.

Combining SAQs

If you have multiple sites or payment processors, you may be able to combine them into a single SAQ, according to the following rules:

  • The SAQ D includes all elements of the PCI DSS. One SAQ D can be used to cover all your sites and channels.
  • The SAQ A-EP and SAQ C-VT include different elements of the DSS. If some channels require a SAQ A-EP and others require a SAQ C-VT, you need to either complete both or complete a SAQ D.
  • The elements of the DSS in the SAQ A are included in the other SAQs. If you complete a SAQ D, SAQ A-EP or a SAQ C-VT you do not need to complete a separate SAQ A.

If you do choose to combine your self assessment into one SAQ be sure the combined SAQ covers all elements of your environment. For example, both the SAQ A-EP and the SAQ C-VT require a network diagram. If you combine those into a single SAQ D you will need to include diagrams for both environments. It is generally simpler (though more tedious) to complete two SAQs.

Note that the SAQ indicated is the minimum SAQ implied by choosing a given integration mechanism. Specifics of your process may require a higher SAQ. You should document your card data flows and then choose the appropriate SAQ.

Credentials

Production

The best way to get going is to use your own production credentials provided by client support. Credentials are specific to integration type.

File Exchange API Raven Online
User Name x x
Access Key[1] x
Password[2] x x
Security Token Optional
Routing Number[3] x x x
  1. Access Key is made up of an ID and Shared Secret.

  2. File exchange and Raven Online passwords are managed separately and may not be the same.

  3. Reported Payment integrations do not require a Routing Number since payment requests are not submitted. However, a Routing Number will be provided in the result file for your reference.

Test Mode vs Live Mode

Routing Numbers may be set up to process payment requests in test mode. When testing is complete, contact client support to switch the routing to live mode.

Testing

If you haven't yet received your production credentials, feel free to test your integration with the following:

Credential
UserName ernest
Password PinkGin!!
Access Key Secret all good men die young
RoutingNumber 840033

The test credentials support the following services:

  • Card payments in USD, AUD, CAD, EUR, GBP, NZD, JPY and ZAR
  • Debits and credits in USD, EUR SEPA and GBP.
  • Cheques issued in BRL, CAD, EUR, GBP, HKD, INR and USD.
  • Prepaid cards issued in USD, EUR, and GBP

Do not submit any private information. Any data submitted using the test credentials will be visible to all.

Overview

Raven offers many Card processing features. Be sure to familiarize yourself with our payment structure and features before diving into the documentation.

Payment Structure

Payment requests and responses are made up of collections of field-value pairs.

For example, a typical Card request could contain the following:

PaymentRoutingNumber = 840033
PaymentType = cc_debit
CardNumber = 4000000000000010
Expiry = 0933
Currency = CAD
Amount = 3340

Successful payment responses contain an echo of the request field-value pairs, as well as a Tracking Number. For example:

# echo of the request field-values (redacted)
Status = Approved
TrackingNumber = 5123534
ApprovalCode = 40887

Successful payment responses include a Tracking Number, which uniquely identifies the payment request and can be used as a template for subsequent payments.

Each Payment Type has its own collection of field-value pairs. Refer to our Payment Reference for more details.

Features

Basic features are aspects of payment processing that all integrations need to address. They are:

Optional features include:

Payment Submission

​You can charge a credit card by submitting a collection of field-value pairs to Raven. The simplest card payment consists of the following field-value pairs:

PaymentRoutingNumber = 840033
PaymentType = cc_debit
CardNumber = 4000000000000010
Expiry = 0933
Currency = CAD
Amount = 3340

Further reading: Payment Structure, Payment Fields

Settlement

Raven obtains immediate approvals for credit card transactions. Settlement occurs later and can be automatic or manual.

Automatic Settlement Manual Settlement
Payment Submission You submit payment, usually of type cc_debit (in the case of a sale) or cc_refund (in the case of a refund), but other specialized types exist. You make a payment request to Raven, but using cc_preauth instead of cc_debit as the payment type.
Settlement At a standard time, Raven settles all approved payments on a file by file basis. Once a file is marked for settlement all approved payments in the file are settled. You inform Raven of approved payments to settle. You must request a cc_settle payment providing the tracking number of the original cc_preauth. All valid cc_settle payment requests initiate a debit from a cardholder's account.

Manual settlement is a good option if you need to make ship/no ship decisions based on the availability of stock in your warehouse.

Some considerations when using manual settlement:

  • Time limit: While Raven allows up to 7 days to settle an approved preauthorization, some banks will not honour the approval after 96 hours.

  • No need to resend all payment details: A cc_settle payment need not include the card details, it only requires a mandatory PreauthNumber field. This field must contain the TrackingNumber that was returned in response to the original cc_preauth payment request.

  • Extra validation: When cc_settle payments are being processed, Raven checks that the preauthorization meets the following conditions:

    • the two have the same currency
    • the pre-auth was approved and the amount to settle is not greater than the amount that has been pre-authorized
    • the pre-auth has not expired or been used previously

Crediting Your Account

A few days after settlement, funds are credited to your account. You can view the deposits using Raven Online. You may also arrange to have an account statement mailed to you.

Chargebacks

Consumers typically have up to 180 days to charge back a credit card payment. When this happens Raven will create a Return file and place it in your web-folder. You can search for returns by day of return using Raven Online or a Raven API call.

Return files will be ticketed and your account will be debited the value of the charged back payments.

Recurring Payments

You can use a pre-existing payment as a template for recurring payments. This eliminates the need to store customer account details.

To use a template, supply the TrackingNumber of the original payment as the TemplateNumber of the recurring payment.

Do not supply values for fields that are supplied by the template as this will result in an error.

The template payment should be one that was successfully processed, however, it is not mandatory. It is possible for the original payment to be for a zero amount, in which case it will be invalid but you can still use it as a template.

There are time limits to the use of templates. As a default, payment details are stored for 180 days after the original payment. Every time you use a payment template the clock is reset, resulting in another 180 days.

If you are processing annual subscriptions and must store details for a longer period, you must inform us at setup and we will keep details for 14 months from the original payment, and then for 14 months from the last use of the payment as a template.

Delayed Processing

When processing with file exchange it may be useful to delay processing of a file until a specific date/time. You can do this by providing a UTC time stamp formatted as "YYYY-MM-DDThh:mm:ssTZD" in the header of the file as shown below:

RavenPaymentFile_v2.2,AuthorizeAfter:2011-05-17T14:45:00Z

To ensure we process your file on time, you must upload it to Raven the day preceding the AuthorizeAfter date. This allows time for staff to approve the file if necessary.

The AuthorizeAfter time is the precise time that authorization of the payments in the file will begin.

Due to the effect of daylight savings time, UTC is not the same as clock time in the UK and may be off by up to an hour.

Original Credit Transfers

Original Credit Transfer (OCT) is a specialized transaction type that allows you to apply credits to a card without first having debited the card.

The rules for using OCTs are complex. Contact your account representative before making use of this payment type.

Address Verification

Raven supports address verification (AVS) for UK and North American addresses associated with MasterCard and Visa cards. AVS is available for the payment types cc_preauth and cc_debit.

To make use of AVS you need to supply billing address information as part of a payment request. The required fields are BillingStreetAddressLineOne through BillingStreetAddressLineFour, as well as BillingPostalCode. The other billing address fields, such as BillingCity, have no effect on AVS.

If any of the street address or postal code fields are present in a payment request, the digits they contain are sent to the bank for verification and one of several response fields is returned:

  • AVSAddressResponseCode - the outcome of the street address verification
  • AVSPostalResponseCode - the outcome of the postal code verification

See the Payment Reference for the complete specification of Raven Card Payment AVS request and response fields.

Fraud Scoring

Fraud Scoring allows you to profile your customers and determine the likelihood that transactions from them are fraudulent. A fraud score is expressed as a percentage, with 100% being certain fraud.

By default, Raven will not take any action based on fraud scores. You should review your payment fraud scores and:

  • query the customer and conditionally void or settle the payment as normal
  • void the payment if you deem the score to be too high
  • do nothing and allow the payment to be settled as normal

To invoke the fraud scoring mechanism you need to provide at least CustomerIP, BillingCity and BillingCountry.

You can improve the quality of fraud scoring by supplying more information about the location of your customers. For example, supply the country and city for shipped goods, ShippingCountry and ShippingCity.

See the Payment Reference for the complete specification of Raven Card Payment Fraud Score request and response fields.

Blacklisting

You can maintain a list of customers that you no longer wish to do business with.

There is no API for this function. To have a customer added to your blacklist, please email your account representative with the tracking number of a prior payment and the associated customer will be blacklisted.

3-D Secure

3-D Secure (3DS) allows real-time credit card authorizations for Raven API only. 3DS requires the customer to identify themselves, thus providing additional assurances that they are authorized to use the card.

3DS works the same for both Visa and MasterCard. Visa refers to it as Verified by Visa (VbV) and MasterCard refers to it as SecureCode.

3DS is very much a web technology. A transaction using Verified by Visa or SecureCode redirects the customer to the website of the card-issuing bank to authorize the transaction.

3DS verification requires a more complicated three step interaction between your server, Raven, and a cardholder's issuing bank. See 3-D Secure for more information.

Flagging

Raven can flag approved cc_debit and cc_preauth payments before settlement for a variety of reasons.

Flags may be reviewed in Raven Online and are in one of 3 states:

State Description
Unresolved (Red, Initial State) You have yet to examine the flag and its repercussions with regard to a payment. The flag may either be accepted or rejected using Raven Online, however if no action is taken within 7 days the payment will be voided and never settled.
Accepted (Green) You acknowledge the flag but accept the payment regardless, allowing it to settle normally.
Rejected (White) You acknowledge the flag and reject the payment, forcing it to be voided and never settled.

Flagging can be configured to have one of two default behaviours:

Behaviour Description
Auto Reject If a payment is flagged you can choose to have it rejected out of hand. In this case the status will come back as Rejected:FlagsPresent. Choose this configuration if you know you never want to settle a flagged payment.
Hold You may also choose to have flagged payments put aside for further consideration. There is a slight difference between how this works for cc_debit and cc_credit payments. Flagged cc_debit payments will be moved to a separate payment file where they will be held for your review. Flagged cc_preauth payments may not be settled by a cc_settle payment unless all flags have been accepted. Either way, nothing will be settled unless you clear the flags.

MarketDirect customers will not be aware that their payment has been flagged. It may be necessary to inform the customer if you review the payment and decide not to proceed.

Unique Reference Enforcement

Contact client support to enable Unique Reference Enforcement to prevent duplicate payments.

Once enabled, you must supply a unique Reference for each payment request. Additional reference fields do not have this restriction.

See the Reference & Descriptor fields in the Payment Reference.

Currency Exchange Options

You can specify how currency will be exchanged to your customers by supplying either an Amount for an exact amount transaction, or AccountAmount for an automatic exchange at time of transaction.

Exact Amount

If you supply an Amount, your customer will receive that exact amount in a given Currency.

Automatic Exchange

If you supply an AccountAmount based on the currency associated with your account, the customer will receive an amount dependent on the exchange rate at the time of transaction.

For example, you may want to send 10USD from your account to customers who should receive it exchanged as EUR, CAD, or GBP.

To do so, your payment request must:

  • specify your account, via a RoutingNumber
  • specify the payment currencies of your customers, via the Currency field
  • supply an AccountAmount, rather than an Amount.

If AccountAmount value is present and is NOT zero, then the Amount field must be zero.

Manual File Release (Deprecated)

The recommended way to defer settlement is by first obtaining a preauthorization and then explicitly settling that preauthorization (as described in the section on settlement). Standard sales (type cc_debit) are normally released for settlement automatically just prior to the daily cutoff.

However Raven supports the notion of deferring settlement of a file until explicitly triggered. This is done by setting your configuration to manual-release. In this case you files will not be sent for settlement until explicitly released by you using Raven Online or the Raven API. You have 7 days to determine what to do with your file. When using manual release after 7 days your file will be voided or released depending on your configuration.

This feature is deprecated and will not be supported by future versions of Raven.

This option only applies to items submitted using the API, files uploaded using the Raven file exchange are considered to be released when loaded.

Payment Reference

Fields are categorized as follows:

For the column labeled '?', M = Mandatory, C = Conditional, O = Optional

Refer to the Type Reference for all Type definitions.

Basic

Name Type Size ? Remarks
RoutingNumber 0-9 6 M

The six digit payment routing number assigned to you.

PaymentType Enum n/a M

Credit and debit from the customer’s perspective. The possible types are:

  • cc_refund Card Payment Refund
  • cc_preauth Credit card preauthorization later settlement.
  • cc_debit Used when selling products with imediate fulfillment. Combines authorization and funds capture.
  • cc_update Used when requesting VAU/ABU update for a template payment.
  • cc_credit Used to credit an account such as when refunding.
  • cc_settle Settle funds previously authorized.
  • cc_oct Original Credit Transfer
  • cc_verify Used when requesting card verification.
Currency Enum n/a M

The three character ISO currency code, e.g. USD or EUR.

Amount 0-9 1 - 25 M

Value supplied in base units of currency, with no decimal. E.g. $150.00 is 15000. For payments of type cc_settle, transaction value must be identical to Amount value for the corresponding cc_preauth payment. Please note that JPY transactions should have no decimal units. The amount is to be supplied as is, with no changes. Therefore, if the amount to be billed is 5000 JPY, it would be supplied as 5000 in the file.

CardNumber† 0-9 12 - 19 M

The number as found on the card that is to be debited or credited. Not required for cc_settle.

Expiry† 0-9 3 - 4 C

The expiry date of the card, in MMYY format. Not required for cc_settle.

AccountName† Unicode 1 - 40 O

The name exactly as printed on the card.

CVV2 0-9 3 - 6 C

The CVV2 or security code of the card. Highly recommended for eCommerce transactions where it will improve approval rates.

Token Latin1 1 - 1048576 O

The value of raven-token field received from an iframe-powered form. If you supply this field, you should not supply CardNumber, CardExpiry, and CVV2 fields.

TrackingNumber 0-9 9,10 M

Raven will return a unique tracking number for each payment processed.

Status ASCII 1 - 50 M

One of the following status codes:

  • AccountInvalid cc_verify only
  • AccountValid cc_verify only
  • Approved the request has been approved and the payment can be settled.
  • ConfigError:"error" due to a RAVEN configuration error the payment could not be processed.
  • Declined the request was declined and the payment may not be settled.
  • Error: "error" an unusual error condition has occurred.
  • ExpiredCard
  • InProgress the payment has been received and will be processed.
  • InsufficientFunds
  • Invalid::"field" a field in the request is invalid
  • InvalidAccount
  • InvalidAmount: limit on card exceeded
  • InvalidMerchant
  • OverDailyLimit
  • Pending3DS the payment has been received and response included information to complete 3DS authentication
  • PickUpCard payment has been declined and the merchant should confiscate the card if possible.
  • ReferToIssuer the payment could not be approved. Call the issuing bank for clarification.
  • Rejected:"reason" the payment, while valid, has been rejected for another reason.
  • RestrictedCard
  • Retry
  • StopServiceRequest
  • Submitted the payment has been submitted to the clearing system.
  • SuspectedFraud
  • TooManyAuths
  • UnableToAuth
  • UnexpectedResponse:"value" the bank has returned an unexpected error condition.
  • ViolatesLaw
  • Voided the payment has been voided and will not be processed.
ApprovalCode ASCII 1 - 25 C

Approval code as returned by the card scheme. If available, it will only be present in the case of approved cc_debit or cc_preauth payments. Note: This number is not unique.

CardScheme Enum n/a C
CVV2ResponseCode Enum n/a C
  • cvv2_matched CVV Matched
  • cvv2_not_checked CVV Not Checked
  • cvv2_not_matched CVV Not Matched
  • cvv2_response_unknown The CVV2 response is not known or supplied
  • cvv2_unavailable CVV Check Unavailable

Reference & Descriptor

Name Type Size ? Remarks
Reference Unicode 1 - 100 O

Information the merchant may supply at their discretion identifying the payment or customer. Will be echoed on reports. Will not appear on customer statement. This field is recommended but optional.

If unique reference enforcement is enabled then each reference number must be unique.

Reference[i] Unicode 1 - 100 O

Additional reference field containing information the merchant may supply at their discretion identifying the payment or customer. Up to 9 with name Reference2, 3, 4... etc. Will be echoed on reports but will not appear on customer statements.

Manual Settlement

Name Type Size ? Remarks
PreauthNumber 0-9 6 - 30 C

Mandatory for PaymentType cc_settle. Its value must be the TrackingNumber value for the corresponding cc_preauth payment.

Fraud Scoring & Address Verification

Name Type Size ? Remarks
SourceIP IP 1 - 45 C

The IPv4 or IPv6 address of the customer that originated the request. Required to trigger fraud scoring.

Email ASCII 1 - 100 O

Will improve quality of fraud score.

BillingAddressLine[i] Unicode 1 - 100 O

Card holder address line. Up to three may be supplied called BillingAddressLine1, 2 3 etc. Required to trigger address verification.

BillingCity Unicode 0 - 1048576 O

The name of the city in the card holders's address

BillingCountry Unicode 0 - 1048576 O

The name or two letter ISO country code of the customer's credit card billing address. Required to trigger fraud scoreing.

BillingPostalCode Unicode 1 - 10 O

The postal code of the card holder's address Required to trigger postal code verification.

BillingProvState Unicode 0 - 1048576 O

The name of the region (e.g. province/state) in the card holder's address.

AVSAddressResponseCode Enum n/a C
  • avs_address_matched AVS Address Matched
  • avs_address_not_checked AVS Address Not Checked
  • avs_address_not_matched AVS Address Not Matched
  • avs_address_partial_match AVS Address Partially Matched
  • avs_address_unavailable AVS Address Check Unavailable
AVSPostalResponseCode Enum n/a C
  • avs_postal_matched AVS Postal Matched
  • avs_postal_not_checked AVS Postal Not Checked
  • avs_postal_not_matched AVS Postal Not Matched
  • avs_postal_partial_match AVS Postal Partially Matched
  • avs_postal_unavailable AVS Postal Check Unavailable
FraudResponse Unicode 1 - 4000 C

Full fraud/geolocation response from the fraud scoring service. See the output table in the MaxMind documentation.

FraudScore 0-9. 1 - 10 C

Will be returned if the CustomerIP and BillingCountry were provided in the request. Fraud score between 0.00 and 100.00 representing the estimated probability that the payment is fraudulent based on the fraud risk score request values and analysis of past transactions. See the documentation where this value is known as the Fraud Risk

Recurring

Name Type Size ? Remarks
IsRecurring Boolean n/a O

If you are processing recurring payments and are not using 'TemplateNumber' field above to initiate payments subsequent to original debit, this field should be set to "yes" for recurring payments and "no" for original payments in order to improve approval rates with some of the issuers.

  • yes
  • no
TemplateNumber 0-9 6 - 30 C

'TemplateNumber' must be the tracking number of a successful card payment. If provided, the fields marked with an † (the account data) will be pulled from the template payment and must not be supplied. Template payments must have the same payment routing number as the one they are being applied to. It is an error to supply values that will be pulled from the template. For example, if TemplateNumber is supplied it is an error to supply an account number. TemplateNumber is mandatory for cc_refund.

3DS

Name Type Size ? Remarks
3DSVerify Boolean n/a O

Flag indicating whether or not 3DS should be attempted for this transaction.

  • yes
  • no
3DSMerchantURL Unicode 1 - 1024 O

The URL of the website on which the payment is being made

3DSDeviceCategoryCode Enum n/a O

Indicates the type of device used to initiate the transaction: + mobile + desktop

  • desktop HTML Capable Device
  • mobile WML Capable Device
3DSBrowserAcceptHeader Unicode 1 - 4096 O

The MIME types of the headers accepted by this device.

3DSBrowserUserAgentHeader Unicode 1 - 4096 O

The user agent string of the user agent.

3DSPARes Unicode 1 - 4096 O

The Payer Authentication Response (PARes) returned by the ACS.

3DSCardEnrollment Enum n/a O
  • attempted Enrolled cardholder, but authentication is currently unavailable
  • available Authentication available
  • unavailable Authentication not available
3DSACSURL Unicode 1 - 4096 C

The URL of the issuing bank’s ACS, to which the cardholder needs to be re-directed.

3DSPAReq Unicode 1 - 4096 C

The Payer Authentication Response (PARes) returned by the ACS.

3DSResponseCode Unicode 1 - 4096 C

Indicates the outcome of the 3DS authorization

  • not_attempted initial status, also status of all payments where 3DS is not requested
  • attempted interim status after returning the ACS URL.
  • passed user was authenticated and the 3DS guarantees apply.
  • failed the user was not authenticated by the ACS the payment will be marked as declined.
  • unavailable 3DS could not be invoked, no 3DS guarantee applies.
  • merchant_not_participating 3DS could not be invoked, no 3DS guarantee applies.
  • scheme_not_participating 3DS could not be invoked, no 3DS guarantee applies.
  • abandoned any 3DS payment not completed within 24 hours will be voided and marked as abandoned. No approval attempt will have taken place.

Exception Flagging

Name Type Size ? Remarks
FlaggedForReview Boolean n/a C

Indicates this payment was flagged for review. The possible reasons for flagging are:

  • avs_address_mismatch
  • avs_address_not_checked
  • avs_address_partial_match
  • avs_postal_mismatch
  • avs_postal_not_checked
  • avs_postal_partial_match
  • cvv2_mismatch
  • cvv2_not_checked
  • exceeds_max_amount
  • exceeds_max_amount_velocity
  • exceeds_max_count_velocity
  • fraud_score_not_available
  • high_fraud_score
  • not_fully_3ds
  • prepaid_card
  • unacceptable_country
  • unknown

Possible values are:

  • yes
  • no
UnresolvedFlags Unicode 1 - 4096 C

A list of unresolved flags for the payment. The possible flags is given in FlaggedForReview.

Non-payment data MCC6012

Name Type Size ? Remarks
RecipientAccountName† ASCII 1 - 40 C

The name of the recipient of the loan, may be someone other than the cardholder. Mandatory for UK MCC6012 Visa items

RecipientAccountNumber† Unicode 1 - 20 C

The bank account number of the recipient of the loan, may be someone other than the cardholder. Mandatory for UK MCC6012 Visa items

RecipientDateOfBirth† yyyymmdd 8 C

The date of birth of the recipient of the loan, may be someone other than the cardholder.Mandatory for UK MCC6012 Visa items

RecipientPostalCode† ASCII 1 - 10 C

The post code of the recipient of the loan, may be someone other than the cardholder.Mandatory for UK MCC6012 Visa items

Type Reference

The value all key-value pairs must conform to the following types:

Type Description
A – alphabetic An alpha field contains a sequence of the characters a-z in upper or lower case.
[0-9] – Numeric A numeric field contains a sequence of the digits 0-9. It may not contain a negative sign (-) or a period (.).
AN – Alpha Numeric An alpha numeric field contains a sequence of the digits 0-9 and the characters a-z in upper or lower case.
format+(char_1, char_2…char_n) The given format plus the space, dash and exclamation mark characters. For example, AN+(s, -, !) is alpha numeric plus the space, dash and exclamation mark.
TS – Timestamp All timestamps should be the current time in Coordinated Universal Time, rather than the local time for a particular server. Since UTC is the same timezone as GMT (which has the timezone code Z) it is often called Zulu time in military and aviation communications. Timestamps should contain the complete date and time, including seconds. They should be formatted according to the W3C Note on date and time formats for use on the web. The format is: YYYY-MM-DDThh:mm:ssTZD. For example, 6:03 pm on Jan 17, 2006 could be formatted as: 2006-01-17T22:18:03Z.
ASCII A text field contains a sequence of characters in the Unicode decimal code point ranges 32 to 126 and 160 to 255 (almost identical to the ASCII characters in the same ranges). Broadly speaking, these are the digits 0-9, the characters a-z in upper or lower case, the punctuation characters as well as extended Latin characters such as “umlaut A” (Ä). Note that only internal spaces will be preserved. In the case of text fields containing descriptive data such as addresses and names rather than reference numbers, code point values above 255 are mapped to the closest base character if possible. So Š will become S.
Unicode A text field contains a sequence of Unicode characters. Note that only internal spaces will be preserved.
Enum A field specified as ‘Enum’ contains only ONE of the values listed as permissible
B – Boolean A Boolean field contains either ‘yes’ (could also be expressed as ‘true’ or ‘1’) or ‘no’ (could also be expressed as ‘false’ or ‘0’).

Notes:

Any tab and space characters before or after a field are ignored.

All contiguous space characters within a field are collapsed into a single space character except for Reference and Comment fields.

In some cases the characters accepted by Raven are not the ones transmitted to the bank. For example, BACS accepts only upper case letters, digits, spaces and a few punctuation symbols. Raven will convert fields to match (e.g. é to E) before submitting data to BACS.

Glossary

This section defines the special terms used throughout this document.

Access Key : An authentication token that is made up of an ID and Shared Secret.

Account : One or more accounts may be defined, which may be in multiple currencies. Each account has its own balance and will receive reports separate from other accounts.

Account Manager : The Account Manager role allows users to view account statements for the accounts they have access to. They may also request that account statements be emailed to them as a PDF document.

DBA : "Doing Business As", the trade name or business name pseudonym

Payee : These represent the various "doing business as" names a client might have. For example, the company Senoma Ltd. may have two DBA names: Value Wines and Senoma Wines. Since payments will be sent to these accounts, they are listed as a Payee. A client may have as many Payees as they wish.

Routing Number : The Routing Number, or Payment Routing Number (PRN), indicates where and how an incoming payment should be processed.

Settlement : The physical transfer of funds into an account.

Submitter : The submitter role allows a user to submit payment to one or more payment routing numbers. Submitters are able view the payments they have submitted and release files they have submitted. Submitters are not able to access payments submitted by others or view client accounts.

Submitter Manager : The Submitter Manager role allows a user to view payments and release files for one or more payment routing numbers. A Submitter Manager is not able to view client accounts.

Webfolder : Each user may have a webfolder. If a user has a webfolder configured for them, they can use it to submit batch files and receive response files from Raven. Logging into a webfolder requires a URL that has been customized for the user as well as a password.

File Exchange

File Exchange lets you upload payments, get results, and receive notice of returns. It is suitable for simple, manual, batch submission where many transactions are submitted in one file and the processing results for all the transactions are returned together.

Two Upload Options

Webfolders : You are given a set of server-side web folders to submit requests and receive results.

Raven Online: You can use Raven Online Raven Online Raven Online Raven Online to upload batch files and view and subsequently download the various outcome files.

By default, no explicit Receipt or Reject files will be produced in Raven Online.

Workflow

The following is a typical interaction using File Exchange web folders:

  1. Create Request File

    You create a properly formatted Request File, containing one or more payments.

    File formats
    How to create a request file
    List of payment fields available

  2. Submit Request File

    You submit the Request File to Raven by logging into the Raven file server and placing the file in the Payments folder.

    Required credentials
    How to access your webfolder

  3. Raven Processes Request/Receipt/Reject Files

    Raven loads the Request File and, if it is acceptable, puts a Receipt File into the Reports folder. The Receipt File shows the results of a preliminary validation of each payment. If the request file contains errors, Raven places a Reject File in the Reports folder. Reject and Receipt files are generally created within five minutes. In exceptional circumstances it may take up to one hour.

    About receipt and reject files

  4. Raven Produces Result File

    Once the payments have been processed, Raven places a Result File into the Reports directory. The time it takes to generate a Result File depends on the payment type. For some types, such as credit card processing, the Result File follows shortly after the Receipt File. For other types, such as requests to print and ship paper cheques, the Result File may take hours.

    About result files

  5. Raven Produces Return File

    Payments may be returned after they have been processed. If a user elects to be advised of returns, Raven places a Return File into the Reports directory containing those payments.

    About return files

Web Folder Access

Every contact is given a user name and password to access their web folder.

The contact can submit payments depending on the Routing Number they have access to. Customer support can configure your Routing Numbers and number of submitters your company has.

Location

All File Exchange web folders are located at:

https://dataexchange.deepcovelabs.net/(username)

For example, assuming your username is john.smith, your web folder would be located at:

https://dataexchange.deepcovelabs.net/john.smith

and you would see the following directories:

/john.smith
  /payments
  /reports

Access Methods

Use any of the following techniques or tools to access your web folder:

Windows

Go to "My Computer" or "This PC" and right click in an empty section of the right hand panel and select "Add Network Location". When prompted for the network location, enter the web folder URL. Continue entering your username and password when you are prompted for them. You may be prompted several times.

macOS

Select "Connect to Server" from the Finder's "Go" menu. When prompted for the network location, enter the web folder URL. Continue entering your username and password when you are prompted for them.

cURL

cURL is a command line tool for transferring files with URL syntax, supporting almost all available file transfer mechanisms, including web folders via HTTPS. cURL is free software that compiles and runs under a wide variety of operating systems.

Upload

curl --user (username):(password) --upload-file payments.csv "https://dataexchange.deepcovelabs.net/(username)/payments/"

Download

curl --user (username):(password) "https://dataexchange.deepcovelabs.net/(username)/reports/payments.csv RECEIPT.txt"

BitKinex

BitKinex is a full-featured freeware product for Windows available from Barad-Dur, LLC.

WebDrive

WebDrive is a commercial product available from South River Technologies. WebDrive is a file transfer client for web folders and provides an easy way to mount a web folder as a local drive under Windows and macOS.

File Formats

There are several different types of files that make up File Exchange interactions between you and Raven.

File Type Description Source
Request Contains payments You
Receipt Confirms that processing has begun on Request Files Raven
Reject Documents validation errors in Request Files Raven
Result Result of submission Raven
Return Contains payment returned by the bank Raven

Universal File Exchange Format

All File Exchange files share the following universal format:

  • a number of lines in a specific order
  • each line is composed of one or more fields
  • fields are comma separated (CSV)
  • the characters used for fields must be ASCII or UTF8 text (BOM is mandatory)

The first few lines contain header information specific to the file type. After the header lines are any number of payment lines containing values for the fields specified in the header line. After the payment lines is a footer line, and in some cases a summary section.

Request

Request Files define what transactions are to be executed and on whose behalf. A simple Request File may look like this:

RavenPaymentFile_v2.2
RoutingNumber, PaymentType, Currency, Amount, CardNumber, Expiry
840033, cc_debit, GBP, 1200, 4000000000000028, 1217
840033, cc_debit, CAD, 1000, 4000000000000010, 1106
RavenFooter, 2, 2200

Every valid payment Request File has the following four line types:

  1. Header

    The first line, the file header, tells Raven to expect a payment file matching the file specification version (currently 2.2).

  2. Field Names

    The second line is a comma-separated list of the payment fields whose values you are supplying. Field names are specific to each payment type. The only constraint is that the first field of the field names line must always be RoutingNumber. Other fields, such as Currency and Amount, can be presented in any order. To see what other information you can supply, consult the field reference.

  3. Payment Lines

    Following the field names line are one or more payment lines. All of the information presented in each payment line must correspond with the order presented in the field names line. For example in this case the first field (840033) is the RoutingNumber.

  4. Footer

    The last line is the file footer. The footer starts with "RavenFooter" and then indicates the total number of payments and the sum of all the amounts in the file, irrespective of whether they are credits or debits.

    Blank lines and comment lines are optional (see Universal File Exchange Format).

Mixed Payment Types Allowed

A Request File may contain different types of payments, such as credit card debits and credits (cc_credit and cc_debit) but should only contain payments of one "family" per payment file, as identified by the characters before the first underscore of the payment type. E.g. you cannot mix cc payments with deeft payments. Or even deeft payments with nleft payments. However, you may submit payments of various currencies within the same payment file.

Use of Commas and Double Quotes

If commas form part of a field then the field must be surrounded by double quote characters (").

Suite 23, 234 Main Street

"Suite 23, 234 Main Street"

If a field includes a " character then you must precede each double quote character by an additional double quote character and then place double quote characters around the entire field.

Alexander "Alex" Smith:

"Alexander ""Alex"" Smith"

Comments

A comment line is any line starting with the "#" character. Raven ignores and discards comment lines. You may place comment lines before the Header and after the Footer. You may use comments for notes or any other kind of information that you need for your own reference. Blank lines are also ignored and may occur anywhere in the file before the Header line and after the Footer.

#This is a comment

#This is another comment, there is a blank line between the two comments

File Naming Up To You

You may use any naming scheme that you wish. We recommend you never use the same file name twice. The best practice is to adopt a naming protocol which is consistent, and which uses sequential or consecutive numbers. For example, you can incorporate the company name, the date and a sequential number into a file name pattern like this:

AthleticDigest_DDMMYY_1.txt.

It is suggested that you only use numbers, letters, -,_ and . when naming your files.

Creating CSV Files in Windows

You can use any text editor to create payment Request Files. Care must be taken if you choose to use a spreadsheet program, such as Microsoft Excel.

When creating payment files with Excel, it is very important that you format all cells as TEXT. Otherwise, Excel may automatically add decimal places to the amount column, or drop zeros from other columns while you type or when it comes time to save the file in CSV format.

Excel has many automatic formulas, and using Excel to open a finished CSV file can alter the data, making it unreadable by the Raven system. This problem can be avoided by viewing completed CSV files in Notepad or WordPad only.

Receipt

Raven produces a Receipt File after receiving and validating your Request File. Receipt Files confirm that processing has begun and indicate the payment lines that failed validation. Receipt files can be found in the Reports web folder.

The Receipt File corresponding to the Request File example above would look like this:

RavenPaymentFile_v2.2, Receipt, myfile.csv
RoutingNumber, PaymentType, Currency, Amount, CardNumber, Expiry, Status
840033, cc_debit, GBP, 1200, 400000***0028, 1217, InProgress
840033, cc_debit, CAD, 1000, 400000***0010, 1116, Invalid:Expiry
ExpiryRavenFooter, 2, 2200

Receipt Files echo the corresponding Request File with five differences:

  1. The Receipt File omits comment lines, blank lines and any extraneous white space between fields.
  2. The header line contains two additional fields (the file type and the name of the Request File) resulting in the header:

    RavenPaymentFile_v2.2, Receipt, memberships_23112005_1.txt.
    
  3. Account numbers in the payment lines are masked.

  4. Each payment line contains the status of the payment. This is either InProgress which means the payment has been accepted for processing, or a status indicating a problem with the payment. The possible statuses are listed in the sections documenting the various payment types.

  5. Receipt Files have a name that is simply the original Request name with " RECEIPT.txt" appended to it. For example:

    memberships_23112005.txt RECEIPT.txt
    

Reject

Raven produces a Reject File for Request File that do not pass validation.

Raven names the reject file after your payment file with " REJECTED.txt" appended to it. At the top of the file, you will find a description of the problem so that you can correct and resubmit.

FILE REJECTED This payment file could not be processed because:The file contains
a footer that indicates the wrong payment total.
======================================================================
RavenPaymentFile_v2.2
RoutingNumber, PaymentType, Currency, Amount, CardNumber, Expiry
840033, cc_debit, GBP, 1200, 4000000000000028, 1217
840033, cc_debit, CAD, 1000, 4000000000000010, 1106
RavenFooter, 2, 2300

Result

After Raven submits your payment file to the bank for final processing, Raven returns a Result File. The Result File describes the outcome of each of the individual payment requests. The number of Result Files you receive is dependent on the type of payment request that are in the original Request File.

For example, credit card Result Files include the outcome of the approval stage, but EFT Result Files include the outcome of the Raven validation stage.

The Result File corresponding to the Request example above would look like this:

RavenPaymentFile_v2.2, Result, memberships_23112005_1.txt
RoutingNumber, PaymentType, Currency, Amount, CardNumber, Expiry, Status, TrackingNumber, ApprovalCode
840033, cc_debit, GBP, 1200, 400000***0028, 1217, Approved, 50000023, 00AUTH1
840033, cc_debit, CAD, 1000, 400000***0010, 1106, Invalid:Expiry, 50000027,
RavenFooter, 2, 2200
RavenSummary
840033, USD, Approved, 1, 1200
840033, CAD, Invalid, 1, 1000

Result Files echo the corresponding Request File with some minor differences:

  1. The Result File omits comment lines, blank lines and any extraneous white space between fields.
  2. The header line contains two additional fields: the file type and the name of the Request File, resulting in the header

    RavenPaymentFile_v2.2, Result, memberships_23112005_1.txt.
    
  3. The Field Names Line contains the additional fields of Status, TrackingNumber and any type specific result files. For example, card payments may include an ApprovalCode as a result field.

  4. Account numbers in the payment lines are masked.

  5. Each payment line contains the status of the payment after processing, a TrackingNumber which identifies the payment in Raven and any type-specific results. The possible statuses and type-specific result fields are listed in the sections documenting the various payment types.

  6. Following the footer line there is a summary as described below.

Do not assume a specific number of columns but rather allow for the possibility that more columns may be added to the end.

Result Summary

The summary only exists in Result Files. The summary follows the footer line and provides information on the results of processing the Request File. The summary section is not intended to be read by a computer program. It is a human-readable breakdown of the Result File by routing number, currency, and status. The layout of the summary may change over time. If you are developing software to process Result Files, we recommend you stop processing after you have read the Footer line.

The summary section consists of the header, "RavenSummary" followed by a summary detail for each payment from the original Request File. Each summary detail has a routing number, ISO currency code, status name, payment count, and absolute (not net) payment value for that currency. For example:

RavenSummary
840033, GBP, Approved, 1, 1200
840033 , CAD, Invalid, 1, 1000

Result Files have a name that is simply the original Request name with " RESULT.txt" appended to it. For example:

memberships_23112005.txt RESULTS.txt

Return

From time to time, payments submitted to the bank will be returned. The reasons vary depending on the payment type but the most common are:

  • no funds available
  • incorrect account information
  • customer charge back (e.g. revoking authorization)

Return files contain returned items as they are received by Raven.

An example of a Return File is:

RavenPaymentFile_v1.0, returns
PaymentRoutingNumber, PaymentType, CurrencyCode, Amount, Reference, Comment, PayeeName, AccountIdentifier,  Status, TrackingNumber, SubmissionDate, SubmissionFile, ReturnDate
983572, cc_debit, GBP, 12000, BWL037A,, WineClub, 458372***4532, Returned:Not Authorized, 50000023, 2006-01-19,  memberships_23112005_1.txt, 2011-03-04
RavenFooter, 1, 12000`

Note the non-standard naming of some of these fields. These fields are defined as:

Field description Format Max. Size Remarks
Payment Routing Number Numeric 6 The six-digit payment routing number assigned to you.
Currency Alpha 3 The three-character ISO currency code of the payments in a summary line.
Status One of 50 See the section describing the specific payment type you submitted.
Payment Count Numeric 12 Number of all payments in the status listed immediately prior.
Subtotal Numeric 12 Total of all payment amounts in the status listed immediately prior.

The simplest way to deal with a Return File is to look up the original payment in your system using the tracking number. Handle the returned item based on the return reason encoded in the Status.

A Return File is made of up the following parts:

  • Your account name that the original payment was processed under, e.g.: "EUROPE_1"
  • The currency of your account
  • A payment category identifying the kind of payments, e.g. cc, chq_issue or usach
  • The date the return file was created in YYYY-MM-DD format, e.g. 2006-06-07
  • RETURNS.txt

Putting this all together results in: EUROPE_1 GBP CC 2006-06-07 RETURNS.txt

API

You can interact with Raven using defined endpoints. If you have your own existing systems or websites to do payment processing and wish to integrate Raven into them, then the Raven API is a good choice.

Using Raven API directly may mean that your systems must conform to a higher level of PCI compliance. If you are interested in avoiding some of that compliance headache, then please consult PCI Considerations to review your options.

In this section:

Sending Requests

Encode a complete and valid set of endpoint parameters into the body of an HTTP request, as specified by the HTML Standard and RFC2388. Do not encode them into a query string.

Use the base address https://raven.deepcovelabs.net/realtime/ followed by the desired endpoint, then POST the valid set of endpoint parameters.

A proper Submit Endpoint, for example, will contain the following URL encoded form data:

RAPIVersion=2&RequestID=EUEtJlhwcCvxQLEB&UserName=ernest&Timestamp=2006%2D01%2D17T15%3A26%3A30Z&RoutingNumber=840033&PaymentType=cc_debit&Currency=CAD&Amount=5493&CardNumber=4000000000000010&Expiry=0933

Authorization

You must sign each API request. The Raven API uses a HMAC message hash as defined in RFC2104. Supply the HMAC hash as lowercase hexadecimal digits (hexits).

Our Raven API Integration Libraries automatically sign requests for you.

Generating a Signature

Functions to calculate HMAC are widely available and typically take three parameters:

  • Access Key Shared Secret - this is the shared secret associated with your username.
  • Hash Data - selected fields from the API command concatenated together into one string. The fields to use are described with each API command.
  • Hash Algorithm - Raven prefers SHA1

For the Submit Payment endpoint, the fields used in the HMAC are: UserName, Timestamp, RequestID, PaymentType, Amount and Currency. For example, using the shared secret "ernest", calculate the HMAC in PHP as follows:

hash_hmac(  'sha1',
'ernest2006-01-17T15:26:30.Zasdf9090asdlasdfasldscc_debit100CAD',
'ernest')

You can also use our Signature Calculator to generate your signature.

Processing Responses

Raven returns responses to you as form data encoded in the same way as the POST. Responses include result fields in addition to the fields supplied in the request. Raven masks data that it considers sensitive, such as card numbers.

An HTTP status 200 indicates the response has been successfully processed. The body of the response contains the results of processing. See the HTTP Status Table to determine how to respond to other status codes.

An HTTP status of 200 response will look like this:

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

The response is URL-encoded. Decoding this same information as a field-value pair results in:

UserName = ernest
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.

HTTP Status Codes

HTTP status 200 will contain field-value data. All other responses will only contain a single field-value pair, "RequestResult=(value)" where the value describes the error situation.

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 endpoint.
400 duplicateRequestID,invalidParameters 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 noSuchItem,unableToResolveRequest 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.

Real-Time v.s. Batch Processing

If processing requires an immediate approval response, for example card payments, then Raven API is preferable.

If processing cannot happen immediately, for example printing of paper cheques, you can gather the payment requests in a file to be processed once released. You can configure batch processing so that all items are released automatically at the end of the day or explicitly using the closefile endpoint. Raven will void unreleased items after 7 days. This is different from using File Exchange, where Raven releases files when loaded.

Workflow

The following is a typical interaction using API:

  1. Prepare Your Environment

    For some common programming languages we provide helper libraries that make communication with Raven API easier. We recommend that most of our clients use our helpers, since they eliminate many possible sources of integration error, in particular the calculation of signatures.

    Required credentials
    Our recommended API Libraries

  2. Submit Request

    There are many requests you can make of API, such as generating a report or voiding a payment.

    API Endpoint Reference
    How to send a Request

  3. Handle Response

    Raven responds to your request. Your application or server must then process this response appropriately. If no response is received you will need to use the Response endpoint to inquire with Raven and determine if Raven received your request and what the response was.

    About the Response endpoint
    How to process responses

  4. Review Payments and Release Items

    If you are not setup for auto-release, you should review your payments online at the end of the day and release the file either using Raven Online or by submitting the Release File endpoint.

  5. Review Returns

    Payments that have been processed may be returned. You are notified of returned payments by a Return file. You can also review your returns using Raven Online or by using the Payments Report endpoint.

    Payments Report endpoint

Signature Calculator

This calculator never sends your information to the server, you can use your access key safely.
Fields To Sign:
Concatenated Field Values:
Signature Merchanism:
HMAC_SHA1("", "")
Hex-encoded Signature:
Fields To Sign:
Concatenated Field Values:
Signature Merchanism:
HMAC_SHA1("", "")
Hex-encoded Signature:

End Points

Using the Raven API suite of endpoints, your applications can communicate in real-time with Raven over the internet. Typically, the foundation of Raven API usage is the submission of payment requests (using the Submit endpoint), however there are many other endpoints available to you:

Endpoint URL Description
hello https://raven.deepcovelabs.net/realtime/hello Ping Raven, eliciting a simple response
submit https://raven.deepcovelabs.net/realtime/submit Send a payment request
complete https://raven.deepcovelabs.net/realtime/complete Complete a 3DS approval cycle see
response https://raven.deepcovelabs.net/realtime/response Enquire about a missing response
status https://raven.deepcovelabs.net/realtime/status Determine the current status of a payment
void https://raven.deepcovelabs.net/realtime/void Void a payment
clearflags https://raven.deepcovelabs.net/realtime/clearflags Clear any flags preventing a payment from being settled
closefile https://raven.deepcovelabs.net/realtime/closefile Release a payment file for settlement
voidfile https://raven.deepcovelabs.net/realtime/voidfile Void a payment file and all its payments
payments https://raven.deepcovelabs.net/realtime/payments Search for payments
events https://raven.deepcovelabs.net/realtime/events Search for payments and their history

Hello

URL: https://raven.deepcovelabs.net/realtime/hello Purpose: To simply elicit a hello response from Raven. No payment-related processing takes place. Summary: Useful for debugging communications, time stamps and signatures.

Request Fields for /hello

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 O Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 O Any value unique for the UserName (a given user may never submit the same RequestID twice). This can be implemented using a UUID, GUID or even the machine name followed by a microsecond timestamp. If no RequestID is provided one will be assigned.
Signature N 40 M SHA1 HMAC of either just the UserName or the HMAC of the follow values concatenated:
UserName
TimeStamp
RequestID

Response Fields for /hello

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 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 M Response will be: “Hello from Raven. Current date and time in GMT.”

Sample Code for /hello

cURL

Live sample: To try it, paste the following into cURL and execute.
["UserName", "Timestamp", "RequestID"]
curl https://raven.deepcovelabs.net/realtime/hello \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=EUEtJlhwcCvxQLEB" \
  --data-urlencode "Timestamp=2016-09-09T14:01:25Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "Signature=40b44707e6b0b0eda1b2d8b725e8d7305edaf25e"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');

$request =  new Raven\Request('hello');

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("hello");

var response = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;

RavenRequest request = new RavenRequest("hello");

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model

let rvnResponse (id:string)(secret:string)(request:Request) = Raven(id,secret).Send(request)

let response = rvnResponse "ernest" "all good men die young" (Request("hello"))

Submit

URL: https://raven.deepcovelabs.net/realtime/submit
Purpose: To send a payment request to Raven.

Request Fields for /submit

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 M Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 M Any value unique for the UserName (a given user may never submit the same RequestID twice). This can be implemented using a UUID, GUID or even the machine name followed by a microsecond timestamp.
Signature N 40 M SHA1 HMAC of the following values concatenated:
UserName
TimeStamp
RequestID
PaymentType
Amount
Currency
Filename AN 150 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), where short username is normally the same as UserName. One exception is when UserName is an email address, in which case only the first element of the address is used (e.g. for "[email protected]", "ernest" would be used).

If the file doesn’t exist it will automatically be created.

Response Fields for /submit

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 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: RoutingNumber, PaymentType, Amount, CardNumber and Expiry. The response would include the Approval and TrackingNumber.

See the individual payment specifications (eg Card Payment Reference) for more details.

Sample Code for /submit

cURL

Live sample: To try it, paste the following into cURL and execute.
["UserName", "Timestamp", "RequestID", "PaymentType", "Amount", "Currency"]
curl https://raven.deepcovelabs.net/realtime/submit \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=1bb056101113034543d0847da74f39a3" \
  --data-urlencode "Timestamp=2016-09-09T14:01:25Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "RoutingNumber=840033" \
  --data-urlencode "PaymentType=cc_debit" \
  --data-urlencode "Currency=CAD" \
  --data-urlencode "Amount=1200" \
  --data-urlencode "CardNumber=4000000000000010" \
  --data-urlencode "Expiry=0918" \
  --data-urlencode "Signature=45c1aeeb88681abcb0c39fc857b0cfa5809cfbdf"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');

$request =  new Raven\Request('submit', array(
                                        "RoutingNumber"=>"840033",
                                        "PaymentType"=>"cc_debit",
                                        "Currency"=>"USD",
                                        "Amount"=>2000,
                                        "CardNumber"=>"4000000000000010",
                                        "ExpiryDate"=>"0919"));

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;
using System.Collections.Specialized;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("submit", new NameValueCollection
                    {
                        {"RoutingNumber","840033"},
                        {"PaymentType","cc_debit"},
                        {"Amount","1234"},
                        {"Currency","USD"},
                        {"CardNumber","4000000000000010"},
                        {"ExpiryDate","0919"},
                    });

var result = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;

RavenRequest request = new RavenRequest("submit");

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

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model
open System.Collections.Specialized

let rvnResponse (id:string)(secret:string)(request:Request) =   
    Raven(id,secret).Send(request)

let nvcData = new NameValueCollection()
nvcData.Add("RoutingNumber","840033")
nvcData.Add("PaymentType","cc_debit")
nvcData.Add("Amount","1234")
nvcData.Add("Currency","USD")
nvcData.Add("CardNumber","4000000000000010")
nvcData.Add("ExpiryDate","0919")

let response = rvnResponse "ernest" "all good men die young" (Request("submit", nvcData))

Complete

URL: https://raven.deepcovelabs.net/realtime/complete
Purpose: Complete the 3DS approval process.
Summary: Used to submit a follow-up payment request to RAVEN after customer-completed authentication with ACS.

Request Fields for /complete

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 M Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 M Any value unique for the UserName (a given user may never submit the same RequestID twice). This can be implemented using a UUID, GUID or even the machine name followed by a microsecond timestamp.
RoutingNumber N 6 M The six digit payment routing number assigned to you.
PaymentType T 25 M The same payment type as the original payment
Amount N 10 Req M
Currency A 3 M Same currency as the original payment.
Signature N 40 M SHA1 HMAC of the following values concatenated:
UserName
TimeStamp
RequestID
PaymentType
Amount
Currency
TrackingNumber N 10 M The tracking number that was received from RAVEN for the original request.
3DSPARes T 4096 M The Payer Authentication Response (PARes) that was received from the ACS. Note: this value must be URL-encoded to be transferred correctly.

Response Fields for /complete

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 M Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.

Static sample: Cannot be executed in cURL as is because it needs to be part of a live 3DS payment cycle.

Sample Code for /complete

cURL

Static sample: Cannot be executed in cURL as is because it needs to be part of a live 3DS payment cycle.
["UserName", "Timestamp", "RequestID"]
curl https://raven.deepcovelabs.net/realtime/complete \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=EUEtJlhwcCvxQLEB" \
  --data-urlencode "Timestamp=2016-09-09T14:01:24Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "RoutingNumber=840033" \
  --data-urlencode "PaymentType=cc_debit" \
  --data-urlencode "Currency=CAD" \
  --data-urlencode "Amount=1200" \
  --data-urlencode "TrackingNumber=2071236224" \
  --data-urlencode "3DSPARes={ value of PARes }" \
  --data-urlencode "Signature=0e4b36c9c65fc74476c166ea50a84d9b15f506de"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');
$request =  new Raven\Request('complete', array(
                                        "RoutingNumber"=>"987743",
                                        "PaymentType"=>"cc_debit",
                                        "Amount"=>2000,
                                        "Currency"=>"USD",
                                        "TrackingNumber"=>"2071236224",
                                        "3DSPARes"=>"{ value of PARes }"));

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;
using System.Collections.Specialized;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("complete", new NameValueCollection
                    {
                        {"RoutingNumber","840033"},
                        {"PaymentType","cc_debit"},
                        {"Amount","1234"},
                        {"Currency","USD"},
                        {"TrackingNumber","2071236224"},
                        {"3DSPARes","{ value of PARes }"},
                    });

var result = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;

RavenRequest request = new RavenRequest("complete");

request.set("RoutingNumber", "840033");
request.set("Currency", "USD");
request.set("CardNumber", "4000000000000010");
request.set("PaymentType", "cc_debit");
request.set("Amount", "2000");
request.set("3DSPARes", "{ Value of PARes }");

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model
open System.Collections.Specialized

let rvnResponse (id:string)(secret:string)(request:Request) =
    Raven(id,secret).Send(request)

let nvcData = new NameValueCollection()
nvcData.Add("RoutingNumber","840033")
nvcData.Add("PaymentType","cc_debit")
nvcData.Add("Amount","1234")
nvcData.Add("Currency","USD")
nvcData.Add("TrackingNumber","2071236224")
nvcData.Add("3DSPARes","{ value of PARes }")

let response = rvnResponse "ernest" "all good men die young" (Request("complete", nvcData))

Response

URL: https://raven.deepcovelabs.net/realtime/response Purpose: To enquire about a response from a previously sent payment request.

Request Fields for /response

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 M Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 M Not a new RequestID but rather the one that was used to submit the original payment.
Signature N 40 M SHA1 HMAC of the following values concatenated:
UserName,
TimeStamp,
RequestID

Response Fields for /response

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 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.

Sample Code for /response

cURL

Static sample: Cannot be executed in cURL as is because it needs a valid `RequestID`.
["UserName", "Timestamp", "RequestID"]
curl https://raven.deepcovelabs.net/realtime/response \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=EUEtJlhwcCvxQLEB" \
  --data-urlencode "Timestamp=2016-09-09T14:01:25Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "Signature=40b44707e6b0b0eda1b2d8b725e8d7305edaf25e"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');
$request =  new Raven\Request('response', array(
                                          "RequestID"=>"EUEtJlhwcCvxQLEB"));

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;
using System.Collections.Specialized;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("response", new NameValueCollection
                    {
                        {"RequestID","EUEtJlhwcCvxQLEB"},
                    });

var result = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;

RavenRequest request = new RavenRequest("response");

request.set("RequestID", "EUEtJlhwcCvxQLEB");

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model
open System.Collections.Specialized

let rvnResponse (id:string)(secret:string)(request:Request) =
    Raven(id,secret).Send(request)

let nvcData = new NameValueCollection()
nvcData.Add("RequestID","EUEtJlhwcCvxQLEB")

let response = rvnResponse "ernest" "all good men die young" (Request("response", nvcData))

Status

URL: https://raven.deepcovelabs.net/realtime/status
Purpose: To determine the current status of a payment.
Summary: Status endpoint allows 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.

Request Fields for /status

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 M Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 M Any value unique for the UserName (a given user may never submit the same RequestID twice). This can be implemented using a UUID, GUID or even the machine name followed by a microsecond timestamp.
Signature N 40 M SHA1 HMAC of the following values concatenated:
UserName
TimeStamp
RequestID
TrackingNumber N 10 M As returned by a payment or inquiry request. If no payment is found this field will be empty in the response.

Response Fields for /status

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 M Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.

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.

Sample Code for /status

cURL

Live sample: To try it paste the following into cURL and execute. You can also edit it to find the status of any payment submitted by user `ernest`.
["UserName", "Timestamp", "RequestID"]
curl https://raven.deepcovelabs.net/realtime/status \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=cedfd56923b3b40376fea10b7b17bc74" \
  --data-urlencode "Timestamp=2016-09-09T14:01:25Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "TrackingNumber=2071236224" \
  --data-urlencode "Signature=8a20f90c110d1412669c6a22a52089168a8d8129"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');
$request =  new Raven\Request('status', array(
                                        "TrackingNumber"=>"2071236224"));

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;
using System.Collections.Specialized;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("status", new NameValueCollection
                    {
                        {"TrackingNumber","2071236224"},
                    });

var result = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;

RavenRequest request = new RavenRequest("status");

request.set("TrackingNumber", "2071236224");

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model
open System.Collections.Specialized

let rvnResponse (id:string)(secret:string)(request:Request) =
    Raven(id,secret).Send(request)

let nvcData = new NameValueCollection()
nvcData.Add("TrackingNumber","2071236224")

let response = rvnResponse "ernest" "all good men die young" (Request("status", nvcData))

Void

URL: https://raven.deepcovelabs.net/realtime/void
Purpose: To void a payment that have not been submitted for further processing.

The window to void a payment may be very small, for example when the original request is submitted just prior to the cutoff.

Request Fields for /void

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 M Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 M Any value unique for the UserName (a given user may never submit the same RequestID twice). This can be implemented using a UUID, GUID or even the machine name followed by a microsecond timestamp.
Signature N 40 M SHA1 HMAC of the following values concatenated:
UserName
TimeStamp
RequestID
TrackingNumber
TrackingNumber N 10 M As returned by a payment or inquiry request. If no payment is found this field will be empty in the response.

Response Fields for /void

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 M Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.

Sample Code for /void

cURL

Static sample: Cannot be executed in cURL as is because it needs a tracking number that has not been voided.
["UserName", "Timestamp", "RequestID", "TrackingNumber"]
curl https://raven.deepcovelabs.net/realtime/void \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=dc1f106613a6e8faaf119a147b1c3aec" \
  --data-urlencode "Timestamp=2016-09-09T14:01:25Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "TrackingNumber=2071236224" \
  --data-urlencode "Signature=3d1da40a393ba990e612964d78aa0acb92ea839a"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');
$request =  new Raven\Request('void', array(
                                        "TrackingNumber"=>"2071236224"));

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;
using System.Collections.Specialized;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("void", new NameValueCollection
                    {
                        {"TrackingNumber","2071236224"},
                    });

var result = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;

RavenRequest request = new RavenRequest("void");

request.set("TrackingNumber", "2071236224");

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model
open System.Collections.Specialized

let rvnResponse (id:string)(secret:string)(request:Request) =
    Raven(id,secret).Send(request)

let nvcData = new NameValueCollection()
nvcData.Add("TrackingNumber","2071236224")

let response = rvnResponse "ernest" "all good men die young" (Request("void", nvcData))

Clearflags

URL: https://raven.deepcovelabs.net/realtime/clearflags
Purpose: To clear any flags preventing a payment from being settled.

Request Fields for /clearflags

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 M Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 M Any value unique for the UserName (a given user may never submit the same RequestID twice). This can be implemented using a UUID, GUID or even the machine name followed by a microsecond timestamp.
Signature N 40 M SHA1 HMAC of the following values concatenated:
UserName
TimeStamp
RequestID
TrackingNumber
TrackingNumber N 10 M As returned by a payment or inquiry request. If no payment is found this field will be empty in the response.

Response Fields for /clearflags

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 M Will be OK in normal cases, otherwise will be an error code as described in the table of HTTP status codes below.

Sample Code for /clearflags

cURL

Static sample: Cannot be executed in cURL as is because it needs a tracking number with flags.
["UserName", "Timestamp", "RequestID", "TrackingNumber"]
curl https://raven.deepcovelabs.net/realtime/clearflags \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=9370a7c6d925f198a8c5532dbca99b1f" \
  --data-urlencode "Timestamp=2016-09-09T14:01:24Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "TrackingNumber=2071236224" \
  --data-urlencode "Signature=eb00cbf812e2fed69768aacbbb33ac9765ec2e95"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');
$request =  new Raven\Request('clearflags', array(
                                        "TrackingNumber"=>"2071236224"));

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;
using System.Collections.Specialized;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("clearflags", new NameValueCollection
                    {
                        {"TrackingNumber","2071236224"},
                    });

var result = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;

RavenRequest request = new RavenRequest("clearflags");

request.set("TrackingNumber", "2071236224");

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model
open System.Collections.Specialized

let rvnResponse (id:string)(secret:string)(request:Request) =
    Raven(id,secret).Send(request)

let nvcData = new NameValueCollection()
nvcData.Add("TrackingNumber","2071236224")

let response = rvnResponse "ernest" "all good men die young" (Request("clearflags", nvcData))

Closefile

URL: https://raven.deepcovelabs.net/realtime/closefile
Purpose: To allow a payment file to be settled.

Request Fields for /closefile

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 M Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 M Any value unique for the UserName (a given user may never submit the same RequestID twice). This can be implemented using a UUID, GUID or even the machine name followed by a microsecond timestamp.
Signature N 40 M SHA1 HMAC of the following values concatenated:
UserName
TimeStamp
RequestID
Filename
Filename AN 150 O 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.

Response Fields for /closefile

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 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 M Status of the file after the operation, either: open or released

Sample Code for /closefile

cURL

Static sample: Cannot be executed as is because it needs an unreleased file.
["UserName", "Timestamp", "RequestID", "FileName"]
curl https://raven.deepcovelabs.net/realtime/closefile \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=a4eb4d6705677dcfd85dd9b131355378" \
  --data-urlencode "Timestamp=2016-09-09T14:01:24Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "FileName=myfile.csv" \
  --data-urlencode "Signature=8d6988cf8a10b343ef20360c94a744143c5e70ea"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');
$request =  new Raven\Request('closefile', array(
                                        "FileName"=>"myfile.csv"));

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;
using System.Collections.Specialized;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("closefile", new NameValueCollection
                    {
                        {"FileName","myfile.csv"},
                    });

var result = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;

RavenRequest request = new RavenRequest("closefile");

request.set("Filename", "myfile.csv");

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model
open System.Collections.Specialized

let rvnResponse (id:string)(secret:string)(request:Request) =
    Raven(id,secret).Send(request)

let nvcData = new NameValueCollection()
nvcData.Add("FileName","myfile.csv")

let response = rvnResponse "ernest" "all good men die young" (Request("closefile", nvcData))

Voidfile

URL: https://raven.deepcovelabs.net/realtime/voidfile
Purpose: To void a payment file and all its payments.

Request Fields for /voidfile

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 M Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 M Any value unique for the UserName (a given user may never submit the same RequestID twice). This can be implemented using a UUID, GUID or even the machine name followed by a microsecond timestamp.
Signature N 40 M SHA1 HMAC of the following values concatenated:
UserName
TimeStamp
RequestID
Filename
Filename AN 150 O The name of the file to be voided. The file must not yet be released. If an unreleased file with this name does not exist, an HTTP Status code 400 will result.

Response Fields for /voidfile

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 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 M Status of the file after the operation, either: open or voided

Sample Code for /voidfile

cURL

Live sample: Cannot be executed as is because it needs a file to void.
["UserName", "Timestamp", "RequestID", "FileName"]
curl https://raven.deepcovelabs.net/realtime/voidfile \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=8f1287d986f0f00c3e709f00da5d7704" \
  --data-urlencode "Timestamp=2016-09-09T14:01:25Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "FileName=myfile.csv" \
  --data-urlencode "Signature=3aae770cecdb6f2a305c81ff84f214880aa025b1"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');
$request =  new Raven\Request('voidfile', array(
                                        "TrackingNumber"=>"2071236224"));

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;
using System.Collections.Specialized;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("voidfile", new NameValueCollection
                    {
                        {"TrackingNumber","2071236224"},
                    });

var result = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;

RavenRequest request = new RavenRequest("voidfile");

request.set("TrackingNumber", "2071236224");

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model
open System.Collections.Specialized

let rvnResponse (id:string)(secret:string)(request:Request) =
    Raven(id,secret).Send(request)

let nvcData = new NameValueCollection()
nvcData.Add("TrackingNumber","2071236224")

let response = rvnResponse "ernest" "all good men die young" (Request("voidfile", nvcData))

Payments

URL: https://raven.deepcovelabs.net/realtime/payments
Purpose: To search for payments.

Request Fields for /payments

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 M Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 M Any value unique for the UserName (a given user may never submit the same RequestID twice). This can be implemented using a UUID, GUID or even the machine name followed by a microsecond timestamp.
Signature N 40 M SHA1 HMAC of the following values concatenated:
UserName
TimeStamp
RequestID
ReportFormat One of 50 M The following formats are supported:
RavenPaymentFile_v1.0
StartTime Timestamp 50 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 M Only payments created before this time will be returned.
ResultFields AN 500 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 payment type specifications.
Accounts AN 250 O A space separated list of Raven account numbers.
RoutingNumbers AN 250 O A space separated list of Raven payment routing numbers.
PaymentTypes AN 250 O A space separated list of Raven payment types.
TrackingNumbers AN 250 O A space separated list of payment tracking numbers.

Response Fields for /payments

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 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 M Number of records returned.
PaymentReport O A report in Raven result file format of the payments found. This will include those fields specified in ResultFields.

Sample Code for /payments

cURL

Live sample: To try it paste the following into cURL and execute. You can also edit it to find other payments submitted by user `ernest`.
["UserName", "Timestamp", "RequestID"]
curl https://raven.deepcovelabs.net/realtime/payments \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=d0fb41accefcad078d6eada9933a2c07" \
  --data-urlencode "Timestamp=2016-09-09T14:01:25Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "ReportFormat=RavenPaymentFile_v1.0" \
  --data-urlencode "StartTime=2016-01-26T16:22:09Z" \
  --data-urlencode "EndTime=2016-01-28T16:22:09Z" \
  --data-urlencode "ResultFields=TrackingNumber Status" \
  --data-urlencode "RoutingNumbers=840033" \
  --data-urlencode "Signature=01945ce1399d698f3154c281c78be86adb83dece"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');

$request =  new Raven\Request('payments', array(
                                        "ReportFormat"=>"RavenPaymentFile_v1.0",
                                        "StartTime"=>"2016-01-26T16:22:09Z",
                                        "EndTime"=>"2016-01-28T16:22:09Z",
                                        "ResultFields"=>"TrackingNumber Status"));

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;
using System.Collections.Specialized;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("payments", new NameValueCollection
                    {
                        {"ReportFormat","RavenPaymentFile_v1.0"},
                        {"StartTime","2016-01-26T16:22:09Z"},
                        {"EndTime","2016-01-28T16:22:09Z"},
                        {"ResultFields","TrackingNumber Status"},
                    });

var result = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;
import java.util.Calendar;
import java.util.GregorianCalendar;
import java.util.TimeZone;

// Default is past 30 days
Calendar endTime = new GregorianCalendar(TimeZone.getTimeZone("GMT"));
Calendar startTime = new GregorianCalendar(TimeZone.getTimeZone("GMT"));
startTime.add(Calendar.DAY_OF_MONTH,-30);

RavenRequest request = new RavenRequest("payments");

request.set("ReportFormat", "RavenPaymentFile_v1.0");
request.set("StartTime", timestampProvider.formatTimestamp(startTime.getTime()));
request.set("EndTime", timestampProvider.formatTimestamp(endTime.getTime()));
request.set("ResultFields", "PRN PymtType Amount Currency CardNumber ApprovalCode");

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model
open System.Collections.Specialized

let rvnResponse (id:string)(secret:string)(request:Request) =
    Raven(id,secret).Send(request)

let nvcData = new NameValueCollection()
nvcData.Add("ReportFormat","RavenPaymentFile_v1.0")
nvcData.Add("StartTime","2016-01-26T16:22:09Z")
nvcData.Add("EndTime","2016-01-28T16:22:09Z")
nvcData.Add("ResultFields","TrackingNumber Status")


let response = rvnResponse "ernest" "all good men die young" (Request("payments", nvcData))

Events

URL: https://raven.deepcovelabs.net/realtime/events
Purpose: To search for payments and their history.

Request Fields for /events

Field Names Type Max. Size O/C/M Remarks
RAPIVersion AN 10 M Must be 2.
UserName AN 50 M Your Raven user identity, as assigned.
Timestamp Timestamp 50 M Time at which the message was sent. Will be validated against UTC time if present.
RequestID AN 50 M Any value unique for the UserName (a given user may never submit the same RequestID twice). This can be implemented using a UUID, GUID or even the machine name followed by a microsecond timestamp.
Signature N 40 M SHA1 HMAC of the following values concatenated:
UserName
TimeStamp
RequestID
ReportFormat One of 50 M The following formats are supported:
RavenEventFile_v1.0
StartTime Timestamp 50 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 M Only payments created before this time will be returned.
ResultFields AN 500 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 payment type specifications.
Accounts AN 250 O A space separated list of Raven account numbers.
RoutingNumbers AN 250 O A space separated list of Raven payment routing numbers.
PaymentTypes AN 250 O A space separated list of Raven payment types.
PaymentEventTypes One of 100 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.

Response Fields for /events

Includes all fields from Request file, plus these additional fields:

Field Names Type Max. Size O/C/M Remarks
RequestResult AN 100 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 M Number of records returned.
PaymentEventReport 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.

Sample Code for /events

cURL

Live sample: To try it paste the following into cURL and execute.
["UserName", "Timestamp", "RequestID"]
curl https://raven.deepcovelabs.net/realtime/events \
  --data-urlencode "RAPIVersion=2" \
  --data-urlencode "RequestID=4d2b2020bf1fa19af258a0c96343172e" \
  --data-urlencode "Timestamp=2016-09-09T14:01:24Z" \
  --data-urlencode "UserName=ernest" \
  --data-urlencode "ReportFormat=RavenEventFile_v1.0" \
  --data-urlencode "StartTime=2016-01-26T16:22:09Z" \
  --data-urlencode "EndTime=2016-01-28T16:22:09Z" \
  --data-urlencode "ResultFields=TrackingNumber Status" \
  --data-urlencode "Signature=617eb3a27988fbecc8cd293c1919176c528daffe"

PHP

Our PHP SDK automatically signs requests for you.

require 'vendor/autoload.php';
use Raven\Raven;

$rvn = new Raven('ernest', 'all good men die young');
$request =  new Raven\Request('events', array(
                                        "ReportFormat"=>"RavenEventFile_v1.0",
                                        "StartTime"=>"2016-01-26T16:22:09Z",
                                        "EndTime"=>"2016-01-28T16:22:09Z",
                                        "ResultFields"=>"TrackingNumber Status"));

$result = $rvn->send($request);

C#

Our C# SDK automatically signs requests for you.

using RavenDotNet.Model;
using System.Collections.Specialized;

var rvn = new Raven("ernest", "all good men die young");

var request = new Request("events", new NameValueCollection
                    {
                        {"ReportFormat","RavenEventFile_v1.0"},
                        {"StartTime","2016-01-26T16:22:09Z"},
                        {"EndTime","2016-01-28T16:22:09Z"},
                        {"ResultFields","TrackingNumber Status"},
                    });

var result = rvn.Send(request);

Java

Our Java SDK automatically signs requests for you.

import com.deepcovelabs.Raven.api;
import java.util.Calendar;
import java.util.GregorianCalendar;
import java.util.TimeZone;

// Default is past 30 days
Calendar endTime = new GregorianCalendar(TimeZone.getTimeZone("GMT"));
Calendar startTime = new GregorianCalendar(TimeZone.getTimeZone("GMT"));
startTime.add(Calendar.DAY_OF_MONTH,-30);

RavenRequest request = new RavenRequest("events");

request.set("ReportFormat", "RavenEventFile_v1.0");
request.set("StartTime", timestampProvider.formatTimestamp(startTime.getTime()));
request.set("EndTime", timestampProvider.formatTimestamp(endTime.getTime()));
request.set("ResultFields", "PRN PymtType Amount Currency CardNumber ApprovalCode");

RavenResponse response = request.send();

F#

#r "./packages/RavenDotNet.2.4.0/lib/net45/RavenDotNet.dll"
open RavenDotNet
open RavenDotNet.Model
open System.Collections.Specialized

let rvnResponse (id:string)(secret:string)(request:Request) =
    Raven(id,secret).Send(request)

let nvcData = new NameValueCollection()
nvcData.Add("ReportFormat","RavenEventFile_v1.0")
nvcData.Add("StartTime","2016-01-26T16:22:09Z")
nvcData.Add("EndTime","2016-01-28T16:22:09Z")
nvcData.Add("ResultFields","TrackingNumber Status")


let response = rvnResponse "ernest" "all good men die young" (Request("events", nvcData))

Libraries

We recommend that you use our API libraries, since they eliminate many possible sources of integration error.

In particular, we find the most common mistake is calculating request signatures incorrectly. All of the libraries do this for you automatically prior to being sent to Raven, assuming all of the required parameters are set on the request object.

In the end, however the choice is yours. Feel free to:

  • Use Our Libraries - use the supplied libraries directly, if one exists for your language of choice
  • Customize Our Helpers - copy and modify the existing libraries (again, if one exists for your language) to accommodate your specific needs.
  • Roll Your Own - in whatever language you want, possibly using the existing libraries as templates/guides

PHP Library

See the source, and simple usage instructions on GitHub.

Java Library

See the source, and simple usage instructions on GitHub.

.NET Library

See the source, and simple usage instructions on GitHub.

Python Library

See the source, and simple usage instructions on GitHub.

iFrame

If you are interested in keeping your PCI DSS compliance scope low, then we recommend using the iframe payment integration method.

This is a beta product, please contact [email protected] to report any issues or ask any questions.

Key Features

  • The Raven iframe processes your customers’ payments without having their sensitive information ever touch your servers. It takes care of creating a payment form and securely passes the sensitive card data through the Raven servers. This lowers your compliance requirements since customer information will not be stored or transferred on your servers.

  • The Raven iframe fits into your existing payment page and includes only the payment fields. If you would like to collect additional information from your customers, you can create a master form with all remaining input fields.

  • The Raven iframe is responsive and was designed to blend in with your existing payment page's UI. We have provided you with options to customize variables in order to achieve your desired results.

How it Works

You can add the payment iframe to your form by including the following script tag anywhere in your form:

<form>
  <script async
    src="https://raven-cdn.deepcovelabs.com/iframe-v1/embed.js"
    data-key-id="id_6s5NqjV1uJE">
  </script>
  <button>Place Order</button>
</form>

The script will embed the iframe into your from. The iframe will render any fields and controls needed to securely collect the required card data. When the form is submitted, the iframe will insert a cyptographically secure value into your form as a hidden field called raven-token. This hidden field is submitted back to your server along with all the other fields in your form. You then need to supply the value of raven-token when making your Raven API authorization request.

We provide a few options to customize the look & feel of the iframe to better match up with the enclosing form's style:

<form>
  <script async
    src="https://raven-cdn.deepcovelabs.com/iframe-v1/embed.js"
    data-key-id="id_6s5NqjV1uJE"
    data-label-color="#000"
    data-background-color="#efebdf"
    data-parent-background-color="#f8f5ee"
    data-border-color="#e0d8ca">
  </script>
  <button>Place Order</button>
</form>

IFrame Reference

Attribute Mandatory Value Description
async Yes N/A https://css-tricks.com/thinking-async/
src Yes https://raven-cdn.deepcovelabs.com/iframe-v1/embed.js
data-key-id Yes id_XXXXXXX API Access Key ID
data-label-color No Hex color value
data-background-color No Hex color value
data-parent-background-color No Hex color value
data-border-color No Hex color value

IFrame Example

Here's a real example of a form collecting an email address along with payment information,

<form action="https://httpbin.org/post" method="post">

  <!-- you define whatever fields normally you would want customers to fill out -->
  <div class="form-group">
    <label for="input-name">Name:</label>
    <input class="form-control" id="input-name" placeholder="John Doe">
  </div>
  <div class="form-group">
    <label for="input-email">Email:</label>
    <input class="form-control" id="input-email" placeholder="[email protected]">
  </div>

  <!-- this adds an iframe in-line with the rest of the form -->
  <script async src="https://raven-cdn.deepcovelabs.com/iframe-v1/embed.js"
    data-key-id="id_6s5NqjV1uJE"></script>

  <!-- define a button to submit the form, we'll make sure to populate the 'raven-token'
       hidden field when form is submitted -->
  <button class="btn btn-primary">Place Order</button>

</form>

Content Security Policy and IFrame

If you deploy Content Security Policy for your checkout pages, you will need to allow the following sources,

  • script-src - https://raven-cdn.deepcovelabs.com
  • frame-src - https://raven-cdn.deepcovelabs.com
  • connect-src - https://raven.deepcovelabs.com

Secure Fields

Secure Fields is a security utility whose purpose is to simplify your PCI compliance requirements, without having you sacrifice control over the flow and presentation of your customer payment transactions. It is designed to be used in conjunction with the Raven API.

Secure fields provides the following benefits:

  1. Simplified PCI-Compliance

    Secure Fields prevents sensitive customer information from being handled by your servers. Information such as contact details and credit card numbers is automatically and transparently encrypted in the customer’s browser before being sent to your servers, along with clear-text fields such as currency and amount.

    Once passed onto Raven, which is PCI compliant and therefore allowed to handle sensitive information, contact details, card numbers and any other information marked by you as sensitive is un-encrypted and used along with the clear text data as part of the authorization of the transaction.

    Since all customer information declared by PCI to be sensitive is prevented from ever physically residing or even passing through your servers, those servers do not come under the mandate of PCI, and your infrastructure requirements are substantially lessened.

    Note that as of 2016 the PCI compliance requirements for Sercure Fields have jumped from an SAQ A to a SAQ A-EP.

  2. Customizable Look and Feel

    Since you are tasked with creating your own payment page, you can ensure that it matches the look of your website and your customer’s language preference.

Integrating Secure Fields into your Payment Page

Secure Fields is implemented as a javascript library called raven.js, available directly from our content servers. Secure Fields works by intercepting form submissions from your payment page and encrypting all fields declared by you to be holding sensitive information, before that information is submitted to Raven via your web server.

To use raven.js, you need to modify your payment page in the following ways:

  1. Include the raven.js library in your payment page via a script tag:

     <script src="https://raven.deepcovelabs.net/files/clients/raven.js" type="text/javascript" />
    
  2. Mark all fields to be encrypted by adding "class=encrypted" to their form elements:

    <input type="text" id="rapi-number" name="cardnumber" class="encrypted"/>
    
  3. Kick things off by calling the activate() function:

    <script type="application/javascript">
      raven.activate();
    </script>
    

Avoiding Additional CSS Classes

If for any reason you don't want to use CSS styles to annotate your sensitive fields, use raven.activate() and optionally pass the element ids of the fields to be encrypted, regardless of their class:

<input type="text" id="rapi-number" name="cardnumber"/>

<script type="application/javascript">
  raven.activate('rapi-number');
</script>

Testing Secure Fields

Once you have your payment page operational and are getting successful responses back, open a browser web development tool and examine the details of a typical POST.

As illustrated below, you should see that the fields you annotated to be sensitive will have encrypted values that only Raven can understand.

Screenshot of Secure Fields Encrypted POST Data

3-D Secure

Raven supports 3-D Secure (3DS) for real-time authorizations of credit card payments, and is available for both Visa and MasterCard. Visa refers to it as Verified by Visa and MasterCard refers to it as SecureCode.

With 3DS, a card holder's issuing bank is inserted directly into the middle of the payment process, between your payment request to Raven and Raven's request for approval. In between these two events, card holders are required to directly authenticate themselves to the bank which issued them their card.

Three Step, Three Party Process

3-D Secure verification requires a three step interaction between your server, Raven, and a cardholder's issuing bank:

  1. Initiation

    Your server first submits a payment request to Raven, indicating 3DS is required and providing several 3DS-specific parameters. If 3DS is not available, Raven automatically performs an approval request to which the 3DS guarantees do not apply.

  2. Authentication

    If 3DS is available, Raven returns with:

    • the URL of the issuing bank's Access Control System (ACS), to which your customer must be directed in order to authenticate themselves
    • a payment authentication request (PAReq) that must be passed to the ACS.
  3. Approval

    Assuming 3DS is available, the issuing bank returns a payment authentication response (PARes) to your server which must then be passed on to Raven for verification, along with details of the original request.

    • If authentication response is valid, Raven will indicate 3DS has Passed and perform an approval request.
    • If the authentication response is not valid, Raven will indicate 3DS has Failed and respond with Declined for the approval.
    • If at this late stage the 3DS system is unavailable and the response cannot be verified, Raven will once again automatically perform an approval request to which the 3-D Secure guarantees do not apply.

Initiation

Submit your authorization requests to Raven with the following fields set:

  • 3DSVerify - set to true, telling Raven to invoke 3DS
  • 3DSMerchantURL - your website URL to which control should be passed in step 2
  • 3DSDeviceCategoryCode - mobile or desktop
  • 3DSBrowserAcceptheader - the MIME types accepted
  • 3DSBrowserUserAgentHeader - User agent

3DS Applicability

Just asking for 3DS is not sufficient for it to be applied to your transactions. In order for a transaction to take advantage of 3DS, Raven checks that the following conditions exist:

  • the card is either enrolled or that it may be enrolled on the fly
  • the 3DS system is available
  • you (as determined by your merchant ID) are participating in 3DS (configured by Raven)

3DS Unavailable

If 3-D Secure cannot be invoked, Raven will immediately make an approval request just as if no 3DS processing had been requested. The value of 3DSResponseCode will indicate the reason why 3-D Secure could not be invoked.

3DS Available

If 3DS is available, Raven does not proceed with authorization, but instead populates the payment response with the URL of the issuing bank’s Access Control Server (ACS) in the 3DSACSURL field, as well as a payer authentication request (PAReq) in the 3DSPAReq field.

Raven then returns a normal Raven response. If 3-D Secure processing can proceed, the payment has a status of Pending3DS and the 3DSResponseCode has a value of Attempted. The response values include the 3DSACSURL and the the 3DSPAReq fields with the values needed for step 2. If 3-D Secure processing is not possible, the payment has a status of Approved or one of the standard payment processing status's indicating a declined transaction.

3DS Specification

Click here for the complete 3DS specification.

For any other value of 3DSResponseCode, no 3-D Secure authentication has taken place and no liability shift has occurred. If you do not want to proceed without a 3-D Secure guarantee, you must ensure transactions without a 3DSResponseCode of Passed are not settled.

Authentication

If 3-D Secure can be invoked (payment status code Pending3DS), the payment authentication request (PAReq) returned by Raven in step 1 must be submitted to the Access Control System through the cardholder's browser/device using an HTML element.

The cardholder is in turn presented with their issuing bank's interface for enrollment or password validation.

This request must come from the cardholder's computer, not from the merchant's server. This form must use POST method and contain the following elements:

Element Name Content
Target acsframe Value of 3DSACSURL from Raven's response in Step 1.
Hidden field PaReq Value of 3DSPAReq from Raven's response in Step 1.
Hidden field TermUrl URL to direct customer to after the interaction with ACS.
Hidden field MD Merchant data field which contains a unique transaction reference. This must allow the merchant to find the original request in their system.

Here's an example of code that could be used to present the ACS frame to the customer:

<form name="acsform" method="post" target="acsframe" action="{Value of 3DSACSURL}">
    <input type="hidden" name="PaReq" value="{Value of 3DSPAReq}"/>
    <input type="hidden" name="TermUrl" value="{redirect URL}"/>
    <input type="hidden" name="MD" value="{Merchant's unique ref}"/>
    <iframe name="acsframe" width="750" height="600"></iframe>
    <script type="text/javascript">
        document.acsform.submit();
    </script>
</form>

The JavaScript code or something similar is essential to the way 3-D Secure works. The customer must be redirected from their own browser window to the location specified in the 3DSACSURL field.

After the customer is authenticated by their bank, the ACS displays a page that causes the browser to automatically POST the following fields to the URL you supplied in the TermURL hidden field.

Name Content
PARes Payor authorization response generated by the ACS.
MD Merchant data field which contains a unique transaction reference. This must allow the merchant to find the original request in their system.

Approval

Once the ACS has returned control to your server, you again use the MD reference number to fetch your record of the original transaction and resubmit the authorization request to Raven.

This follow-up transaction must be submitted to the Complete 3DS Payment Endpoint:

  • The resubmitted authorization request must have the 3DSPARes field set to the value of the PARes received from the ACS.
  • The TrackingNumber field must be set to the value of TrackingNumber received from Raven in Step 1.

In processing the resubmitted authorization request, Raven verifies the ACS signature on the PARes and parses the response.

  • If the response is not valid, the 3DSResponseCode is set to Failed and the payment is declined.
  • If the response is valid, the 3DSResponseCode is set to Passed.
  • If the 3DS system is not available the 3DSRespsonseCode is set to Unavailable.

In both the case of 3DSResponseCode being Passed and Unavailable an approval request is made. The result is returned using the response field named Status, just as in the non 3-D Secure case.

Clean-up

Any payments that remain in status ThreedPending for over 24 hours are marked as Void and the 3DSResponseCode is set to Abandoned.

3DS Testing

3DS can only be tested using real cards against a live (non-test) routing. If 3DS is requested against a routing configured for testing, the 3DS window will not appear.

Hosted Payment Page

Hosted Payment Page (HPP) solutions are designed to simplify your PCI compliance.

HPP never gives initiating websites access to sensitive cardholder data, thereby ensuring that those websites are not brought into scope for PCI purposes. HPP is an ideal solution if you:

  • do not have a secure server. want to avoid the risks involved with accepting sensitive credit card information on their own servers.
  • have not yet been certified PCI compliant and who want to assure that they are not inadvertently exposing their customers' credit card details to a third party.
  • wish to sell their products to international markets without investing heavily in website localization or establishing accounts with foreign banks.

There are two hosted payment page options:

  • MarketDirect is a hosted payment page hosted by Raven.

  • SecurePay is a payment page hosted by UnionPay International.

MarketDirect

MarketDirect is a semi-customizable payment page hosted by us that can be integrated into your existing website. Unlike Secure Fields, MarketDirect offers minimal customization opportunities.

Workflow

The following is a typical interaction using MarketDirect:

  1. Prepare Your Environment

    Assuming that you are integrating MarketDirect using the PHP scripting language, you can download the PHP MarketDirect Helper to simplify your integration effort. Place it within your normal script directory on your webserver. If you are using any other language, you will need to code manually using field information provided in the MarketDirect Fields section.

    Required credentials
    Our recommended API Libraries

    Modify your site to include an HTML form that, when POSTed, supplies Raven with all the information it needs to process a payment.

    Create your form Tailor your form

  2. Customer "Buys" on Your Site

    Customer uses your website to determine their order and initiates a payment transaction by pressing a "Buy" button that you have integrated to MarketDirect. The button controls how MarketDirect will look.

  3. Customer Redirected to MarketDirect Payment Page

    The customer's browser redirects them transparently to a secure payment page hosted on Raven servers for the collection of credit card details.

    • The page is optionally customized with your company's look and feel.
  4. Raven Processes Payment

    The payment page transmits the transaction data securely to our banking system for approval.

  5. Raven Communicates Result

    To complete the order process, Raven can do one or both of the following:

    • Communicates the transaction result back to your server so that the order can be fulfilled (see md_fulfillment_url request field)
      Notify Fulfillment Center
    • Redirects the user back to your site (see md_result_url request field) where a script or program at the URL can then be used to create a custom receipt page from the transaction information. The custom receipt page is then displayed to the customer's browser.
      Handling Results

Create MarketDirect Form

Consult the MarketDirect Specification for the complete listing and detailed description of MarketDirect fields, including those used to invoke the various Raven Card Payment processing options, such as fraud scoring and address verification.

The following template code creates a form suitable for handling simple credit card payments (other more complex examples are shown at the bottom of this page):

<?php include_once('/tools/md.php')?>

<form action="https://raven.deepcovelabs.com/payment" method="post">
    <?php mdGenerateInputs(array(
        'md_submitter' => 'ernest',
        'md_shared_secret' => 'ernest',
        'md_routing' => '840033',
        'md_currency' => $currency,
        'md_amount' => $amount
    ))?>
    <input type="image" src="/images/buynow.gif"/>
</form>

Using your text editor or website designer, edit your order page (or create one if none exists) and paste in the template code shown above.

MarketDirect Form Explained

The first line makes the MarketDirect Helper available to your order page:

<?php include_once('/tools/md.php')?>

The form action references Raven's production payment URL by which payment requests are submitted, by way of HTML POSTs:

<form action="https://raven.deepcovelabs.com/payment" method="post">

The MarketDirect Helper creates the hidden fields required by Raven to identify and authenticate your company, as well as describe the details of the payment:

<?php mdGenerateInputs(array(
    'md_submitter' => 'ernest',
    'md_shared_secret' => 'ernest',
    'md_routing' => '840033',
    'md_currency' => $currency,
    'md_amount' => $amount
))?>

The fields are hidden since they contain nothing of interest to the customer. The shared secret is only used to calculate a signature, by which Raven verifies your identity, it is not included in the form and so cannot be seen if a customer inspects the source of your payment page.

Tailor Your Form

With the template code integrated into your site, you must modify it so that it properly identifies and authenticates your company as the source of the payment.

Change the included path of the MarketDirect Helper to point to the directory into which it was downloaded:

<?php include_once('/yourtoolsdirectorypath/md.php')?>

Now substitute in your credentials for submitter, shared secret and routing:

<?php mdGenerateInputs(array(
    'md_submitter' => 'your username',
    'md_shared_secret' => 'your shared secret',
    'md_routing' => 'your PRN',
    'md_currency' => $currency,
    'md_amount' => $amount
))?>

The amount and possibly the currency need to be variables that represent the values of a current payment. You will need to ensure that your order page makes these available to the payment page.

If you are using a separate payment page, and have your order page forward your customer to your new payment page, passing in the amount and currency of the purchase as part of your query string, then you can use the following code to populate the variables shown in the template:

<?
    $amount = $_GET["amount"];
    $currency = $_GET["currency"];
?>

Calculated Fields - A Good Reason to Use the Helper

Use the MarketDirect Helper to include required fields automatically. For example:

  • md_timestamp - the time of the payment transaction
  • md_reference - a unique reference by which to identify this payment transaction
  • md_signature - a digital signature by which Raven verifies the source of the payment

If you do not use the helper, you will need to calculate these fields yourself. In particular, the signature field is not trivial to compute. Consult the the API Guide for complete details.

Customizing the Look and Feel

When using the hosted payment form, several request fields can be used to configure the payment page to match the look of your website more closely and your customer's language preference.

Consult the MarketDirect Specification for the complete listing and explanation of look-and-feel fields.

Providing a Transaction Breakdown

Although the configuration parameters included in previous sections are sufficient to request the Hosted Payment Page form, additional fields can be supplied to the POST to provide customers with a detailed breakdown of the total that is being charged.

The md_amount field must be reconciled with the line items. It must contain the gross amount after tax, and (where appropriate) shipping and discounts.

A tolerance of one minor currency unit per line item is allowed.

When integrating with a shopping cart that may contain one or more items, you can supply label/cost/quantity of each line item by providing triplets of:

    md_detail_label_1/md_detail_cost_1/md_detail_qty_1,
    md_detail_label_2/md_detail_cost_2/md_detail_qty_2, ...

Consult the MarketDirect Specification for the complete listing and explanation of transaction breakdown fields.

Gathering Contact Information

If md_collect_contact_information is used, MarketDirect presents the customer with a form that they must fill out before proceeding with the payment. These fields are then returned back to you via mechanisms described in the Reporting section of this reference.

Consult the MarketDirect Specification for the complete listing and explanation of contact information gathering fields.

The Form in Final Form (pardon the pun)

The resulting HTML form produced by the code above should look something like this (try and view source on your browser page to check):

<form action="https://raven.deepcovelabs.com/payment" method="post">
    <input type="hidden" name="md_submitter" value="ernest"/>
    <input type="hidden" name="md_routing" value="840033"/>
    <input type="hidden" name="md_currency" value="USD"/>
    <input type="hidden" name="md_amount" value="1999"/>
    <input type="hidden" name="md_timestamp" value="2013-02-27T02:18:35Z"/>
    <input type="hidden" name="md_reference" value="75a62ff8d824b3ca8728cbe6ed618ca2"/>
    <input type="hidden" name="md_signature" value="D37F33C50294382B1F64E577CEA6FCF8"/>
    <input src="/images/buynow.gif" type="image" />
</form>

The above form is approximately what you would need to produce by hand, if you aren't using PHP, or if you are but don't want to use our helper.

Consult the MarketDirect Specification for the complete specification of MarketDirect fields, including those used to invoke the various Raven Card Payment processing options such as fraud scoring and address verification.

Fulfillment Center Integration

We provide a separate option to send additional notification to a third-party fulfillment center (see md_fulfillment_url in the MarketDirect Specification) on transaction completion.

Handling Results

You have two options when it comes to handling results:

  1. Let us automatically take care of communicating results back to the customer
  2. Provide your own response/receipt page.

    Should you wish to take over this responsibility, we provide an option to redirect your customers back to your site (see md_result_url in the MarketDirect Specification). Typically in this scenario, a script or program at the URL you specify creates a custom receipt page from the transaction response that Raven provides.

If you use an SSL (https://) address to specify the location of a callback and are experiencing issues receiving requests from our servers, please make note of the following caveats:

  • The web server must present a valid certificate issued by a trusted CA
    • We use Mozilla's trusted CAs listing: http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt?raw=1
  • The web server must present properly-ordered collection of intermediate certificates to link the site's certificate to its CA, if applicable.
    • You could use an external tool like SSL Checker to validate this: www.sslshopper.com/ssl-checker.html
  • The web server must present a certificate with a subject matching the domain of the callback's URL.
    • We do not support X.509 Subject Alternative Name extensions (http://tools.ietf.org/html/rfc3280#section-4.2.1.7)

Examples

There are various ways you can integrate MarketDirect into your existing website.

Click the sample button at the end of each description to try it out.

Basic Button

This creates a payment button to process a payment with default options.

<?php include_once('md.php')?>
<form action="https://raven.deepcovelabs.com/payment" method="post">
<?php mdGenerateInputs(array(
  'md_submitter' => 'ernest',
    'md_shared_secret' => 'ernest',
    'md_routing' => '840033',
    'md_currency' => 'USD',
    'md_amount' => '1999'))?>
    <input type="image" src="/images/buynow.gif"/>
</form>


Customized Button

This creates a payment button to process a payment without collecting shipping or billing information. It also configures the payment page with a unique color, logo and merchant URL.

<?php include_once('md.php')?>
<form action="https://raven.deepcovelabs.com/payment" accept-charset="UNKNOWN" enctype="application/x-www-form-urlencoded" method="post">
<php mdGenerateInputs(array(
    'md_submitter' => 'ernest',
    'md_shared_secret' => 'all good men die young',
    'md_routing' => '840033',
    'md_currency' => 'CAD',
    'md_amount' => '2000',
    'md_collect_shipping' => 'no',
    'md_collect_billing' => 'none',
    'md_collect_email' => 'no',
    'md_color' => '#480073',
    'md_logo_url' => 'https://docs.deepcovelabs.com/images/marketdirect/logo.gif',
    'md_return_url' => 'https://docs.deepcovelabs.com/card/#article-card-marketdirect-examples'))?>
<input type="image" src="/images/buynow.gif"/>
</form>


Complex Settlement Button

This is the most complicated example, specifically designed to make use of many possible display and result handling options.

<?php include_once('md.php')?>
<form action="https://raven.deepcovelabs.com/payment" accept-charset="UNKNOWN" enctype="application/x-www-form-urlencoded" method="post">
<?php mdGenerateInputs(array(
    'md_submitter' => 'ernest',
    'md_shared_secret' => 'all good men die young',
    'md_routing' => '840033',
    'md_currency' => 'USD',
    'md_amount' => '6232',
    'md_collect_billing' => 'full',
    'md_collect_shipping' => 'yes',
    'md_collect_email' => 'yes',
    'md_email_receipt' => 'no',
    'md_color' => '#480073',
    'md_logo_url' => 'https://docs.deepcovelabs.com/images/marketdirect/logo.gif',
    'md_language' => 'en',
    'md_return_url' => 'https://docs.deepcovelabs.com/card/#article-card-marketdirect-examples',
    'md_detail_item_1' => 'Wine Opener',
    'md_detail_cost_1' => '1999',
    'md_detail_qty_1' => '1',
    'md_detail_item_2' => 'Wine Glass',
    'md_detail_cost_2' => '1095',
    'md_detail_qty_2' => '2',
    'md_detail_extras' => '230',
    'md_detail_shipping' => '1000',
    'md_detail_taxes' => '813',
    'md_contact_email' => [email protected]',
    'md_shipping_name' => 'Ernest Gallo',
    'md_shipping_company' => 'Senoma Wines',
    'md_shipping_phone' => '+1 (604) 987-6543',
    'md_shipping_fax' => '+1 (604) 987-6543',
    'md_shipping_address1' => 'Unit 405, 595 Howe Street',
    'md_shipping_city' => 'Vancouver',
    'md_shipping_state' => 'British Columbia',
    'md_shipping_country' => 'CA',
    'md_shipping_zip' => 'V6C 2T5'))?>
                <input type="image" src="/images/buynow.gif"/>
</form>


Fields

To display the hosted payment form to a customer, a payment form request needs to be submitted via an HTML form POST with hidden fields. The following table describes the minimum fields required for requesting the hosted payment form.

Field Type Max Dflt Req Rsp Remarks
md_submitter String 50 M M Submitter ID assigned to you.
md_routing Integer 6 M M 6-digit payment routing number assigned to you.
md_currency String M M 3-character ISO currency code (e.g. USD, GBP, JPY etc)
md_amount Integer 25 M M Total that should be charged in base units of currency, with no decimal or thousands separator, i.e. $1,307.99 should be 130799.
md_reference String 50 M1,2 M Unique reference identifying this payment. New requests using duplicate reference value will result in an error if the request with original reference has been completed by the customer.
md_reference2 String 50 O O Additional reference that will be echoed back to the merchant, but will not affect processing.
md_reference3 String 50 O O Additional reference that will be echoed back to the merchant, but will not affect processing.
md_timestamp Timestamp M1 M Current universal time in UTC formatted as 'YYYY-MM-DDThh:mm:ssTZD'. Merchant server's system clock must be set to the proper time and time zone.
md_signature String 40 M1 M Hash of merchant and transaction specific information used to generate unique transaction fingerprint. Payment page uses the same mutually exclusive merchant information to decrypt the transaction fingerprint and authenticate the transaction. See the 'Signature' section at the bottom of this page for more detail.
md_collect_shipping5 Yes / No / display Yes2 O N Option indicating whether or not we should collect or display shipping information on your behalf:
Yes - collect full shipping details
No - do not collect any information
Display - display provided shipping details as read-only text.
md_collect_billing5 Full / Short / None / Display None2 O N Option indicating how much, if any, billing information we should collect or display on your behalf:
Full - collect full details for advanced fraud scoring
Short - only collect billing country for basic fraud scoring
None - do not collect any information; this will disable address based fraud scoring for this transaction
Display - display billing details provided as read-only text and use them for advanced fraud scoring
md_collect_email Yes / No / Display Yes2 O N Flag indicating whether or not we should collect the customer's email address on your behalf.
md_prefer_3ds Yes / No Yes4 O N Flag indicating whether we should attempt to authenticate customers using 3-D Secure, if their card scheme supports it for e-commerce transactions.
md_use_conversion Yes / No Yes3 O N Flag indicating whether or not dynamic currency conversion should be enabled.
md_payment_type preauth / debit debit O N Option indication the type of payment to be initiated by the customer, preauth -  only process authorization, settlement must be performed separately by the merchant debit - default type of transaction, which debits customer's card and credits the merchant
  1. This field can be omitted when using helper functions (i.e. mdGenerateInputs for PHP).

  2. If you do not provide your own md_reference for this transaction and decide to disable collection of shipping information, billing information or email address, you may not be able to identify the customer performing this transaction once approval is acquired.

  3. If your routing is only set up to process payments in a single currency or up-to-date exchange rates are not available, dynamic currency conversion will be disabled, regardless of this setting.

  4. Even if you opt out of 3D-Secure authentication, it will take place regardless in cases where card scheme mandates its use for e-commerce transactions (i.e. MaestroÆ).

  5. These fields were previously known as md_collect_shipping or md_collect_contact_information and both can still be used for backward-compatibility, but they do not provide as much flexibility as the new parameters.

MD Reporting Fields

In addition to the secure payment form, we also take care of communicating results back to the customer. Should merchants wish to take over that responsibility, we provide an option to redirect the user back to merchant site (see md_result_url). A script or program at the URL can then be used to create a custom receipt page from the transaction information.The custom receipt page is then displayed to the customer’s browser. The transaction response that is returned to the merchant from the payment gateway is a set of fields that provides information about the status of a transaction—whether it was accepted or declined—as well as information included in the transaction request.

We also provide a separate option to send additional notification to a third-party fulfillment center (see md_fulfillment_url) on transaction completion.

Field Type Max Dflt Req Rsp Remarks
md_fulfillment_url URL O N URL to which we will silently echo the transaction result; does not have to be SSL-secured as no sensitive data is transmitted back. Note: A fulfillment response will not follow 3XX redirects for security reasons.
md_retry_fulfillment_ notification Yes/No No O N Our system can retry failed callback notifications against the address specified in md_fulfillment_url up to 5 times with an interval of at least 2 minutes between each attempt (number of retries and retry interval are subject to change without notice). Only HTTP 2XX response code is considered a success, all other network errors or HTTP responses will be considered failures. Your system must ensure that duplicate order notifications aren't fulfilled more than once. Important: In order to preserve backwards-compatibility for existing clients the default value of this field is "No", but we strongly encourage new integrations needing to make use of md_fulfillment_url to make use of this retry mechanism by setting this field to "Yes".
md_fulfillment_post Yes/No Yes O N Gateway can provide key-value fields back to the processing URL via either POST (Yes) or GET (No).
md_always_notify_ fulfillment Yes/No No O N By default, MarketDirect will only notify md_fulfillment_url for approved payments that didn't trigger fraud screening threshold. When this option is set to "Yes", MarketDirect will notify md_fulfillment_url regardless of the status of a response.
md_result_url URL O N URL to which we will redirect the customer, bypassing our own result page; does not have to be SSL-secured as no sensitive data is transmitted back.
md_result_post Yes/No Yes O N Gateway can provide key-value fields back to the processing URL via either POST (Yes) or GET (No).Important: we strongly recommend using GET ("No" value in this field) to receive control of a result page to avoid potential issues with browsers warning customers about non-secured content if your md_result_url does not use SSL encryption.
md_email_receipt Yes/No Yes4 O N Flag indicating whether or not we will automatically email customer transaction receipt. Should merchants wish to use this option, the receipt email will contain information about the merchant and the status of a transaction as well as information included in the transaction request.
md_email_from Email O N Email address monitored by merchant from which receipt emails will be sent by the system. If not provided, default of [email protected] will be used.
md_tracking_number Integer 10 N M Unique number identifying this transaction.
md_approval_code String 50 N M Approval code issued by the holding bank, if approved.
md_approval_status String 50 N M WIP
md_cv2_status Code 50 N M WIP
md_card_scheme Code 2 N M WIP
md_avs_address_ status Code 25 N M WIP
md_flagged_for_ review Yes/No N O Field indicating that certain flagging conditions had been triggered for this payment.

If you use SSL (https://) address to specify the location of a callback and are experiencing issues receiving requests from our servers, please make note of the following caveats,

  • The web server must present a valid certificate issued by a trusted CA (we use Mozilla’s trusted CAs listing: http://mxr.mozilla.org/mozilla/source/security/nss/lib/ckfw/builtins/certdata.txt?raw=1)
  • The web server must present properly ordered collection of intermediate certificates to link the site’s certificate to its CA, if applicable (you could use an external tool like SSL Checker to validate this: www.sslshopper.com/ssl-checker.html)
  • The web server must present a certificate with a subject matching the domain of the callback’s URL, we do not support X.509 Subject Alternative Name extensions (http://tools.ietf.org/html/rfc3280#section-4.2.1.7)

MD Look and Feel Fields

When using the hosted payment form, the following fields can be configured to match the look of the merchant's website and customer's language preference.

Field Type Max. Size Dflt Req Rsp Remarks
md_title String 50 Payee Name O N Text to display in the page header as well as page title in the browser.
md_color RGB Hex 7 #206D82 O N Color value that matches merchant's site design, we will use this to adjust the color scheme of a payment page.
md_logo_path1 String Payee Name O N Local path to an image (jpg, jpeg, jpe, png and gif files are supported) that will be displayed in the header. Recommended size is 150px by 100px.
md_logo_url URL Payee Name O N URL of an image that will be displayed in the header. If your image is hosted securely with SSL (i.e. with SSLpic), this is recommended, if not, md_logo_path is a better way of ensuring that users aren't presented with a security warning when visiting the payment page. Recommended size is 150px by 100px.
md_logo_image String O N If SSL image hosting service if not available, this field can be used to provide the copy of the image itself as mime-type, followed by comma, followed by base64-encoded bytes of an image file; for example,image/gif,R0lGODlhAQA=
md_language deenesfrpt en2 O N Language in which the payment page should be displayed to the customer.
md_return_url URL 2 HTTP referrer O3 N Merchant site URL to be used in links throughout the payment process.
md_google_analytics String O N Google Analytics account number.
  1. This field is only available when using helper functions (i.e. mdGenerateInputs for PHP).

  2. If you do not provide md_language preference, we will attempt to determine the customer's regional preferences automatically and fallback to **en.

  3. If you do not provide **md_return_url and we cannot determine HTTP referrer, customers will have no way of navigating back to your site thus reducing their chances of follow-up transactions.

Transaction Breakdown Fields

Although the configuration parameters included in previous sections are sufficient to request the hosted payment form, additional fields can be submitted with the HTML form POST to provide customers with a detailed breakdown of the total that is being charged. Please bear in mind that the md_amount field must be reconciled with the line items. The md_amount field should contain the gross amount, after tax, and (where appropriate) shipping and discounts. In order to compensate for rounding errors, a tolerance of one minor currency unit per line item element is allowed.

When integrating with a shopping cart that may contain one or more items, merchants can supply label/cost/quantity of each line item by providing triplets of:

md_detail_label_1/md_detail_cost_1/md_detail_qty_1,

md_detail_label_2/md_detail_cost_2/md_detail_qty_2

etcetera.

Field Type Max. Size Dflt Req Rsp Remarks
md_detail_item_[i] String 25 O N Label of each item by index.
md_detail_cost_[i] Integer 25 O N Cost of each item by index; see md_amount for formatting.
md_detail_qty_[i] Integer 25 1 O N Quantity of each item by index, no fractions.
md_detail_extras Integer 25 O N Additional charges portion of grand total; see md_amount for formatting.
md_detail_shipping Integer 25 O N Shipping charges portion of grand total; see md_amount for formatting.
md_detail_taxes Integer 25 O N Tax portion of grand total; see md_amount for formatting.

MD Contact Info Fields

The possible CVV2 responses:

If md_collect_contact_information is used, the hosted payment page will present the customer with a form that they must fill out before proceeding with the payment. These fields are then returned back to merchant via mechanisms described in the Reporting section of this reference.

Field Type Max. Size Dflt Req Rsp Remarks
md_contact_email String 50 O C
md_shipping_name String 50 O C
md_shipping_company String 50 O C
md_shipping_phone String 50 O C
md_shipping_fax String 50 O C
md_shipping_address[i] String 50 O C Up to 3 address lines.
md_shipping_city String 50 O C
md_shipping_state String 50 O C
md_shipping_postal String 50 O C
md_shipping_country ISO Alpha 2 2 O C ISO 3166-1-alpha-2 code
md_billing_name String 50 O C
md_billing_company String 50 O C
md_billing_phone String 50 O C
md_billing_fax String 50 O C
md_billing_address 1-3 String 50 O C Up to 3 address lines.
md_billing_city String 50 O C
md_billing_state String 50 O C
md_billing_postal String 50 O C
md_billing_country ISO Alpha 2 50 O C ISO 3166-1-alpha-2 code

SecurePay

SecurePay is a payment page hosted by UnionPay International (UPI, formerly China UnionPay). SecurePay may be used to make credit card and debit card payments against UPI branded cards.

Unlike MarketDirect or SecureFields, SecurePay offers no customization.

Workflow

The following is a typical interaction using SecurePay:

  1. Prepare Your Environment

    Assuming that you are integrating SecurePay using the PHP scripting language, you can download the PHP Helper to simplify your integration effort. Place it within your normal script directory on your webserver.

    Required credentials
    Our recommended API Libraries

    Modify your site to include an HTML form that, when POSTed, supplies UnionPay with all the information it needs to process a payment.

    Create your form

  2. Customer "Buys" on Your Site

    Customer uses your website to determine their order and initiates a payment transaction by pressing a "Buy" button that you have integrated to SecurePay. Unlike MarketDirect, the button has no control over how SecurePay will look.

  3. Customer Redirected to SecurePay Payment Page

    The customer's browser redirects them to SecurePay hosted on UnionPay servers for the collection of credit card details.

    An SMS verification code is sent to the cell phone associated with the customer's card number.

  4. UnionPay Processes Payment

    The payment page transmits the transaction data securely to UnionPays banking system for approval.

  5. UnionPay Communicates Result

    To complete the order process, UnionPay redirects the user back to your site where a script or program at the URL can then be used to create a custom receipt page from the transaction information. The custom receipt page is then displayed to the customer's browser.
    'resultredirecturl' => 'https://wgs.rustycog.com/result.php'

    Unlike MarketDirect, automatic notification of fulfillment is not an option.

Create SecurePay Form

The following template code creates a form suitable for handling simple credit card payments (other more complex examples are shown at the bottom of this page):

<?php include_once('/tools/md.php')?>

<form action="https://raven.deepcovelabs.com/payment" method="post">
    <?php mdGenerateInputs(array(
    'username' => 'senoma.test',
    'sharedsecret' => 'kool aid tastes great',
    'routingnumber' => '508754',
    'currency' => 'CNY',
    'amount' => 100,
    'resultredirecturl' => 'https://wgs.rustycog.com/result.php'
    ))?>
    <input type="image" src="/images/buynow.gif"/>
</form>

Using your text editor or website designer, edit your order page (or create one if none exists) and paste in the template code shown above.

SecurePay Form Explained

The first line makes the SecurePay Helper available to your order page:

<?php include_once('/tools/md.php')?>

The form action references Raven's production payment URL by which payment requests are submitted, by way of HTML POSTs:

<form action="https://raven.deepcovelabs.com/payment" method="post">

The SecurePay Helper creates the hidden fields required by Raven to identify and authenticate your company, as well as describe the details of the payment:

<?php mdGenerateInputs(array(
  'username' => 'senoma.test',
  'sharedsecret' => 'kool aid tastes great',
  'routingnumber' => '508754',
  'currency' => 'CNY',
  'amount' => 100,
  'resultredirecturl' => 'https://wgs.rustycog.com/result.php'
))?>

The fields are hidden since they contain nothing of interest to the customer. The shared secret is only used to calculate a signature, by which Raven verifies your identity, it is not included in the form and so cannot be seen if a customer inspects the source of your payment page.

SecurePay Examples

There are a number of ways to get a browser to post a form. The simplest is to have a button on your page tied to hidden fields that describe the payment to be made. Below is a button tied to such a form with a payments as follows:

<?php include_once('/tools/md.php')?>

<form action="https://raven.deepcovelabs.net/realtime/securepay" method="post">
    <?php mdGenerateInputs(array(
    'username' => 'senoma.test',
    'sharedsecret' => 'kool aid tastes great',
    'routingnumber' => '508754',
    'currency' => 'CNY',
    'amount' => 100,
    'resultredirecturl' => 'https://wgs.rustycog.com/result.php'
    ))?>
    <input type="image" src="/images/buynow.gif"/>
</form>

Third Party Shopping

Raven is integrated with several shopping carts, stores, gateways and CRMs. Typically these will handle multiple aspects of payment processing, including refunding payments, however you may need to use one of our other integrations for some functions, such as Raven Online for reviewing your merchant account.

Below is the list of systems with which Raven is integrated. One key differentiator is if a cart or CRM is not hosted by a PCI-compliant vendor or you will need to host it yourself and take on the compliance burden.

Cart Hosting Remarks
LimeLight vendor hosted Commercial CRM, no hosting of shop or purchase pages
Magento both Magento is both a commercial hosted product and a self hosted OSS product. Raven is only available on the self hosted OSS platform
UltraCart self hosted Commercial product
Shopify vendor hosted Commercial platform/eco-system
ZenCart self hosted Open source cart with Raven plugin for integration
OS Commerce self hosted Open source cart with Raven plugin for integration

Testing

To begin testing you will need a set of credentials.

Ideally, card payment testing is done using your payment routing and "magic" card numbers in test mode. Magic card numbers are card numbers guaranteed not to correspond to live cards.

3DS can only be tested using real cards against a live (non-test) routing. If 3DS is requested against a routing configured for testing, the 3DS window will not appear.

Two Types of Magic Cards

There are two types of magic card numbers:

  • Distinct Magic Cards

    Each card number in the tables below may be used to evoke a specific, unique response from Raven. For example, to elicit the response Declined, the card with magic number 4000000000000044 can be supplied.

    Important: All of the distinct magic card numbers are assumed to be US-based credit cards.

  • Programmatic Magic Card

    A single card number 4242424242424242 is used. Other aspects of the card (such as country, card scheme, and expected response) are specified in the request.

    Because of their configurability, programmatic magic card numbers can be used to test more complex scenarios, such as:

    • non-credit card types of card schemes (such as debit)
    • non-US card payments for industries classified as SIC 7995

Testing with Distinct Magic Cards

  1. Pick a scenario that you want to test for, for example transactions that can be considered a "Success".
  2. Select your desired response, for example "Approved".
  3. Select any magic card number that delivers the desired response, for example "4000000000000010".
  4. Set the selected card number on your test card payment Submit endpoint and call it.
  5. Verify that you received the expected "ResponseCode" response parameter and perform the appropriate handling.

Distinct Magic Card Scenarios

Success

ResponseCode Numbers
Approved 4000000000000010, 5100000000000016
Declined 4000000000000044, 5100000000000040
PickUpCard 4000000000000069, 5100000000000065
ReferToIssuer 4000000000000077, 5100000000000073
RepeatDeclined 4000000000000051, 5100000000000057
Voided 4000000000000085, 5100000000000081

Rejected

ResponseCode Numbers
AccountBlocked 4000000000000093, 5100000000000099
PreauthExpired 4000000000000135, 5100000000000131
ServiceNotAvailable 4000000000000127, 5100000000000123
SubmitterNotAuthorized 4000000000000184, 5100000000000180
UnsupportedAmount 4000000000000119, 5100000000000115
UnsupportedCardScheme 4000000000000101, 5100000000000107

Configuration Error

ResponseCode Numbers
MultipleCandidateChannels 4000000000000143, 5100000000000149
NoActiveChannels 4000000000000150, 5100000000000156
NoChannelForCurrency 4000000000000176, 5100000000000172
NoChannelForType 4000000000000168, 5100000000000164

Processing Error

ResponseCode Numbers
BankGatewayFailure 4000000000000200, 5100000000000206
ResultIndeterminate 4000000000000218, 5100000000000214
ServerError 4000000000000192, 5100000000000198
UnexpectedResponse 4000000000000226, 5100000000000222

Testing with the Programmatic Magic Cards

Programmatic magic cards have the added benefit of being able to test advanced aspects of card payments, such as country of origin or card scheme (e.g. Mastercard credit or Visa debit).

  1. Decide on any of the following as part of your test scenario:

    • Scenario Outcome - pick a scenario that you want to test for (for example transactions that can be considered a "Success"), then select your desired response (for example "Approved") from the Programmable Response Code table below.
    • Country of Origin - pick the country from which the card was issued, for example "CA" for Canada.
    • Card Scheme - pick the scheme that issued the card, for example "VI", for Visa.
  2. Set the "PaymentReference" field value on your card payment Submit action in such a way that it represents all of your choices. For example, the scenario mentioned above could be tested by:

    • PaymentReference = "approvedtest[CA:VI:Approved]"
  3. Set the card number on your test card payment Submit action to "4242424242424242" and invoke the action.

  4. Verify that you received the expected "ResponseCode" response parameter and perform the appropriate handling.

Programmatic Magic Card Syntax

The following Extended BNF describes the format of PaymentReference field, when programmatic magic card number 4242424242424242 is used:

PaymentReference ::=  [ClientReference], [ "[", [CountryCode], ":", [SchemeCode],  ":", [ResponseCode] "]" ]

ClientReference ::= text;

CountryCode ::= "CA" | "US | ... (valid [ISO 3166-1 alpha-2][1] code, default is "US")

SchemeCode ::= "VI | "MC" | ... (see scheme table below, default is "VI")

ResponseCode ::= "Approved" | "Declined" | ... (see response table above, default is "Approved")

Programmatic Magic Card Examples

  1. Ask Raven to approve a payment on a Canadian Visa card:

    PaymentReference = "approvedtest[CA:VI:Approved]" note: "approvedtest" is a client-supplied reference (can be anything)

  2. Ask Raven to decline a US Mastercard payment:

    PaymentReference = "declinedtest[US:MC:Declined]"

  3. Ask Raven to decline a US Visa payment, using default values for country of origin and scheme:

    PaymentReference = "declinedtest2[::Declined]"

Programmatic Magic Card Programmable Values

Programmable Responses

The table below gives the desired response values (verbatim including case) that can be programmed:

Category ResponseCode
Success Approved, Declined, PickUpCard, ReferToIssuer, RepeatDeclined, Voided
Rejected AccountBlocked, PreauthExpired, ServiceNotAvailable
SubmitterNotAuthorized, UnsupportedAmount, UnsupportedCardScheme
Configuration MultipleCandidateChannels, NoActiveChannels, NoChannelForCurrency
NoChannelForType
Processing Errors BankGatewayFailure, ResultIndeterminate, ServerError, UnexpectedResponse

Programmable Countries

The accepted country values are valid ISO 3166-1 alpha-2 codes.

Programmable Card Schemes

The following table of card scheme codes may be used to identify a scheme based on a code returned by Raven. This is not a list of accepted card schemes. Card schemes accepted vary from merchant to merchant.

Your PRN must be configured to support the scheme that you programmatically set.

Code Name Code Name
AT Automated Teller Machine PL Platima
AX American Express PP PPT
CH CHJones Fuel Card RF ReD Fuel Card
DC Diners Club/Carte Blanche RG RBS Gift Card
DK Dankort SO Solo
DU DUET SW Switch
DV Discover UF UK Fuel Card
ER EnRoute VD Visa Debit
GE GE Capital VE Visa Electron
JB JCB VI Visa
JC Laser VP Visa Purchase
MA Maestro XX Unknown
MC Mastercard/Eurocard
MD Mastercard/Eurocard debit
PF PHH Fuel Card