Card Payments
Card payments initiate a real-time approval and subsequent settlement of credit card payments. There are two ways to process card payments: automatic settlement and manual settlement.. The automatic cycle will obtain an approval and then settle the transaction without further input. It functions as follows:
- You make a payment request from RAVEN. Usually this will be a cc_debit in the case of a sale and a cc_credit in the case of a refund. But other specialized types exist.
- RAVEN will attempt to obtain an approval and return the results to you.
- RAVEN will then settle all approved payments on a file by file basis. Once a file is marked for settlement all approved payments in the file will be settled.
If you need to make ship/no ship decisions based on the availability of stock in your warehouse, you will need to use manual settlement. The process is as follows:
- You request a cc_preauth from RAVEN.
- RAVEN will attempt to obtain an approval and return the results to you.
- When you wish to settle the payment, you must request a cc_settle payment providing the tracking number of the original cc_preauth.
All valid cc_settle requests will initiate a debit from a cardholder’s account.
Some considerations to take into account when using manual settlement are:
- An approved preauthorization will expire after 168 hours.
- 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.
- When cc_settle payments are being processed, RAVEN will check that the preauthorization meets the following conditions: that the two have the same currency, that the pre-auth was approved, that the amount to settle is not greater than the amount that has been pre-authorized and that the pre-auth has not expired or been used previously.
- In the case of batch processing using a webfolder, if a Request file contains any cc_preauth payments, RAVEN will also return a Settlement file at the same time as the Result file. This file is a payment file containing one cc_settle payment for each approved cc_preauth payment in the Result file. When you wish to settle the approved payments, you can simply edit the Settlement file so it includes only the payments you wish to settle and submit it to RAVEN for processing. RAVEN generated Settlement files have a name that is simply the original Request file name with “
PREAUTHS TO SETTLE.txt"appended to it, e.g.AthleticDigest_311102_2.txt PREAUTHS TO SETTLE.txt
As this file is generated purely for your convenience, you may choose to simply ignore it.
Original Credit Transfers
Original Credit Transfers (OCT credits) are a specialized transaction type that allow merchants to apply a credit to a card without first having debited the card. The rules for using OCT credits are complex; contact your processor before making use of this payment type.
Fraud Scoring
RAVEN supports payment fraud risk scoring. This facility allows you to provide data that profiles a customer and is used to compute a ‘Fraud Score’. The score is the chance that a payment is fraudulent, expressed as a percentage. By default, RAVEN will not take any action based on the fraud score. You should review the fraud score and may choose to:
- do nothing, and allow the payment to be settled as normal,
- query the customer and conditionally void or settle the payment as normal,
- or simply void (or ignore) the payment if you deem the score to be too high.
To invoke the fraud scoring mechanism you need to provide at least an IP address, a billing city and a billing country. Providing additional information will improve the reliability of the fraud score. The complete set of fields used to determine the fraud score are:
CardIssuerName
CardIssuerPhone
CustomerIP
BillingCity
BillingRegion
BillingPostal
BillingCountry
ShipToCity
ShipToRegion
ShipToPostal
ShipToCountry
Blacklisting Cards
RAVEN enables each client to maintain a black list. There is no API for this function; to have a card added to your black list, please email your account representative with the tracking number of a prior payment and the associated card will be black listed.
Address Verification
RAVEN supports address verification (AVS) for UK and North American addresses associated with MasterCard and Visa cards. AVS is supported with the payment types cc_preauth and cc_debit. To make use of AVS you need to supply billing address information as part of the payment request. The fields names are BillingStreetAddressOne through BillingStreetAddressFour as well as BillingPostalCode. The other billing address fields, such as BillingCity, have no effect on AVS. The table of request/response fields below specifies the fields.
If any of the street address or postal code fields are provided, the digits they contain are send to the bank for verification and a response field is returned. If street address information is provided you will receive a AVSAddressResponseCode indicating the outcome of the street address verification. Similarly if the billing postal code is provided you will receive a AVSPostalResponseCode indicating the outcome of the postal code verification. The possible values for these fields are documents in the table of request/response fields below. You may then take these outcomes into account when deciding how to proceed.
Flagging Payments
You can request that payments that meet certain conditions be flagged. Flagged payments will not be settled even if your account is configured for auto-release; instead, all flagged payments will move to a separate file where they will be held for your review. After 7 days, flagged payments that have not been manually released will be voided and the associated approvals will be lost.
For users of MarketDirect and similar payment pages:
Flagged payments will require special attention if the payment was made through MarketDirect. Your customers will not be aware that their payment has been flagged, and will assume that the transaction completed successfully. If you review the payment and decide to proceed, there is no need to inform the customer. However, if you decide not to proceed, it may be necessary to inform the customer.
Additionally, once a payment is flagged, any fulfillment actions requested in connection to it will not be triggered. For example, your account configuration might include notifying your shipping department that an order needs to be packed and shipped. Once a flagged payment is reviewed and released, you must notify your shipping department of the order. No automatic order notification will be sent.
You can request that payments be flagged for the following reasons:
| Reason | Description |
|---|---|
| Fraud Score | Any payment with a fraud score over a certain percentage will be flagged. |
| Fraud Score Not Checked | Any payment where the fraud score was not checked due to insufficient information will be flagged. |
| CVV2 Not Matched | Any payment where the CVV2 was checked and did not match will be flagged. |
| CVV2 Not Checked | Any payment where the CVV2 was not checked even though the service was available will be flagged. |
| CVV2 Unavailable | Any payment where the CVV2 could not be checked because the service was not available will be flagged. |
| Uncommon Country | Any payment with a card domiciled in an uncommon country will be flagged. This list changes from time to time, please contact Client Support for a current listing. |
Delayed Processing
In some cases, it may be useful to delay authorization of card transactions in RAVEN files until a specific date/time. This can be accomplished by providing a UTC time stamp formatted as “YYYY-MM-DDThh:mm:ssTZD” in the header of the file as show below,
RavenPaymentFile_v2.2,AuthorizeAfter:2011-05-17T14:45:00Z
To ensure the file is processed on time the file must be uploaded to RAVEN before the normal client cut-off time on a business day preceding requested the AuthorizeAfter date/time. This is to allow time for staff to approve the file if such approval is required.
The AuthorizeAfter time is the time 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 but may be off by up to an hour.
Request and Response Fields
The supported fields are defined in the following table. The column ‘Req/Rsp’ indicates if the field forms part of the request to RAVEN (Req)or part of the response from RAVEN (Rsp). Except as noted, Raven will echo all request fields in the response. The column “O/C/M” indicates if a field is optional, conditional or mandatory.
| Field Names | Type | Max. Size | Req/Rsp | O/C/M | Remarks |
|---|---|---|---|---|---|
| PaymentRoutingNumber | N | 6 | Req | M | The six digit payment routing number assigned to you. This must always be the first field of any payment line. |
| PaymentType | T | 25 | Req | M | Credit and debit from the customer’s perspective. The possible types are:
|
| Amount | N | 10 | Req | M | Value supplied in base units of currency, with no decimal. E.g. $150.00 is 15000. For PaymentType “cc_settle”, transaction value must be no greater (but can be less) than the Amount value for the corresponding “cc_preauth” payment. |
| CurrencyCode | A | 3 | Req | M | The three character ISO currency code, e.g. USD or EUR. This is used to verify the payment routing number. |
| AccountName | AN+(s) | 40 | Req | O | The name exactly as printed on the card. |
| CardNumber† | T | 19 | Req | M | The number of the customer’s account, as found on the card that is to be debited or credited. Not required for cc_settle. |
| ExpiryDate† | N | 4 | Req | M | The expiry date of the card, in MMYY format. Not required for cc_settle. |
| CardBrand | T | 10 | Req | O | If provided, RAVEN will ensure the card belongs to the specified brand. The supported brands are: Visa, MasterCard, Switch, Solo and Maestro. |
| CVV2 | N | 4 | Req | O | The CVV2 number as printed on the physical credit card. |
| IssueNumber† | N | 2 | Req | C | Required for the Switch brand card scheme. Not required for cc_settle. |
| Reference | T | 30 | Req | O | Information the merchant supplies to identifying the payment or customer. Will be echoed on reports. Will not appear on cardholder statement. In the case of batch files this field is recommended but optional, in all other cases (RAPI, Virtual Terminal) this field is mandatory and must be unique in the file. |
| Reference2-10 | T | 30 | Req | O | 9 additional reference fields containing information the merchant may supply at their discretion identifying the payment or customer. Will be echoed on reports. Will not appear on cardholder statement. |
| PreauthNumber | N | 9 | Req | C | Mandatory for PaymentType “cc_settle”. Its value must be the TrackingNumber value for the corresponding “cc_preauth” payment. |
| Description | T | see remarks | Req | O | If present, will be submitted to the issuing bank for inclusion in the customer statement instead of the fixed merchant description. The number of characters available will depend on the length of the merchant name, and can be calculated as follows: 21 – (length of merchant name). Any additional description will be truncated without warning. White space may be collapsed and the description may appear in uppercase only. This field is also known as a “Dynamic Descriptor DD1″. NOTE: Contact client support before making use of this field. |
| Description2 | T | 13 | Req | O | If present, will be submitted to the issuing bank for inclusion in the customer statement instead of the fixed merchant location description. This field should be used either to indicate the merchant location or to provide a way for customers to contact the merchant (e.g. a toll free number or an email address). White space may be collapsed and the description may appear in uppercase only. This field is also known as a “Dynamic Descriptor DD2″. Note: Contact client support before making use of this field. |
| Comment | T | 1000 | Req | O | Information the merchant may supply at their discretion. Will be echoed on result reports. |
| TemplateNumber | N | 9 | Req | C | The 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 Template Number is supplied it is an error to supply a account number. TemplateNumber is mandatory for cc_refund. |
| TrackingNumber | N | 9 | Rsp | M | RAVEN will return a unique tracking number for each payment processed, independent of type. |
| ApprovalCode | N | 6 | Rsp | 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. |
| CVV2ResponseCode | T | 50 | Rsp | M | One of the following status codes:
The difference between cvv2_unavailable and cvv2_not_checked is that in the second case the cvv2 checking should have been available but was not carried out for some reason. |
| AVSAddressResponseCode | T | 50 | Rsp | O | One of the following response codes:
The difference between avs_address_unavailable and avs_address_not_checked is that in the second case the AVS checking should have been available but was not carried out for some reason. |
| AVSPostalResponseCode | T | 50 | Rsp | O | One of the following response codes:
The difference between avs_postal_unavailable and avs_postal_not_checked is that in the second case the AVS checking should have been available but was not carried out for some reason. |
| StatusCode | T | 50 | Rsp | M | One of the following status codes.
|
| 3D Secure / Secure Code Fields | The following are the request and response fields involved in 3D secure. Items marked as mandatory are only mandatory if 3D secure processing is desired. | ||||
| 3DSVerify | T | Req | O | Flag indicating whether or not 3DS should be attempted for this transaction. | |
| 3DSMerchantURL | T | Req | O | The URL of the website on which the payment is being made | |
| 3DSDeviceCategoryCode | T | Req | O | Indicates the type of device used to initiate the transaction:
|
|
| 3DSBrowserAcceptHeader | T | Req | O | The MIME types of the headers accepted by this device. | |
| 3DSBrowserUserAgentHeader | T | Req | O | The user agent string of the user agent. | |
| 3DSPAReq | T | Req | O | The Payer Authentication Request (PAReq) that needs to be submitted to the ACS. | |
| 3DSACSURL | T | Req | O | The URL of the issuing bank’s ACS, to which the cardholder needs to be re-directed. | |
| 3DSResponseCode | OneOf | Res | C |
Indicates the outcome of the 3DS authorization
|
|
| 3DSPARes | T | Req | O | The Payer Authentication Response (PARes) returned by the ACS. | |
| Fraud Scoring Fields | The following are the request and response fields involved in fraud scoring | ||||
| CustomerIP | 17 | Req | C | The IP address of the customer that originated the request, in dotted decimal notation. Format: NNN.NNN.NNN.NNN. Mandatory if a fraud score is desired, otherwise optional. | |
| CardIssuerName | T | 255 | Req | O | Name of the bank which issued the credit card based on BIN number. Used to verify that cardholder is in possession of the credit card. |
| CardIssuerPhone | 255 | Req | O | Customer service phone number listed on back of credit card. Used to verify that cardholder is in possession of the credit card. | |
| FraudScore | N | 10 | Rsp | 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. |
| Shipping /Billing Address Fields | |||||
| BillingAddressLine1-4 | T | 60 each | Req | O | Billing address lines. Up to four may be supplied. Will trigger AVS. |
| BillingCity | T | 50 | Req | O | The name of the city in the customer’s billing address |
| BillingRegion | T | 50 | Req | O | The name of the region (e.g. province/state) in the customer’s credit card billing address. |
| BillingPostal | T | 10 | Req | O | The postal code of the customer’s billing address Will trigger AVS. |
| BillingCountry | T | 2 | Req | C | The name or two letter ISO country code of the customer’s credit card billing address. Mandatory if a fraud score is desired, otherwise optional. |
| ShippingAddressLine1-4 | T | 60 each | Req | O | Shipping address lines. Up to four may be supplied. |
| ShipToCity | T | 50 | Req | O | The name of the city in the customer’s shipping address. |
| ShipToRegion | T | 50 | Req | O | The name of the region (e.g. province/state) in the customer’s shipping address. |
| ShipToPostal | T | 10 | Req | O | The postal code of the customer’s shipping address. |
| ShipToCountry | T | 2 | Req | O | The name or two letter ISO country code of the customer’s shipping address. |
| ContactEmail | T | 255 | Req | O | The customer’s email address. |
| CustomerPhone | T | 255 | Req | O | The customer’s phone number. |
† These fields will be copied into recurring payments from their template.
CVV2 Response Codes
| Response | Description |
|---|---|
| cvv2_matched | Any payment were the CVV2 was checked and matched the CVV2 supplied. |
| cvv2_not_matched | Any payment where the CVV2 was checked and did not match the CVV2 supplied. |
| cvv2_not_checked | Any payment where either the CVV2 data was not supplied or rarely, where the CVV2 was not checked by the gateway even though the service was available. |
| cvv2_unavailable | Any payment where the CVV2 could not be checked because the service was not available. |
| cvv2__response_unknown | If the CVV2 was provided but no information on the match is provided by the acquiring bank. |
Returned Payment Status Codes
These are the possible Status values for Card Payment Return files:
| Field Names | Type | Max | Remarks |
|---|---|---|---|
| Status | One of | 50 | The reasons will be one of: account_inactive account_not_found amount_disputed cancelled duplicate fraudulent goods_not_as_agreed goods_not_provided ineligible other processing_unsuccessful refund_not_provided timing_disputed unauthorized |
Testing
Testing CardPayments is done by using a test channel and “magic” card numbers. Magic card numbers are card numbers guaranteed not to correspond to a live card and each number may be used to evoke a specific response. For example, to elicit the response PickUpCard use the magic number 4000000000000069.
Success
| Action | Numbers |
|---|---|
| Approved | 340000000000017 340000000000025 340000000000033 4000000000000010 4000000000000028 4000000000000036 5100000000000016 5100000000000024 5100000000000032 |
| Declined | 340000000000041 4000000000000044 5100000000000040 |
| PickUpCard | 340000000000066 4000000000000069 5100000000000065 |
| ReferToIssuer | 340000000000074 4000000000000077 5100000000000073 |
| RepeatDeclined | 340000000000058 4000000000000051 5100000000000057 |
| Voided | 340000000000082 4000000000000085 5100000000000081 |
Rejected
| Action | Numbers |
|---|---|
| AccountBlocked | 340000000000090 4000000000000093 5100000000000099 |
| PreauthExpired | 340000000000132 4000000000000135 5100000000000131 |
| ServiceNotAvailable | 340000000000124 4000000000000127 5100000000000123 |
| SubmitterNotAuthorized | 340000000000181 4000000000000184 5100000000000180 |
| UnsupportedAmount | 340000000000116 4000000000000119 5100000000000115 |
| UnsupportedCardScheme | 340000000000108 4000000000000101 5100000000000107 |
Configuration
| Action | Numbers |
|---|---|
| MultipleCandidateChannels | 340000000000140 4000000000000143 5100000000000149 |
| NoActiveChannels | 340000000000157 4000000000000150 5100000000000156 |
| NoChannelForCurrency | 340000000000173 4000000000000176 5100000000000172 |
| NoChannelForType | 340000000000165 4000000000000168 5100000000000164 |
Processing Errors
| Action | Numbers |
|---|---|
| BankGatewayFailure | 340000000000207 4000000000000200 5100000000000206 |
| ResultIndeterminate | 340000000000215 4000000000000218 5100000000000214 |
| ServerError | 340000000000199 4000000000000192 5100000000000198 |
| UnexpectedResponse | 340000000000223 4000000000000226 5100000000000222 |