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.
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.
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:
|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.|
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.
|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
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
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.
|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.|
|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).|
|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 email@example.com 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_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;
- 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)
- 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)
- 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-18.104.22.168)
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.
|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
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.
|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.|
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.
|md_shipping_country||ISO Alpha 2||2||O||C||ISO 3166-1-alpha-2 code|
|md_billing_country||ISO Alpha 2||50||O||C||ISO 3166-1-alpha-2 code|
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="firstname.lastname@example.org"> <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.
- 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
- Now we can complete the above request, adding the completed signature
<input type="hidden" name="md_submitter" value="email@example.com">
<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.