Advanced References

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 moved 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_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_status String 50 N M Status of the payment. For list of possible codes see description of status code with the various types.
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
md_avs_address_status Code 25 N M avs_address_matched
avs_address_partial_match
avs_address_not_matched
avs_address_not_checked
avs_address_unavailable
md_avs_postal_status Code 25 N M avs_postal_not_checked
avs_postal_not_matched
avs_postal_matched
avs_postal_partial_match
avs_postal_unavailable
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;

  1. 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)
  2. 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)
  3. 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)

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 exp,image/gif,R0lGhAQA=
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

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="[email protected]">
<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.
[email protected],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="[email protected]">
<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.

Text to display in the page header as well as page title in the browser.