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 request either a cc_debit or a cc_credit from RAVEN.
- 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 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
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. (e.g.) 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.
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.
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. |
Request and Response Fields for Card Payments
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:
For example, a cc_debit is used in the case of a sale and results in a charge to the customers account.The PaymentType “cc_preauth” is used to acquire authorization for debiting funds from a card. “cc_settle” debits funds acquired by a previous “cc_preauth”. |
| 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. |
| 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, Amex, 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.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.
NOTE: Contact DeepCove Labs 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 | 15 | Req | C | The TemplateNumber must be the tracking number of a successful card payment. If provided, the Fields marked with an * (the card 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 card number. |
| TrackingNumber | N | 10 | 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. For descriptions of these see the full description of cvv2 response codes, above.
|
| 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 | ||
| 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. | |
| 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. |
| 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 |
| 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.
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 |