HOSTED - Retail Merchant Services

1y ago
15 Views
2 Downloads
1.46 MB
130 Pages
Last View : 2m ago
Last Download : 2m ago
Upload by : Gideon Hoey
Transcription

HOSTEDINTEGRATION GUIDEHOSTEDINTEGRATION GUIDEVersion: 10.00V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk-1-

HOSTEDINTEGRATION GUIDE1Hosted HTTP Integration . 31.1About This Guide . 41.2Integration Disclaimer . 41.3Terminology . 51.4Pre-Requisites . 61.5Integration Details . 71.6Authentication . 81.7Supported Actions. 92Hosted Payment Page . 122.1Request Fields . 122.2Response Fields . 143Hosted Payment Page Options. 153.1Request Fields . 154AVS/CV2 Checking . 184.1Background. 184.2Benefits & Limitations . 194.3Request Fields . 204.4Response Fields . 2153-D Secure Authentication . 225.1Background. 225.2Benefits & Limitations . 235.3Implementation . 245.4Request Fields . 255.5Response Fields . 276VISA MCC6012 Merchants . 306.1Background. 306.2Request Fields . 317Billing Descriptor. 327.1Background. 327.2Request Fields . 338Receipts & Notifications . 348.1Background. 348.2Request Fields . 368.3Response Fields . 389Purchase Data . 399.1Background. 399.2Request Fields . 4010 Recurring Transaction Agreements . 4210.1 Background. 4210.2 Request Fields . 4310.3 Response Fields . 4511 Duplicate Transaction Checking . 4611.1 Background. 4611.2 Implementation . 4611.3 Request Fields . 4712 Custom Data . 4812.1 Request Fields . 4813 Advanced Integration Fields . 4813.1 Customer Request Fields. 4913.2 Merchant Request Fields . 5013.3 Supplier Request Fields . 5113.4 Delivery Request Fields . 5213.5 Receiver Request Fields . 5313.6 Shipping Request Fields . 5414 PayPal Transactions . 55V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk-2-

HOSTEDINTEGRATION GUIDE14.1 Background. 5514.2 Benefits & Limitations . 5614.3 Implementation . 5714.4 Request Fields . 5914.5 Response Fields . 6814.6 Transaction Lifecycle . 7814.7 Reference Transactions . 81A-1 Response Codes . 82A-2 AVS / CV2 Check Response Codes . 90A-3 3-D Secure Enrolment/Authentication Codes . 92A-4 3-D Secure Enrolment/Authentication Only . 93A-5 Request Checking Only . 94A-6 Merchant Account Mapping . 95A-7 Velocity Control System (VCS) . 96A-8 Capture Delay . 97A-9 Types of card . 98A-10 Integration Testing . 100A-10.1 Test Card Details . 100A-10.2 Test 3-D Secure Card Details . 103A-10.3 PayPal Sandbox Accounts . 105A-11 Sample Signature Calculation . 106A-12 Transaction Life-cycle . 108A-12.1 Authorise, Capture & Settlement . 108A-12.2 Transaction States . 109A-13 Transaction types . 113A-13.1 E-commerce (ECOM) . 113A-13.2 Mail Order/Telephone Order (MOTO). 113A-13.3 Continuous Authority (CA). 113A-14 Payment Tokenisation . 114A-15 Repeat Transactions . 117A-15.1 Card On File Transactions . 117A-15.2 Continuous Payment Agreements . 118A-16 Transaction Cloning . 120A-16.1 Cloned Fields . 121A-16.2 Cloned Groups . 125A-17 Example Code . 126A-18 Frequently Asked Questions . 1301. I'm getting Invalid Credentials. What do I do? . 1302. I'm getting an invalid signature error message. How do I fix it? . 1303. I have more than one Merchant ID - how do I use more than one?. 1304. I receive a 'Bad Testcard Usage' error message. Why?. 130V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk-3-

HOSTEDINTEGRATION GUIDE1 Hosted HTTP Integration1.1 About This GuideThe Hosted HTTP integration works by redirecting the Customer to theGateway’s Hosted Payment Page, which will gather the Customer’s paymentdetails and send them to the Gateway on your behalf. This allows you thequickest path to integrating with the Gateway.If you wish to take card details on your website, or style your payment pages,then you either need to use the Direct integration or use the Hostedintegration and request a Custom Hosted Payment Page for your website.Unlike the Direct method, your website does not need to have a SSLCertificate, and PCI compliance becomes more straightforward.This guide provides the information required to integrate with the PaymentGateway and gives a very basic example of code for doing so (furtherexamples can be found on our website). It is expected that you have someexperience in server side scripting with languages such as PHP or ASP, orthat an off-the-shelf software package is being used that has in-built or plug-insupport for the Payment Gateway.If you do require programming assistance related to your integration, pleasecontact Retail Merchant Services on 0845 241 9960 or via email toinfo@retailmerchantservices.co.uk.1.2 Integration DisclaimerRetail Merchant Services provides all integration documentation necessary forenabling Merchants to process payments via our Payment Gateway. Whilstevery effort has been made to ensure these guides are accurate andcomplete, we expect Merchants undertaking any integration to test all theirtechnical work fully and satisfy their own standards. Retail Merchant Servicesis not responsible or liable for any Merchant or Third Party integration.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk-4-

HOSTEDINTEGRATION GUIDE1.3 TerminologyThe following terms are used throughout this guide;GatewayThe Retail Merchant Services Payment GatewayMerchantThe Merchant using the Gateway’s servicesAcquirerThe bank or financial institution used by the Merchant.CustomerA customer of the Merchant making a payment etc.CardholderThe person who owns the payment card, normally the Customer.Merchant AccountAn account on the Gateway mapped to an Acquirer issued account.You/yourThe Merchant or their representative performing the integration.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk-5-

HOSTEDINTEGRATION GUIDE1.4 Pre-RequisitesYou will need the following information to integrate with the Payment Gatewayusing the Hosted integration method;RetailMerchantServicesMerchant IDYour Merchant ID enables you to access andcommunicate with the Payment Gateway. Please note thatthese details will differ to the login supplied to access theadministration panel. You should have received thesedetails when your account was set up.You may also use test Merchant IDs (if you have beenissued with a test ID) and swap these for your live accountdetails when you receive ervices.co.uk/paymentform/New Merchants who have not yet received their live Merchant ID can stillperform an integration for testing purposes. Simply enter one of the testMerchant IDs below and use the test cards provided in appendix A-10 to run atest transaction.For non 3-D Secure testing use Merchant ID 101599For 3-D Secure Testing use Merchant ID 101600V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk-6-

HOSTEDINTEGRATION GUIDE1.5 Integration Details1.5.1 Hosted RequestsA request can be sent to the Gateway by submitting a HTTP POST request tothe integration URL provided.The request should be URL encoded as name value fields separated by ‘&’characters. The response will be received in the same format.For more information on the URL encoded format refer to RFC 1738 and theapplication/x-www-form-urlencoded media type.Please note that the field names are cAsE sEnSiTiVe.The request needs to be sent from the Customers web browser as theresponse will be a HTML Hosted Payment Page requesting the Customerenter their card details etc. The normal way to achieve this is to send therequest data as hidden form fields as per the example code provided inappendix A-17. The browser will then automatically encode the requestcorrectly as per the application/x-www-form-urlencoded format.Once the payment page has been complete the Customer’s browser will beautomatically redirected to the URL provided via the redirectURL field. Theresponse will be returned to this page using a HTTP POST request.The response will return the request fields in addition to any dedicatedresponse field. If the request contains a field that is also intended as aresponse field then any incoming request value will be overwritten by thecorrect response value.1.5.2 Callback URLYou can request that the Gateway sends a copy of the response to analternative URL using the callbackURL request field. In this case eachresponse will be then POSTed to that URL in addition to the normal response.This allows you to specify a URL on a secure shopping cart or backend orderprocessing system which will then fulfil any order etc. related to thetransaction.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk-7-

HOSTEDINTEGRATION GUIDE1.6 AuthenticationAll requests must specify which Merchant Account they are for using themerchantID request field. In addition to this the following security measurescan be used;1.6.1 Message signingMessage signing requires you to generate a hash of the request messagebeing sent and then send this hash along with the original request in thesignature field. The gateway will then re-generate the hash on the requestmessage received and compare it with the one sent. If the two hashes aredifferent then the request received must not be the same as that sent and sothe contents must have been tampered with and the transaction will beaborted and an error response returnedThe gateway will also return hash of the response message in the returnedsignature field allowing the merchant to create a hash of the response(minus the signature field) and verify the hashes match.If message signing is enabled, then the data POSTed to any callback URL willalso be signed.See appendix A-11 for information on how to create the hash.1.6.2 Allowed IP addressesYou can configure a list of IP addresses using the Merchant ManagementSystem (MMS). Two different address lists can be configured, one forstandard requests, such as sales, and one for advanced requests, such asrefunds and cancellations. If a request is received from an address other thanthose configured, then it will be aborted and an error response returned.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk-8-

HOSTEDINTEGRATION GUIDE1.7 Supported ActionsAll requests must specify what action they require the Gateway to performusing the action request field. The Hosted integration allows the followingactions to be specified;1.7.1 SALEThis will create a new transaction and attempt to seek authorisation for asale from the Acquirer. A successful authorisation will reserve the funds onthe Cardholder’s account until the transaction is settled.The captureDelay field can be used to state if the transaction should beauthorised only and settled at a later date. For more details on delayedcapture refer to appendix A-8.1.7.2 VERIFYThis will create a new transaction and attempt to verify that the card accountexists with the Acquirer. The transaction will result in no transfer of funds andno hold on any funds on the Cardholder’s account. It cannot be captured andwill not be settled. The transaction amount must always be zero.This transaction type is the preferred method for validating that the cardaccount exists and is in good standing, however it cannot be used to validatethat it has sufficient funds.1.7.3 PREAUTHThis will create a new transaction and attempt to seek authorisation for a salefrom the Acquirer. If authorisation is approved, then it is immediately voided(where possible) so that no funds are reserved on the Cardholder’s account.The transaction will result in no transfer of funds. It cannot be captured andwill not be settled.This transaction type can be used to check whether funds are available andthat the account is valid. However due to the problem highlighted below it isrecommended that Merchants use the VERIFY when supported by theirAcquirer.Warning: If the transaction is to be completed then a new authorisation needs to be soughtusing the SALE action. If the PREAUTH authorisation could not be successfully voidedthen this will result in the funds being authorised twice effectively putting 2 holds on theamount on the Cardholder’s account and thus requiring twice the amount to be available inthe Cardholder’s account. It is therefore recommended to only PREAUTH small amountssuch as 1 to mainly check account validity.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk-9-

HOSTEDINTEGRATION GUIDEThis page is intentionally left blank.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 10 -

HOSTEDINTEGRATION GUIDEThis page is intentionally left blank.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 11 -

HOSTEDINTEGRATION GUIDE2 Hosted Payment PageYou can display the payment page and perform a new transaction, such as asale, by sending a request with the required action and order details.2.1 Request FieldsField NameMandatory?DescriptionmerchantIDYesYour Gateway Merchant ID.signatureYes1Any hash used to sign this request.Refer to section 1.6.1 for details.actionYesThe action requested.Refer to section 1.7 for supported actions.Possible values are: PREAUTH, SALE,VERIFY.1amountYesThe amount of the transaction in minorcurrency. For the UK, this is pence, so 10.99 should be sent as 1099.Numeric values only – no decimalpoints or currency symbols.countryCodeYesMerchant’s location.Valid ISO-3166 alpha or numeric code.currencyCodeYesTransaction currency.Valid ISO-4217 alpha or numeric code.transactionUniqueNoYou can supply unique identifier for thistransaction. This is an added securityfeature to combat transaction spoofing.orderRefNoFree format test field to store order details,reference numbers, etc. for the Merchant’srecords.captureDelayNoNumber of days to wait betweenauthorisation of a payment andsubsequent settlement.Refer to appendix A-8 for details.callbackURLNoA non-public URL which will receive acopy of the transaction result by POST.Refer to section 1.5.2 for details.A signature is recommended if using the Hosted Integration.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 12 -

HOSTEDINTEGRATION GUIDEThis page is intentionally left blank.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 13 -

HOSTEDINTEGRATION GUIDE2.1 Response FieldsThe response will contain all the fields sent in the request plus the following;Field NameReturned?responseCodeAlwaysDescriptionA numeric code providing the outcomeof the transaction:Possible values are:0 - Successful / authorised transaction.2 - Card referred.4 - Card declined – keep card.5 - Card declined.Check responseMessage for moredetails of any error that occurred.Refer to appendix A-1 for details.responseMessageAlwaysThe message received from theAcquiring bank, or any error message.transactionIDAlwaysA unique ID assigned by the Gateway.xrefAlwaysYou may store the cross reference forrepeat transactions.stateAlwaysTransaction state.Refer to appendix A-12.2 for details.timestampAlwaysTime the transaction was created or lastmodified.transactionUniqueIf suppliedAny value supplied in the initial request.authorisationCodeOn successAuthorisation code received fromAcquirer.referralPhoneIf providedTelephone number supplied by Acquirerto phone for voice authorisation. MostAcquirers do not provide this number.amountReceivedOn successThe amount the Acquirer authorised.This should always be the full amountrequested.orderRefIf suppliedAny value supplied in the initial request.cardNumberMaskAlwaysCard number masked so only the last 4digits are visible.cardTypeCodeAlwaysThe code of card used.Refer to appendix A-9 for detailscardTypeAlwaysThe description of the card used.Refer to appendix A-9 for details.cardSchemeCodeAlwaysThe code of the card scheme used.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 14 -

HOSTEDINTEGRATION GUIDEField NameReturned?DescriptionRefer to appendix A-9 for details.cardSchemeAlwaysThe description of the card schemeused.Refer to appendix A-9 for details.cardIssuerAlwaysThe card issuer (when known).cardIssuerCountryAlwaysName of card issuing country (whenknown).cardIssuerCountryCodeAlwaysISO-3166 Alpha 2 code of the cardissuing country (when known)Note: the response is also POSTed to any URL provided by optionalcallbackURL.3Hosted Payment Page OptionsYou can customise the appearance of the standard Hosted Payment Page bysending additional fields in the request. Some of these fields may not work ifthe Merchant has a customised Hosted Payment Page.3.1 Request FieldsField NameMandatory?cardNumberNoDescriptionDefault value to display in the card numberfield.It is highly recommended that this fieldnever be sent!cardCVVNoDefault value to display in the CVV field.cardExpiryMonthNoDefault value to display as the card expirymonth.cardExpiryYearNoDefault value to display as the card expiryyear.customerNameNoDefault value to display in the Cardholder’sname field.customerAddressNoDefault value to display in the Cardholder’spostal address field.customerPostcodeNoDefault value to display in the Cardholder’spostcode field.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 15 -

HOSTEDINTEGRATION GUIDEcustomerEmailNoDefault value to display in the Cardholder’semail address field.customerPhoneNoDefault value to display in the Cardholder’sphone number field.cardCVVMandatoryNoForce a CVV to be entered.customerAddressMandatoryNoForce a postal address to be entered.customerPostcodeMandatoryNoForce a postcode to be entered.customerEmailMandatoryNoForce an email address to be entered.customerPhoneMandatoryNoForce a phone number to be entered.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 16 -

HOSTEDINTEGRATION GUIDEThis page is intentionally left blank.V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 17 -

HOSTEDINTEGRATION GUIDE1AVS/CV2 Checking1.1 BackgroundYou are able to request AVS and CV2 fraud checking on transactionsprocessed by the Payment Gateway.These fraud prevention checks are performed by the Acquirer whileauthorising the transaction. You can choose how to act on the outcome of thecheck (or even to ignore them altogether).1.1.1 AVS CheckingThe Address Verification System (AVS) uses the address details that areprovided by the Cardholder to verify the address is registered to the cardbeing used. The address and postcode are checked separately.1.1.2 CV2 CheckingCV2, CVV, or Card Verification Value is a 3 or 4 digit security code –Thecheck verifies the code is the correct one for the card used.For most cards the CVV is a 3 digit number to the right of the signature strip.For American Express cards this is a 4 digit number printed, not embossed,on the front right of the card.The AVS/CV2 checking preferences can be configured per Merchant Accountwithin the Merchant Management System (MMS). These preferences can beoverridden per transaction by sending one of the preference fieldsdocumented in section 4.3 which hold a comma separated list of the checkresponses that should be allowed to continue to completion. Responses not inthe list will result in the transaction being declined with a responseCode of 5(AVS/CV2 DECLINED).V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 18 -

HOSTEDINTEGRATION GUIDE1.2 Benefits & Limitations1.2.1 Benefits Instant: The results are available immediately and returned as part ofthe transaction Flexible: The checks can be managed independently allowing you theupmost control over how the results are used. Automatic: The checks can be configured to automatically declinetransaction where required.1.2.2 Limitations Not all countries supported: AVS is a UK scheme only: It is not possibleto check AVS on non-UK issued cards. Only Address numerics are checked: The non-numerical characters inthe billing address and postcode are not checked as part of the AVSchecks. Unable to check AVS/CV2 on company cards: If you accept companycredit cards you are not able to receive results on all company cards.This is due to the Acquirers not having access to this informationV10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 19 -

HOSTEDINTEGRATION GUIDE1.3 Request FieldsThese fields should be sent in addition to basic request fields in section 2.1.Field NameMandatory?DescriptioncustomerAddressYes1For AVS checking this must be a registeredbilling address for the card.customerPostCodeYes2For AVS checking this must be a registeredpostcode for the card.cardCVVYes3For CVV checking this must be the CardVerification Value printed on the card.avscv2CheckRequiredNo4Is AVS/CV2 checking required for thistransaction?Possible values are:N – Checking is not required.Y – Abort if checking is not enabled.cv2CheckPrefNo5List of cv2Check response values that areto be accepted, any other value will causethe transaction to be declined.Value is a comma separated list containingone or more of the following: not known,not checked, matched, not matched,partially matched.addressCheckPrefNo5List of addressCheck values that are tobe accepted, any other value will cause thetransaction to be declined.Value is a comma separated list containingone or more of the following not known,not checked, matched, not matched,partially matched.postcodeCheckPrefNo5List of postcodeCheck response valuesthat are to be accepted, any other valuewill cause the transaction to be declinedValue is a comma separated list containingone or more of the following: not known,not checked, matched, not matched,partially matched.Mandatory if AVS address checking is requiredMandatory if AVS postcode checking is required3 Mandatory if CV2 checking is required4 The default value is Y if AVS/CV2 checking is enabled on the Merchant Account, otherwise N5 If the value is not supplied than the default account preferences will be used.12V10.00For further help, please telephone 0845 241 9960 or emailinfo@retailmerchantservices.co.uk- 20 -

HOSTEDINTEGRATION GUIDE1.1 Response FieldsThese fields will be returned in addition to the AVS/CV2 request fields insection 4.3 and

The Merchant using the Gateway's services Acquirer The bank or financial institution used by the Merchant. Customer A customer of the Merchant making a payment etc. Cardholder The person who owns the payment card, normally the Customer. Merchant Account An account on the Gateway mapped to an Acquirer issued account. You/your The Merchant or .

Related Documents:

2. Merchant Banking 22 - 37 Introduction - Definition - Origin - Merchant Banking in India - Merchant Banks and Commercial Banks - Services of Merchant Banks - Merchant Bankers as Lead Managers - Qualities Required for Merchant Bankers - Guidelines for Merchant Bankers - Merchant Bankers' Commission - Merchant Bankers in the

mint payments - virtual terminal & merchant portal user guide 1.0 2 contents chapter 1: merchant portal - logging in 3 chapter 2: merchant portal - home page 6 chapter 3: merchant portal - setting up your company 7 chapter 4: merchant portal - user registration 10 chapter 5: merchant portal - mpos device setup 14 chapter 6: merchant portal - transaction, exporting data, refunds 15

Merchant Banking Definition, Origin, Merchant Banking in India, Merchant Banks, and Commercial Banks, Services of Merchant Banks, Qualities of Merchant Bankers in Market Making Process, Progress of Merchant Banking in India, Problems, Scope of Merchant Banking in India. 12 02 Mutual Funds, Factoring and Forfeiting Mutual Funds

Please sign at the Merchant Name line and complete the Merchant Name, Title, and Date. Page 10 - Merchant Services Agreement for SUB-MERCHANTS Please enter in Merchant Name. Page 11. Please enter in Merchant Name, Name, Title, Date, and Address. Please sign at Signature line. Please fax all pages to (888) 758-0587.

2.9 Pay Merchant Direct 2.9.1 Merchant Direct Pay Customer may pay a Merchant direct whenever a Merchant displays a Product Code for goods or services on offer. Here is how you can carry out direct payments. Step 1: Dial #111# and select "Pay Merchant Direct" Step 2: Select "Merchant Direct Pay" Step 3: Enter your PIN

The Merchant must upload a 2020 tax clearance certificate preferably on the day of registration. MERCHANT AFFILIATION MEMBERSHIP Challenge: The Merchant uploaded the proof of merchant association / membership documents for . but you marked it as no. Rectification Action: If the merchant belongs to any association please tick the yes box.

Premise Hosted Hosted % Savings: 3-Year TCO: 30% 5-Year TCO: 8% 50 A gent TCO Com parison: Hosted versus Premise ACD Only 250,000 200,000 150,000 100,000 50,000 0 Year 1 Year 2 Year 3 Year 4 Year 5 Premise Hosted Hosted % Savings: 3-Year TCO: 12% 5-Year TCO: 5% 50 A gent TCO Com parison: Hosted versus Premise ACD 0 50,000 100,000 .

Second’Grade’ ’ Strand:(ReadingInformational(Text’ Topics( Standard( “Ican ”statements( Vocabulary(Key(Ideas(and(Details ’ RI.2.1.’Ask’andanswer .