Basic features are aspects of payment processing that all integrations need to address. They are:
Optional features include:
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
Raven obtains immediate approvals for credit card transactions. Settlement occurs later and can be automatic or manual.
||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.
||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:
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:
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.
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.
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.
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.
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:
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.
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.
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
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 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
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,
See the Payment Reference for the complete specification of Raven Card Payment Fraud Score request and response fields.
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 (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.
Raven can flag approved
cc_preauth payments before settlement for a variety of reasons.
Flags may be reviewed in Raven Online and are in one of 3 states:
|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.
||You acknowledge the flag but accept the payment regardless, allowing it to settle normally.
||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:
||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.
||You may also choose to have flagged payments put aside for further consideration. There is a slight difference between how this works for
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.
If you supply an
Amount, your customer will receive that exact amount in a given
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
- specify the payment currencies of your customers, via the
- supply an
AccountAmount, rather than an
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.