Advanced Reference
MarketDirect is an extremely flexible solution that caters to small and medium sized businesses. Below is a detailed reference of all of the available features of the product.
Fraud Scoring
MarketDirect supports payment fraud risk scoring. This facility allows you to provide data that profiles a customer and is used to compute a ‘Fraud Score’. By default MarketDirect will not take any action based on the fraud score. You should review the fraud score and 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
- simply void (or ignore) the payment if you deem the score to be too high
The score is the chance that a payment is fraudulent expressed as a percentage.
Flagging Payments
You can request that payments that meet certain conditions be flagged. Flagged payments will not be settled even if you are 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, any flagged payments that have not been manually released will be voided and any approvals will be lost.
Flagged payments 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 connected to it will not be triggered. For example, if your configuration setup includes sending notice to the fulfillment company to complete the order, once you proceed with a flagged transaction that fulfillment action will still need to be initiated.
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 it 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 County | 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. |
Processing
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. Size | Default | Request | Response | 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 3D-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
Reporting
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. Size | Default | Request | Response | 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_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 | O | N | Email address monitored by merchant “from” which receipt emails will be sent by the system. If not provided, default of do-not-reply@raven.deepcovelabs.com 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 | approved - payment was approved declined - payment was declined absent - payment authorization was not attempted, most likely because the payment in its current form is invalid, please see Raven Online for details card_expired - card’s expiration date is in the past pick_up_card - issuer requested that card be retained refer_to_issuer - refer to card issuer for reason repeat_declined - card was declined multiple times in a row service_not_available - payment authorization was attempted, but failed, please see Raven Online for details unexpected_response - payment authorization was attempted, but failed for unknown reason, please contact customer support |
|
| md_cv2_status | Code | 50 | N | M | cvv2_matched – bank confirmed CVV2 match cvv2_not_checked – CVV2 check could not be performed at this time cvv2_not_matched – bank confirmed CVV2 mismatch, merchant should review this transaction prior to fulfillment cvv2_unavailable – CVV2 checking is not available for this card |
|
| md_card_scheme | Code | 2 | N | M | Note, the below list does not represent all schemes that can be accepted, please contact your client support representative for details.
DC – Diners Club/Carte Blanche DV – Discover ER – EnRoute GE – GE Capital JB – JCB JC – Laser MA – Maestro MC – MasterCard/Eurocard MD – MasterCard/Eurocard Debit SO – Solo SW – Switch VD – Visa Debit VE – Visa Electron VI – Visa VP – Visa Purchase |
|
| md_card_brand | Code | 25 | N | M | Note, the below list does not represent all schemes that can be accepted, please contact your client support representative for details.
diners_club – Diners Club/Carte Blanche discover – Discover enroute – EnRoute ge_capital – GE Capital jcb – JCB laser – Laser maestro – Maestro mastercard – MasterCard/Eurocard solo – Solo switch – Switch visa – Visa/Delta/Electron unknown – Unknown |
Look & Feel
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 | Default | Request | Response | 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 | en / de / fr | 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
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 | Default | Request | Response | Remarks |
|---|---|---|---|---|---|---|
| md_detail_item_[index] | String | 25 | O | N | Label of each item. | |
| md_detail_cost_[index] | Integer | 25 | 0 | O | N | Cost of each item; see md_amount for formatting. |
| md_detail_qty_[index] | Integer | 25 | 1 | O | N | Quantity of each item, 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. |
Contact Information
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 | Default | Request | Response | 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_address1 | String | 50 | O | C | ||
| md_shipping_address2 | String | 50 | O | C | ||
| md_shipping_address3 | String | 50 | O | C | ||
| 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_address1 | String | 50 | O | C | ||
| md_billing_address2 | String | 50 | O | C | ||
| md_billing_address3 | String | 50 | O | C | ||
| 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 |
Signature
In order for the payment page to ensure that a payment request has been authorized, you must include a digital signature. The digital signature is a MD5 or SHA-1 hash of md_submitter, md_timestamp and a few values from the payment. Note that signatures are calculated automatically by helper functions (i.e. mdGenerateInputs for PHP). You only need to use the procedure below when coding form POST fields directly.
We’ll use the payment request below as an example:
<input type="hidden" name="md_submitter" value="ernest@somecorp.us"><input type="hidden" name="md_timestamp" value="2006-01-17T15:26:30.Z"><input type="hidden" name="md_amount" value="2000"><input type="hidden" name="md_currency" value="EUR"><input type="hidden" name="md_reference" value="ord#123">
Given the preceding request, the md_signature field is constructed (hashing with either algorithm) in the following way:
- Create a string of comma separated values using the elements: md_submitter, md_timestamp, md_amount, md_currency and md_reference.
ernest@somecorp.us,2006-01-17T15:26:30Z,2000,EUR,ord#1234
- Calculate the hash of this string and create a new comma separated string with this hash and your shared secret. Note: any letters in the hash MUST be upper case.
562668587AB703FD11166A5F89B4AF5C68321E5D,all good men die young
- Calculate the hash of this second string. Again any letters in the hash must be in upper case; this is the signature of the payment
C9885A4F6CEC8D08281E5EDB5946C12A089CD5C8
- Now we can complete the above request, adding the completed signature
<input type="hidden" name="md_submitter" value="ernest@somecorp.us">
<input type="hidden" name="md_timestamp" value="2006-01-17T15:26:30.Z">
<input type="hidden" name="md_amount" value="2000">
<input type="hidden" name="md_currency" value="EUR">
<input type="hidden" name="md_reference" value="ord#123">
<input type="hidden" name="md_signature" value="C9885A4F6CEC8D08281E5EDB5946C12A089CD5C8">
Please make sure to never include your shared secret in the source code of a page as it could greatly compromise the security of your account.