MasterPayment API. Version 2.8.0

Transcription

1 Version 2.8.0

2 Table of contents 1 Payments/transactions processing... 5 i. Payment/transaction processing parameters... 6 ii. Items array content... 9 iii. Control key computation Transaction status notification i. Transaction status and notification type ii. Notification configuration iii. Notification contents Redirect on transaction completion Payment gateway i. Invoking the gateway using test tool ii. Displaying gateway invocation code/url iii. Troubleshooting iv. List of transaction statuses and their meanings Credit Card i. Payment steps ii. Request example Three D secured transactions i. Payment request ii. Payment steps Lastschrift i. Payment steps ii. Request example Carte Bleue transactions i. Request example Sofortbanking i. Request example Ratenzahlung i. Payment steps ii. Set "Items sent" status iii. Request example Rechnungskauf transactions i. Short description ii. Merchants transactions statuses... 44

3 iii. Customer transactions statuses iv. Request example v. Rechnungskauf Set statuses Anzahlungskauf transactions i. Short description ii. Request example iii. Gateway screens Master Gateway i. Request example ii. Payment scenarios PIN gateway i. Request example ii. Payment steps Transactions Refund Payment API i. Payment/transaction processing parameters for credit card and carte bleue ii. Payment/transaction processing parameters for Lastschrift iii. Items array content iv. Control key computation v. Form example for credit card or carte bleue vi. Form example for Lastschrift vii. Response example Refund API i. Payment/transaction processing parameters for refund ii. Control key computation iii. Form example for refund iv. Response example Transaction service i. Request example ii. Response parameters iii. Response examples Payment, Preauthorize, Capture and Void operations i. Void request example ii. Capture request example iii. Responses... 84

4 Release History Release Description Date Changes 1.5 Initial version 10 - June Major release 20 - December Major release 15 - February Major release 27 - May Major release 17 - July Major release 25 - August Major release 26 - September Major release 12 - February Initial Workflow Description Recurrent methods description Rechnungskauf and anzahlungskauf descriptions credit card payment API description Lastschrift payment API description, refund API description Master gateway description Reatenkauf changes description, three d secure description, css path and form payment parameters added, refund procedure description Capture and void operations added for credit card.

5 1 Payments/transactions processing To start new transaction please include IFRAME tag within your site leading to MasterPayment gateway URL: ;or include the form with the payment post request in your payment page: <form method="post" action=" <input type="hidden" name="merchantname" value=" " /> <input type="hidden" name="txid" value=" " /> <input type="hidden" name="paymenttype" value=" " /> <input type="hidden" name="gatewaystyle" value=" " /> <input type="hidden" name="language" value=" " /> <input type="hidden" name="currency" value=" " /> <input type="hidden" name="basketvalue" value="" /> <input type="hidden" name="basketdescription" value="demo transaction" /> <input type="hidden" name="userid" value="" /> <input type="hidden" name="sex" value=" " /> <input type="hidden" name="firstname" value=" " /> <input type="hidden" name="lastname" value=" " /> <input type="hidden" name="street" value=" " /> <input type="hidden" name="housenumber" value=" " /> <input type="hidden" name="zipcode" value=" " /> <input type="hidden" name="city" value=" " /> <input type="hidden" name="country" value=" " /> <input type="hidden" name="birthdate" value=" " /> <input type="hidden" name="mobile" value=" " /> <input type="hidden" name=" " value=" " /> <input type="hidden" name="userip" value=" " /> <input type="submit" name="submitform" value="zeige Gateway" /> </form> Payment/transaction processing procedure has both mandatory and optional parameters (described further down within this document). Parameters should be passed: Using HTTP POST method if possible as hidden input element in self-submitting HTML form Using HTTP GET method if POST cannot be used by adding them as url-encoded string to end of the MasterPayment gateway URL (example: com/en/payment/gateway?param1=value1&param2=value2&... ) Note: We strongly recommend using HTTP POST method for gateway invocations. This recommendation is due to both HTTP GET limitations (URL length restrictions imposed by web browsers) and security reasons (with POST invocations none of the parameters are visible within URL used to invoke gateway). Mentioned URL length restrictions could cause problems on production systems that are very hard to detect and track down. Depending on browser that paying customer uses maximum length of the URL varies for example, in case of Internet Explorer v.9 it s 2048 characters. This limits total length of data that can be passed, when invoking gateway using HTTP GET method - in turn causing payment failures (often pretty mysterious at first glance). If gateway invocation contains many parameters, especially with lengthy data (like basket items descriptions), URL length limitation can lead to payment invocation failure; URL containing invocation parameters will be truncated by paying customer browser which, in turn, will cause some of the parameters to be missing - from the Masterpayment servers perspective. In such case, it s very likely that control key will not be passed to the server, or control key computed by the server will not match passed value. This leads to payment failure with ERR_INV_DATA status. Version 2.8.0, 2013/02/14, Page 5 of 84

6 i. Payment/transaction processing parameters Mandatory parameters are marked with. To keep in mind is that parameters are sent in UTF 8 encoding. Req. Parameter Data Type Description merchantname String (50) Merchant login name ( ). txid String (200) Merchant s transaction Id - unique string. basketdescription String (250) This value will be used as transaction description visible to the user on his bank account/credit card billing. basketvalue Int The amount to be charged in cents (in currency specified as separate parameter). currency String enum One of [ EUR, GBP, CHF, USD ]. Contact your account manager to enable different currencies for your merchant account. language String (2) Requested user interface language (double-character, i.e.: "DE", "EN") - must conform to the ISO 639 standard. userid String (100) Unique merchant s user ID string that identifies paying customer within merchant s shop system. sex String - enum User sex, one of [ man, woman, unknown ] firstname String (100) User first name. lastname String (150) User last name. street String (150) User address street name. housenumber String 50 User address house number. zipcode String 20 User address postal code. city String 100 User address city name. country String 50 User address - country name (or code) according to ISO 3166 standard. If empty then default value is used - DE birthdate String(10) User birth date - format: "YYYY-MM-DD". mobile String (20) User mobile phone number, including country code prefix. String (120) User - used for transaction status confirmation. userip String (20) IP number used by user format: "##0.##0.##0.##0". paymenttype String enum One of [ credit_card, debit_card, elv, ratenzahlung, rechnungskauf, Version 2.8.0, 2013/02/14, Page 6 of 84

7 anzahlungskauf, sofortbanking ]. gatewaystyle String - enum One of [ standard, mobile, pinmobile etc]. UrlPatternSuccess String (1000) URL Pattern for payment success notification, meant to POST the transaction result data to the merchant provided URL, overrides txsuccess - see "Transaction status notification" section (also, callback method will be overridden to POST) UrlPatternFailure String (1000) URL Pattern for payment failure notification, meant to POST the transaction result data to the merchant provided URL, overrides txfailure - see "Transaction status notification" section (also, callback method will be overridden to POST) UrlRedirectSuccess String (1000) URL to which user browser should be redirected after payment ended successfully meant to redirect the end customer back to the merchant shop, (see "Redirect on transaction completion"). UrlRedirectCancel String (1000) URL to which user browser should be redirected after payment was canceled by user, meant to redirect the end customer back to the merchant shop if not specified, UrlRedirectFailure parameter value will be used (see "Redirect on transaction completion"). UrlRedirectFailure String (1000) URL to which user browser should be redirected after payment process failed if not specified, UrlRedirectCancel parameter value will be used (see "Redirect on transaction completion") showcanceloption String (bool) Boolean value (true/1 or false/0) - if true, cancel buttons will be shown on user input forms during payment process installmentscount Int Number of installments optional/required; meaningful and required only for one of following payment types: ratenzahlung, finanzierung. installmentsfreq Int Number of days between installments optional/required; meaningful only for one of following payment types: ratenzahlung, finanzierung. Any of those payment types requires this or installmentsperiod parameter to be specified (but not both of them). installmentsperiod String - enum One of [ monthly, end_of_month ] optional/required; meaningful only for one of following payment types: retenzahlung, finanzierung. Any of those payment types requires this or installmentsfreq parameter to be specified (but not both of them). recurrentperiod String - enum One of [ weekly, monthly, quarterly, yearly ] required fields for recurring transactions; meaningful only for one of following payment types: recurring lastschrift ( elv_recurrent ), recurring credit card ( cc_recurrent ). Any of those payment types requires this parameter to be specified. mintxamount Int Optional parameter set by default to 1, which means the minimum number of repeated transactions required for the recurrent billing. Version 2.8.0, 2013/02/14, Page 7 of 84

8 firstbill Int Optional parameter set by default to the basket value, which means the amount of the first recurrent transaction. paymentdelay Int Number of days the payment should be delayed optional/required; meaningful and required only for payment type deferred_debit. invoiceno String (50) Invoice number optional, generated by system if not specified; meaningful only for one of following payment types: rechnungskauf, anzahlungskauf. customerno String (100) Customer number for use within invoice optional, if not specified userid parameter or system-generated value will be used; meaningful only for one of following payment types: rechnungskauf, anzahlungskauf. duedays Int Number of days before invoice payment is due optional/required; meaningful and required only for one of following payment types: rechnungskauf, anzahlungskauf. createaspending String (bool) Boolean value ("true"/"1" or "false"/"0") optional/required; meaningful and required only for one of following payment types: rechnungskauf, anzahlungskauf. If true, invoice payment will be created as pending payment due date will be computed at the moment when payment is manually triggered by merchant. groupsize Int Number of transactions created by gateway optional; meaningful only for payment type elv_triggered. items Array Array of Item entities (see "Items array content"). Content of this field can be used by the system to create more informative transaction description visible to the user on his bank account/credit card billing. controlkey String (100) Check sum of other form fields concatenated together with merchant Secret Key. Item index (number) should be placed within square brackets, as shown in table below (by replacing n with appropriate index, for example: "items[1][itemprice]" parameter holds a price of second item in items array). csspath String (255) Parameter used for merchant customized CSS style. Overrides the existing gateway style elements. disable form String (bool) Boolean value (true/1 or false/0) - if true, end customer will not see the input step during payment process. sofortsenderholder String (30) Sofort account holder name, if provided, together with the other 2 sofort specific parameters (sofortsenderaccountnumber, sofortsenderbankcode), end customer gets redirected to sofortbanking site without seeing the masterpayment gateway. sofortsenderaccount String (30) Sofort account holder name, if provided, together with the other 2 sofort specific Number parameters (sofortsenderholder, sofortsenderbankcode), end Version 2.8.0, 2013/02/14, Page 8 of 84

9 customer gets redirected to sofortbanking site without seeing the masterpayment gateway. sofortsenderbankcod String (30) Sofort account holder name, if provided, together with the other 2 sofort specific e parameters (sofortsenderholder, sofortsenderaccountnumber), end customer gets redirected to sofortbanking site without seeing the masterpayment gateway. operation String (2) The kind of operation that will be performed - if null or DB is received a debit request will be performed, if PA is received, preauthorization will be performed. Credit card payment method only. ii. Items array content Items array is composed of zero of more entities: Req. Parameter Data Type Description items[n][itemdescription] String (100) Name and/or description of the basket item. items[n][itemamount] Double Amount purchased. items[n][itemprice] Int In cents. Items are indexed from 0. Item index (number) should be placed within square brackets, as shown in table above (by replacing n with appropriate index, for example: "items[0][itemamount]" parameter holds the amount of items of the first item in items array). Version 2.8.0, 2013/02/14, Page 9 of 84

10 iii. Control key computation To compute control key: 1. Do not use url encoded parameters. 2. Create array of all parameters that will be passed to the gateway (with exception control Key of parameter). 3. Sort the array by parameter names, ascending (take into consideration that parameter names are case sensitive). 4. Create temporary string by concatenating all parameter values ( delimited) from the sorted array in effect, string will contain parameter values ordered according to their names, ascending. Parameters should not be url encoded. 5. Concatenate delimiter ( ) and merchants Secret Key to the end of the temporary string. 6. Compute MD5 checksum of the temporary string make sure that byte array used for MD5 computation is created from temporary string. 7. Add computed checksum as a value of "control Key" field (this should be 32 characters long string 16 bytes, hex encoded). Common control key computation errors: Parameters in control string are url encoded. Parameters are not sorted alphabetically Empty parameters are used in control key computation. Wrong control string example "demo+transaction demo+city DE EUR demotransaction%40fin- bet.net Max standard 12 DE Schmidt demo%40fin- bet.net credit_card unknown true demo+street+name tx d7 e5869-7afd-451a-a887-8e6a1530d4ea" Version 2.8.0, 2013/02/14, Page 10 of 84

11 Correct computation example: Parameter name basketdescription Parameter value demo transaction basketvalue 101 country currency firstname gatewaystyle language lastname merchantname DE EUR Max standard DE Schmidt mobile paymenttype txid credit_card tx userid user street demo street name housenumber 12 zipcode city demo city userip sex unknown birthdate mobile Version 2.8.0, 2013/02/14, Page 11 of 84

12 Temporary string: "demo transaction demo city DE EUR Max standard 12 DE Schmidt credit_card unknown true demo street name tx d7e5869-7afd-451a-a887-8e6a1530d4ea" Control key: "04be2b0aff6edd4bca7f163f2819d10c" Gateway URL: Value=101&basketDescription=demo+transaction&userId= &sex=unknown&firstname=Max&lastn ame=schmidt&str eet=demo+street+name&housenumber=12&zipcode=21231&city=demo+city&country=de&birthdate= &mobile= & =demotransaction%40finbet.net&userIp= &showCancelOption=true&controlKey=04be2b0aff6edd4bca7f163f2819d10c " Version 2.8.0, 2013/02/14, Page 12 of 84

13 2 Transaction status notification Masterpayment gateway sends transaction final status notifications back to the Merchant s system by executing HTTP POST or GET (option is set in the merchant administration panel) call to either txsuccess URL or txfailure URL, depending on the transaction status. i. Transaction status and notification type Notifications will be sent for one of the following statuses: Status When Callback URL PENDING SCHEDULED Gateway invocation succeeded, payment is waiting for manual activation by merchant (i.e. rechnungskauf payments). Gateway invocation succeeded, payment is scheduled for automatic execution (i.e. rechnungskauf payments). txsuccess txsuccess SUCCESS Payment processed successfully. txsuccess CANCELLED Payment cancelled by customer. txfailure TIMED_OUT Payment has timed out waiting for input from customer. txfailure REFUSED_RISK Payment was refused due to risk assessment. txfailure FAILED Payment has failed. txfailure Version 2.8.0, 2013/02/14, Page 13 of 84

14 ii. Notification configuration Both URLs can be configured via "My Account" / "Gateway Settings" panel (fields "URL pattern for confirming transaction failure" and "URL pattern for confirming transaction success" respectively). Also notification callback method can be configured using "Callback method" field (to specify POST or GET). To set up notifications please log in and navigate to your gateway settings: Note: Settings entered using this page are required and used by default for all payments. If txsuccess/txfailure pattern URLs are not specified, gateway will not open and all transactions created with it will end with status ERR_SETTINGS. Version 2.8.0, 2013/02/14, Page 14 of 84

15 Enter appropriate information into notification callbacks related fields (marked on screenshot below): After entering required data, please make sure to click "Senden" ("Submit") button. Version 2.8.0, 2013/02/14, Page 15 of 84

16 iii. Notification contents Callback notifications can contain following parameters: Lp. Financial Name Description 1 TX_ID Merchant s transaction ID 2 METHOD Payment method used credit_card, debit_card, elv, ratenzahlung, rechnungskauf, anzahlungskauf, sofortbanking. 3 CUST_ID Merchant s customer ID (empty if not passed to the payment gateway) 4 STATUS Transaction status code 5 STATUS_TEXT Additional status description text - can be empty 6 INVOICE_NO Invoice number to include on invoice sent to the paying customer (valid and not empty only if payment method is invoice ) 7 CUSTOMER_NO Unique customer number for use on invoices; this is either value of merchant s customer ID passed to the gateway invocation or generated value (valid and not empty only if payment method is invoice ) 8 CURRENCY Transaction currency 9 VALUE Transaction value expressed in 1/100 of transaction currency 10 FEE Transaction fee in euro cents 11 DISAGIO Transaction disagio expressed in 1/100 of transaction currency 12 FINAL_VALUE Transaction final value expressed in 1/100 of transaction currency 13 CTRL_KEY Control key of all parameters see below. 14 CTRL_KEY_SH ORT Control key of TX_ID, METHOD and STATUS parameters, computed using method described below. Depending on the callback method used, parameters are: for POST method: All available parameters are passed within post data. No ${PARAM_NAME} parameters should be present in the post callback. for GET method: Version 2.8.0, 2013/02/14, Page 16 of 84

17 Inserted into txsuccess/txfailure URLs by replacing occurrences of ${PARAM_NAM E} with parameter value (if parameter named "PARAM_NAME" exists and is available). Resulting string will be URL -encoded before making HTTP GET call. Example pattern: would be evaluated to: If a parameter is empty or has no value (i.e. STATUS_TEXT or FINAL_VALUE), it s placeholder in the URL will be deleted for example will be evaluated to: Control key computation will be made from the following string: If financial parameters are available: "${TX_ID} ${METHOD} ${STATUS_TEXT} ${CUST_ID} ${STATUS} ${CURRENCY} ${ VALUE} ${FEE} ${DISAGIO} ${FINA L_VALUE} ${INVOICE_NO} ${CUSTOMER_NO} ${SECRET_KEY}" If financial parameters are not available: "${TX_ID} ${METHOD} ${STATUS_TEXT} ${CUST_ID} ${STATUS} ${INVOICE_NO} ${CUSTOMER_NO} ${SECRET_KEY}" Control key short computation is made from the following string: "${TX_ID} ${METHOD} ${STATUS} ${SECRET_KEY}" Note: Depending on the "financial transaction properties will not be available in transaction callback info" check box value (from "My Account" / "Gateway Settings" panel), parameters marked as "Financial" might not be available. Version 2.8.0, 2013/02/14, Page 17 of 84

18 3 Redirect on transaction completion Depending on invocation parameters, MasterPayment gateway may redirect user browser (or the iframe it s displayed within) to specified URL. This functionality is optional and executed only if one or more of the UrlRedirect parameters has been specified see "Payment/transaction processing parameters" table for their complete list and description. All of those URL s can use prefix "target-parent:" (for example target-parent: if so, gateway will assume that it s loaded within an iframe and will redirect page containing it to the specified URL in full window size. Otherwise it assumes it s loaded as a stand-alone web page, thus redirecting current document only (inside the iframe). Version 2.8.0, 2013/02/14, Page 18 of 84

19 4 Payment gateway Masterpayment portal is equipped with a utility page for executing gateway invocations available at address To invoke gateway using this page and your gateway settings please log in to the service and click menu item marked on the following screenshot: The test gateway simulates the iframe payment process, therefore it illustrates the step by step payment process for the end customer if you use iframe gateway integration. To make the payment process more flexible for merchants we defined a parameter - CSS path - which allows the merchant to have his own style for the payment process. For merchants who don t need a special style we have the standard gateway styles (standard for regular payments, mobile for payment on mobile phones, pinmobile for payments on mobile phones with option of storing payment methods by providing a pin) which are loaded by default, the CSS path can override some of the style elements. Version 2.8.0, 2013/02/14, Page 19 of 84

20 i. Invoking the gateway using test tool Clicking on "Gateway" menu option (after logging in) will bring up gateway invocation tool visible on the following screenshot (too keep in mind: the amount of the transactions must not be less than 101 Cent): Besides info labels and edit boxes for entering most important invocation parameters this tool contains: "Weitere Gateway-Settings anzeigen"/"show additional gateway settings" label for displaying/hiding rest of possible invocation parameters. "Zeige Gateway"/"Show Gateway" button for invoking the gateway. "Zeige Code"/"Show Code" button for displaying: o o o o HTML form for invoking gateway with HTTP POST method (and entered invocation parameters). URL for invoking gateway using HTTP GET method (and entered invocation parameters). Control key computed for entered parameters and current secret key. Temporary string used for control key computation. To invoke gateway please enter invocation parameters (possibly extending the view by clicking "Weitere Gateway- Settings anzeigen"/"show additional gateway settings" label) and then click on "Zeige Gateway"/"Show Gateway" button. Version 2.8.0, 2013/02/14, Page 20 of 84

21 ii. Displaying gateway invocation code/url To display gateway invocation code/url for entered invocation parameters click on "Zeige Code"/"Show Code" button. This will bring up "Gateway Code" panel (content will differ, depending on entered gateway invocation parameters): Version 2.8.0, 2013/02/14, Page 21 of 84

22 iii. Troubleshooting Successful gateway invocation requires following conditions to be met: Your account has to be marked as "active" by MasterPayment staff. Gateway settings must have values for txsuccess/txfailure callback URLs (see "Transaction status notification"). Selected payment method has to be enabled (by MasterPayment staff). All invocation parameters marked as required in "Payments/transactions processing with iframe" paragraph have to be passed (with non-empty values). Control key passed as invocation parameter must be valid has to have a value identical to the one computed by the Masterpayment server (and shown in "Gateway Code" panel after entering invocation parameters in the gateway test tool and clicking "Show Code" button). Failing to meet any of those conditions will cause payment failure with one of failure/error statuses. Gateway invocation tool allows for easy detection of first three possible causes for payment failure. If your account set up is incomplete, was not activated yet or selected payment method is unavailable to you, warning message box will appear above gateway invocation tool panel: Version 2.8.0, 2013/02/14, Page 22 of 84

23 iv. List of transaction statuses and their meanings ERR_INV_DATA - basket value to small, no basket description or no user IP (or other parameters marked as required), or sent with wrong values, like country codes or language codes ( DEU instead of DE ) ERR_INV_METHOD - this payment method is not available for the merchant ERR_INV_SETTINGS - no pattern URLs (success or failure) are defined in the gatewa y settings or dent in the payment request ERR_INACTIVE - merchant has not been activated by admin INIT - CTRL_KEY matched, required parameters were sent (newly initialized, not processed yet) NEW - received data contains valid CTRL_KEY, required parameters exists and data was successfully validated EDIT - on retry payment, on receiving invalid data when end user fills payment forms or waiting for user input EDIT_ADDR_DATA - waiting for user to input(or to confirm) address data RISK_CHECKS - risk check process was started, awaiting risk checks to complete RISK_CHECKED - risk process has ended and risk is acceptable REFUSED_RISK - risk process has ended and risk is not acceptable THREE_D - waiting for ACK response from ACS site (user inputs 3D secure code and ACS site validates it), for card payments only SUCCESS - transaction finished, money was billed by provider FAILURE - transaction finished, money was not withdrawn by provider (invalid data sent to provider, or provider decided to decline that transaction) CANCELLED - end user decided to cancel payment process or void operation has ben performed after preauthorize. PREAUTHORIZED - payment preauthorize request send, waiting for capture or void INVO_PAID - rechnungskauf and anzahlungskauf transactions which have been paid by the end customer REVOKED - refunded transactions which do not appear in reports (refund and tx both do not appear in the reports) TIMED_OUT - time out occurred during payment execution No status - invalid CTRL_KEY (no callback is made, transaction is not saved in database) Version 2.8.0, 2013/02/14, Page 23 of 84

24 5 Credit Card i. Payment steps Step 1 - Submission of the payment data by the end customer on masterpayment. Step 2a - Transaction procession result. Version 2.8.0, 2013/02/14, Page 24 of 84

25 If the customer doesn t want to receive the confirmation , he can click on "Weiter". Then he will be redirected to the merchant SuccessRedirectUrl sent by merchant in the payment request or set in the merchant panel, if none is sent in the payment request. If there is no RedirectUrl, we show the default success page. Step 2b - The default success page. Step 2c - Transaction failed and if no FailureRedirectURL is available (in the merchant setting or in the payment request), we again get the default page, in this case for failure. Version 2.8.0, 2013/02/14, Page 25 of 84

26 ii. Request example <form method="post" action=" <input type="hidden" name="merchantname" -bet.net" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="paymenttype" value="credit_card" /> <input type="hidden" name="gatewaystyle" value="standard" /> <input type="hidden" name="language" value="de" /> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="basketvalue" value="101" /> <input type="hidden" name="basketdescription" value="demo transaction" /> <input type="hidden" name="userid" value=" " /> <input type="hidden" name="sex" value="unknown" /> <input type="hidden" name="firstname" value="max" /> <input type="hidden" name="lastname" value="schmidt" /> <input type="hidden" name="street" value="demo street name" /> <input type="hidden" name="housenumber" value="12" /> <input type="hidden" name="zipcode" value="21231" /> <input type="hidden" name="city" value="demo city" /> <input type="hidden" name="country" value="de" /> <input type="hidden" name="birthdate" value=" " /> <input type="hidden" name="mobile" value=" " /> <input type="hidden" name=" " -bet.net" /> <input type="hidden" name="userip" value=" " /> <input type="hidden" name="showcanceloption" value="true" /> <input type="hidden" name="disable form" value="false" /> <input type="submit" name="submitform" value="zeige Gate way" /> </form> Version 2.8.0, 2013/02/14, Page 26 of 84

27 6 Three D secured transactions Depending on the settings merchants have agreed on with their account managers, they can process payments with three d secure cards. A payment request with a three d secure card from the merchant point of view is the same as for a regular card. The difference is viewable for the end customer, as once the user fills in his card details, he is redirected to the ACS site, where he types in his security key (password). Transaction is processed and the user is redirected back to masterpayment with the transaction processing result information. i. Payment request <form method="post" action=" <input type="hidden" name="merchantname" value="demo@fin -bet.net" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="paymenttype" value="credit_card" /> <input type="hidden" name="gatewaystyle" value="standard" /> <input type="hidden" name="language" value="de" /> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="basketvalue" value="101" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="basketdescription" value="demo transaction" /> <input type="hidden" name="userid" value=" " /> <input type="hidden" name="sex" value="unknown" /> <input type="hidden" name="firstname" value="max" /> <input type="hidden" name="lastname" value="schmidt" /> <input type="hidden" name="street" value="demo street name" /> <input type="hidden" name="housenumber" value="12" /> <input type="hidden" name="zipcode" value="21231" /> <input type="hidden" name="city" value="demo city" /> <input type="hidden" name="country" value="de" /> <input type="hidden" name="birthdate" value=" " /> <input type="hidden" name="mobile" value=" " /> <input type="hidden" name=" " value="demotransaction@fin -bet.net" /> <input type="hidden" name="userip" value=" " /> <input type="hidden" name="showcanceloption" value="true" /> <input type="hidden" name="disable form" value="false" /> <input type="submit" name="submitform" value="zeige Gateway" /> </form> Version 2.8.0, 2013/02/14, Page 27 of 84

28 ii. Payment steps Step 1 - End customer fills in his credit card data. Step 2 - card is three d secure enrolled and end customer is redirected to ACS site. Version 2.8.0, 2013/02/14, Page 28 of 84

29 Step 3 - Three d secure authentication. Step 4 - End customer is redirected back to masterpayment and payment is being processed. Version 2.8.0, 2013/02/14, Page 29 of 84

30 Step 5 - Successful completion of a three d secure credit card transaction. Version 2.8.0, 2013/02/14, Page 30 of 84

31 7 Lastschrift i. Payment steps Step 1 - Submission of the payment data by the end customer on masterpayment. Step 2 - Submission of the personal data, auto completed with data sent by the merchant in the payment request. Version 2.8.0, 2013/02/14, Page 31 of 84

32 Step 3a - Transaction procession result. If the customer doesn t want to receive the confirmation , he can click on "Weiter". Then he will be redirected to the merchant SuccessRedirectUrl sent by merchant in the payment request or set in th e merchant panel, if none is sent in the payment request. If there is no RedirectUrl, we show the default success page. Step 3b - The default success page. Step 3c - Transaction failed and if no FailureRedirectURL is available (in the merchant setting or in the payment request), we again get the default page, in this case for failure. Version 2.8.0, 2013/02/14, Page 32 of 84

33 ii. Request example <form method="post" action=" <input type="hidden" name="merchantname" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="paymenttype" value="ratenzahlung" /> <input type="hidden" name="gatewaystyle" value="standard" /> <input type="hidden" name="language" value="en" /> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="basketvalue" value="600" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="basketdescription" value="basket description" /> <input type="hidden" name="sex" value="unknown" /> <input type="hidden" name="country" value="de" /> <input type="hidden" name="installmentscount" value="2" /> <input type="hidden" name="installmentsfreq" value="30" /> <input type="hidden" name="showcanceloption" value="false" /> <input type="hidden" name="disable form" value="false" /> <input type="submit" name="submitform" value="zeige Gateway" /> </form> Version 2.8.0, 2013/02/14, Page 33 of 84

34 8 Carte Bleue transactions From the end customer point of view, carte bleue (debit_card) transactions are the same as credit card transactions. The gateway looks the same, only the brand is different. Version 2.8.0, 2013/02/14, Page 34 of 84

35 i. Request example <form method="post" action=" <input type="hidden" name="merchantname" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="paymenttype" value="debit_card" /> <input type="hidden" name="gatewaystyle" value="standard" /> <input type="hidden" name="language" value="de" /> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="basketvalue" value="101" /> <input type="hidden" name="basketdescription" value="demo transaction" /> <input type="hidden" name="userid" value=" " /> <input type="hidden" name="sex" value="unknown" /> <input type="hidden" name="firstname" value="max" /> <input type="hidden" name="lastname" value="schmidt" /> <input type="hidden" name="street" value="demo street name" /> <input type="hidden" name="housenumber" value="12" /> <input type="hidden" name="zipcode" value="21231" /> <input type="hidden" name="city" value="demo city" /> <input type="hidden" name="country" value="de" /> <input type="hidden" name="birthdate" value=" " /> <input type="hidden" name="mobile" value=" " /> <input type="hidden" name=" " -bet.net" /> <input type="hidden" name="userip" value=" " /> <input type="hidden" name="showcanceloption" value="true" /> <input type="submit" name="submitform" value="zeige Gateway" /> </form> Version 2.8.0, 2013/02/14, Page 35 of 84

36 9 Sofortbanking This is how the sofortbanking gateway looks like: have one. The end customer has to have a sofortbanking account to be able to pay. The merchant doesn t need to If you want to have your customers redirected directly to the sofortbanking site, without seeing the masterpayment gateway, you can send the 3 sofort related paramaters (), and when we receive them we automatically redirect to sofort. Version 2.8.0, 2013/02/14, Page 36 of 84

37 i. Request example <form method="post" action=" <input type="hidden" name="merchantname" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="paymenttype" value="sofortbanking" /> <input type="hidden" name="gatewaystyle" value="standard" /> <input type="hidden" name="language" value="en" /> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="basketvalue" value="101" /> <input type="hidden" name="basketdescription" value="basket description" /> <input type="hidden" name="sex" value="unknown" /> <input type="hidden" name="country" value="de" /> <input type="hidden" name="showcanceloption" value="f alse" /> <input type="submit" name="submitform" value="zeige Gateway" /> </form> Version 2.8.0, 2013/02/14, Page 37 of 84

38 10 Ratenzahlung Ratenzahlung is a payment method which allows the end customer to pay the total transaction amount in an merchant specified number of installments, with merchant specified period between installments. First installment is billed at the successful submission of the payment request in the gateway. Second installment is billed after merchant sets the transaction status to "itemsent". This status can be set in 3 ways: automatically, after a merchant specified numbe r of days (by default set to 5), upon url request or upon button click in the admin module. i. Payment steps Ratenzahlung step 1 - Show to the end customer the number of installments and the period between them chosen by the merchant Version 2.8.0, 2013/02/14, Page 38 of 84

39 Ratenzahlung step 2 - Show how the total amount will be split in periods and the next payments due dates Version 2.8.0, 2013/02/14, Page 39 of 84

40 Ratenzahlung step 3 - Billing information, Lastschrift form, only the first payment amount will be billed. Ratenzahlung step 5 - Address information Ratenzahlung step 5 - Payment successfully completed. Version 2.8.0, 2013/02/14, Page 40 of 84

41 ii. Set "Items sent" status As mentioned above, this status can be set: On button click in the transaction details (by merchant or admin) Or automatically, after the merchant set default period of days passes In this case, after 5 days since the date the ratenzahlungskauf transaction was submitted in the gateway, the status will be set to items sent. Or upon url request <form action= method= post > <input type="hidden" name= merchantname value= [email protected] /> <input type="hidden" name= txid value= tx /> <input type="hidden" name= mptxid value= /> <input type="hidden" name= controlkey value= d4510f4c12e13fd4b4c15d f /> <input type="submit" name="submitform" value="item Sent" /> </form> Response is "OK" if the status was updated or "NOK" is not. Version 2.8.0, 2013/02/14, Page 41 of 84

42 Both, merchant transaction ids and/or masterpayment transaction ids are accepted. At least one of the 2 parameters should be provided. iii. Request example <form method="post" action=" <input type="hidden" name="merchantname" value="demo@fin -bet.net" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="paymenttype" value="ratenzahlung" /> <input type="hidden" name="gatewaystyle" value="standard" /> <input type="hidden" name="language" value="de" /> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="basketvalue" value="10050" /> <input type="hidden" name="basketdescription" value="demo transaction" /> <input type="hidden" name="userid" value=" " /> <input type="hidden" name="sex" value="unknown" /> <input type="hidden" name="firstname" value="max" /> <input type="hidden" name="lastname" value="schmidt" /> <input type="hidden" name="street" value="demo street name" /> <input type="hidden" name="housenumber" value="12" /> <input type="hidden" name="zipcode" value="21231" /> <input type="hidden" name="city" value="demo city" /> <input type="hidden" name="country" value="de" /> <input type="hidden" name="birthdate" value=" " /> <input type="hidden" name="mobile" value=" " /> <input type="hidden" name=" " value="demotransaction@fin -bet.net" /> <input type="hidden" name="userip" value=" " /> <input type="hidden" name="installmentscount" value="6" /> <input type="hidden" name="installmentsfreq" value="30" /> <input type="hidden" name="showcanceloption" value="true" /> <input type="submit" name="submitform" value="zeige Gateway" /> </form> Version 2.8.0, 2013/02/14, Page 42 of 84

43 11 Rechnungskauf transactions i. Short description Rechnungskauf s main feature is that the payment is delayed for a specified amount of days. The merchant can send the due days parameter via url (using POST), set it manually in his admin or set a fixed number of days. This is also available for other parameters, as shown in the table below. Note: For merchant status ItemsSent / DELIVERED (10) the following parameters in URL request using POST command are required: 1. merchantname - merchant authentication 2. txid or mptxid - merchant transaction id or masterpayment transaction id at least one of them is required 3. controlkey the computed control key out of the request parameters to set the status using the following url < form action= method= post > <input type="hidden" name= merchantname value= [email protected] /> <input type="hidden" name= txid value= tx /> <input type="hidden" name= mptxid value= /> <input type="hidden" name= controlkey value= 66241f4c63820a6e30c /> <input type="submit" name="submitform" value="item Sent" /> </form> For customer status NO_PAYMENT (50) the following parameters in URL request using POST command are required: 1. merchantname - merchant authentication 2. txid or mptxid - merchant transaction id or masterpayment transaction id at least one of them is required 3. date - the due date of the payment 4. controlkey the computed control key out of the request parameters to set the status using the following url <form action= method= post > <input type="hidden" name= merchantname value= [email protected] /> <input type="hidden" name= txid value= tx /> <input type="hidden" name= mptxid value= /> <input type="hidden" name= date value= /> <input type="hidden" name= controlkey value= 1a8b8404b51a14c4d780a1dba26cc8c7 /> <input type="submit" name="submitform" value="invoice due" /> </form> Version 2.8.0, 2013/02/14, Page 43 of 84

44 ii. Merchants transactions statuses Status APPROVED (00) DELIVERED (10) IRREVOCABLE (20) PAYOUT_REQUESTED (40) PAYOUT_SENT (50) PAYOUT_COMPLETE (60) LEGAL_ISSUES (70) REFUNDED (90) Meaning Gateway invocation succeeded, payment is waiting for activation. The merchant has sent out the merchandise. This parameter can be sent by the merchant via url (using POST), set manually in his admin or set as a defined value. In case the merchant sends this parameter, it will override the default value of 5 days The default value is 14 days since the merchandise was sent and the transaction wasn t revoked by the user. The number of days can be set in the admin. Payment is requested 5 days since the transaction was active. The number of days can be set in the admin. Payment sent from the customer s account. Payment was completed successfully. The merchant can set the status manually from his admin. Full refund inserted. iii. Customer transactions statuses Status NOT_CHARGED (10) PURCHASE_FINAL (20) ELV (33) BANK_TRANSFER (30) CREDIT_CARD (31) SOFORT_UEBERWEISUNG (32) PAYMENT_COMPLETE (40) NO_PAYMENT (50) ELV_BANK_CHARGEBACK (60) ELV_USER_CHARGEBACK (61) Condition Status set automatically, when the transaction is created. The default value is 5 days since the transaction is created and wasn t revoked by the user. Status set automatically when the user pays via Lastschrift. Status set manually when the user pays via bank transfer. Status set automatically when the user pays via Credit Card. Status set automatically when the user pays via Sofortüberweisung. The payment was made successfully; the money cannot be taken away. Status set depending on merchant status DELIVERED. The number of days can be set in the admin or sent via url (using POST) Status set manually by the merchant, when the end customer account didn t have the amount available after the payment was made via Lastschrift. Status set manually by the merchant, when the end customer Version 2.8.0, 2013/02/14, Page 44 of 84

45 requested a charge back after the payment was made via Lastschrift. CREDIT_CARD_CHARGEBACK (62) _REMINDER (71) Status set manually by the merchant, when the end customer requested a charge back after the payment was made via Credit Card. Status set automatically 10 days after ELV_BANK_RETRY or NOT_PAID_BUT_DUE, unless successful payment was made. SECOND_ _REMINDER (72) Status set automatically 10 days after first _REMINDER LAST_ _REMINDER (73) POSTAL_REMINDER (74) SECOND_POSTAL_REMINDER (75) INKASSO (76) THIRD_PARTY (100) REVOKED (200) REFUNDED (250) Status set automatically 10 days after SECOND_ _REMINDER Status set automatically 14 days after LAST_ _REMINDER. Status set automatically 14 days after POSTAL_ _REMINDER. Status set manually, available only after 2ND_POSTAL_MAIL_REMINDER Status set manually, only after 2ND_POSTAL_MAIL_REMINDER, it means that the invoice vas sold to a third party. Payment revoked by customer. Full refund inserted. The end customer can choose the following payment methods with rechnungskauf: credit card, lastschrift, bank transfer, sofortüberweisung. Both, merchant and customer manual statuses can be changed from the merchant s administration module. Version 2.8.0, 2013/02/14, Page 45 of 84

46 iv. Request example <form method="post" action=" <input type="hidden" name="merchantname" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="paymenttype" value="rechnungskauf" /> <input type="hidden" name="gatewaystyle" value="afterbuy" /> <input type="hidden" name="language" value="de" /> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="basketvalue" value="101" /> <input type="hidden" name="basketdescription" value="demo transaction" /> <input type="hidden" name="userid" value=" " /> <input type="hidden" name="sex" value="unknown" /> <input type="hidden" name="firstname" value="max" /> <input type="hidden" name="lastname" value="schmidt" /> <input type="hidden" name="street" value="demo street name" /> <input type="hidden" name="housenumber" value="12" /> <input type="hidden" name="zipcode" value="21231" /> <input type="hidden" name="city" value="demo city" /> <input type="hidden" name="country" value="de" /> <input type="hidden" name="birthdate" value=" " /> <input type="hidden" name="mobile" value=" " /> <input type="hidden" name=" " /> <input type="hidden" name="userip" value=" " /> <input type="submit" name="submitform" value="zeige Gateway" /> </form> Version 2.8.0, 2013/02/14, Page 46 of 84

47 v. Rechnungskauf Set statuses All statuses are set to the system default, which is 5 days after the transaction is successfully completed in the gateway for the status (20), for example. Your administrator can set the way you wish to set some of the statuses. Merchant status (10) and customer status (50) can be set upon url request (POST), manually in the merchant admin or set to a number of days you define by your administrator. Merchant statuses (20) and (40) can be set by your administrator to a number of days you define. Version 2.8.0, 2013/02/14, Page 47 of 84

48 12 Anzahlungskauf transactions i. Short description Anzahlungskauf s main feature is that the payment is split in 2 sub-payments, first one paid in the gateway by the user when the transaction is created and the second one delayed for a specified number of days, treated like a rechnungskauf transaction. The first and second payment amounts are set in percent in the admin or by the merchant in the registration process. Anzahlungskauf percentage shown in the merchant admin. Both, first and second payment can be processed via credit card, lastschrift or sofortüberweisung. The second part can be paid via bank transfer as well. The merchant can send the due days parameter via url (using POST), set it manually in his admin or set a fixed number of days. This is also available for o ther parameters, same as for rechnungskauf payment method. Note: For merchant status ItemsSent / DELIVERED (10) the following parameters in URL request using POST command are required: 1. merchantname - merchant authentication 2. txid or mptxid - merchant transaction id or masterpayment transaction id at least one of them is required 3. controlkey the computed control key out of the request parameters to set the status using the following url < form action= method= post > <input type="hidden" name= merchantname value= [email protected] /> <input type="hidden" name= txid value= tx /> <input type="hidden" name= mptxid value= /> <input type="hidden" name= controlkey value= 66241f4c63820a6e30c /> <input type="submit" name="submitform" value="item Sent" /> </form> Version 2.8.0, 2013/02/14, Page 48 of 84

49 For customer status NO_PAYMENT (50) the following parameters in URL request using POST command are required: 1. merchantname - merchant authentication 2. txid or mptxid - merchant transaction id or masterpayment transaction id at least one of them is required 3. date - the due date of the payment 4. controlkey the computed control key out of the request parameters to set the status using the following url <form action= method= post > <input type="hidden" name= merchantname value= [email protected] /> <input type="hidden" name= txid value= tx /> <input type="hidden" name= mptxid value= /> <input type="hidden" name= date value= /> <input type="hidden" name= controlkey value= 1a8b8404b51a14c4d780a1dba26cc8c7 /> <input type="submit" name="submitform" value="invoice due" /> </form> All statuses are set to the system default, which is 5 days after the transaction is successfully completed in the gateway for the status (20), for example. Your administrator can set the way you wish to set some of the statuses. Merchant status (10) and customer status (50) can be set upon url request (POST), manually in the merc hant admin or set to a number of days you define by your administrator. Merchant statuses (20) and (40) can be set by your administrator to a number of days you define. Version 2.8.0, 2013/02/14, Page 49 of 84

50 ii. Request example <form method="post" action=" <input type="hidden" name="merchantname" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="paymenttype" value="anzahlungskauf" /> <input type="hidden" name="gatewaystyle" value="standard" /> <input type="hidden" name="language" value="de" /> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="basketvalue" value="10000" /> <input type="hidden" name="basketdescription" value="demo transaction" /> <input type="hidden" name="userid" value=" " /> <input type="hidden" name="sex" value="unknown" /> <input type="hidden" name="firstname" value="max" /> <input type="hidden" name="lastname" value="schmidt" /> <input type="hidden" name="street" value="demo street name" /> <input type="hidden" name="housenumber" value="12" /> <input type="hidden" name="zipcode" value="21231" /> <input type="hidden" name="city" value="demo city" /> <input type="hidden" name="country" value="de" /> <input type="hidden" name="birthdate" value=" " /> <input type="hidden" name="mobile" value=" " /> <input type="hidden" name=" " -bet.net" /> <input type="hidden" name="userip" value=" " /> <input type="hidden" name="showcanceloption" value="true" /> <input type="submit" name="submitform" value="zeige Gateway" /> </form> Version 2.8.0, 2013/02/14, Page 50 of 84

51 iii. Gateway screens Anzahlungskauf step 1 - Details about the first and second sub-payment amounts. Anzahlungskauf step 2 - Details about the customer. Version 2.8.0, 2013/02/14, Page 51 of 84

52 Anzahlungskauf step 3 - Options for the first sub-payment. Anzahlunghskauf step 4 - Can be different, depends on the chosen payment method for the first sub-type (credit card in this case). Version 2.8.0, 2013/02/14, Page 52 of 84

53 Anzahlungskauf step 5 - Option of submitting the for payment confirmation. Last step - Successful notification of the finished transaction. If the previous step is skipped, this screen will not be seen. Version 2.8.0, 2013/02/14, Page 53 of 84

54 13 Master Gateway We offer a new gateway for the merchants who want to offer their users a choice of all available payment methods on masterpayment. Once the master gateway is called, masterpayment returns a list of available payment methods for the merchant and so the user gets to choose the one he wants. Depending on the chosen payment method, the next steps are the same as in the regular payment process (if credit card is chosen, for example, the next steps are the same a s a regular credit card payment.) i. Request example <form method="post" action=" <input type="hidden" name="merchantname" value="[email protected]" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="paymenttype" value="none" /> <input type="hidden" name="gatewaystyle" value="standard" /> <input type="hidden" name="language" value="de" /> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="basketvalue" value="101" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="basketdescription" value="demo transaction" /> <input type="hidden" name="userid" value="161405" /> <input type="hidden" name="sex" value="unknown" /> <input type="hidden" name="firstname" value="max" /> <input type="hidden" name="lastname" value="schmidt" /> <input type="hidden" name="street" value="demo street name" /> <input type="hidden" name="housenumber" value="12" /> <input type="hidden" name="zipcode" value="21231" /> <input type="hidden" name="city" value="demo city" /> <input type="hidden" name="country" value="de" /> <input type="hidden" name="birthdate" value=" " /> <input type="hidden" name="mobile" value=" " /> <input type="hidden" name=" " value="[email protected]" /> <input type="hidden" name="userip" value=" " /> <input type="hidden" name="showcanceloption" value="true" /> <input type="submit" name="submitform" value="zeige Gateway" /> </form> Version 2.8.0, 2013/02/14, Page 54 of 84

55 ii. Payment scenarios Screen 1 - user can choose the desired payment method out of the available ones for the merchant Once the user has chosen his method, the payment flow is the same as through the simple gateway. Screen 2 - Lastschrift payment chosen from the master gateway. Version 2.8.0, 2013/02/14, Page 55 of 84

56 Screen 3 - Sofort payment chosen from the master gateway. Screen 4 - Anzahlungskauf payment chosen from the master gateway. The next steps are dependent on the chosen method (after this step the payment flow corresponds to the chosen payment method). Refunds are the same as for the chosen method. Version 2.8.0, 2013/02/14, Page 56 of 84

57 14 PIN gateway For merchants who have returning customers and wish to save the end customer payment data so that the next time they request a payment, he is recognized and the previous ly submitted payment data can be used. PIN gateway is a gateway style is available for credit card and lastschrift payment methods only. End customer payment data is stored using the combination of merchant sent userid and user typed in PIN (user saves the PIN after the first payment is done). Once PIN is saved, it can be used to show the payment methods saved with the combination of the userid and PIN; or, in case end customer forgot his PIN, re-written only if a new method is added and the user agrees that the old PIN should be re-written. Re - writing the PIN will cause the previously stored payment data to be lost, new payment data will be stored. As end customer payment data is dependent of the merchant sent userid, and as the merchant set userid identifies the user for the merchant in cause only, but is not unique in the system, we cannot store end customer payment data and make it available for several merchants. In this case the end customer will have to save his payment data for each merchant separately. Of course he can have the same userid and the same PIN, for his commodity. However, for merchants from the same group, whereas userid is unique inside the group (for example the merchants process the payments via the same mobile application, where us er is registered, and therefore unique), payment data stored by one merchant inside the group can be used by another merchant inside the same group, as well as a merchant from the group can save new payment data for an userid submitted by another merchant. This allows the end customer to have all his payment data stored under one single PIN. If you wish to process PIN gateway payments together with other merchants, inside the same group, please contact your account manager and ask him to create a group. Version 2.8.0, 2013/02/14, Page 57 of 84

58 i. Request example <form method="post" action=" <input type="hidden" name="merchantname" -bet.net" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="paymenttype" value="credit_card" /> <input type="hidden" name="gatewaystyle" value="pinmobile" /> <input type="hidden" name="language" value="de" /> <input type="hidden" name="currency" value="eur" /> <input type="hidden" name="basketvalue" value="101" /> <input type="hidden" name="txid" value="tx " /> <input type="hidden" name="basketdescription" value="demo transaction" /> <input type="hidden" name="userid" value=" " /> <input type="hidden" name="sex" value="unknown" /> <input type="hidden" name="firstname" value="max" /> <input type="hidden" name="lastname" value="schmidt" /> <input type="hidden" name="street" value="demo street name" /> <input type="hidden" name="housenumber" value="12" /> <input type="hidden" name="zipcode" value="21231" /> <input type="hidden" name="city" value="demo city" /> <input type="hidden" name="country" value="de" /> <input type="hidden" name="birthdate" value=" " /> <input type="hidden" name="mobile" value=" " /> <input type="hidden" name=" " -bet.net" /> <input type="hidden" name="userip" value=" " /> <input type="hidden" name="showcanceloption" value="true" /> <input type="hidden" name="disable form" value="false" /> <input type="submit" name="submitform" value="zeige Gateway" /> </form> Version 2.8.0, 2013/02/14, Page 58 of 84

59 ii. Payment steps Step 1 - First payment, no previously stored PIN. Step 2 - Payment data is validated, user can store the payment data. Version 2.8.0, 2013/02/14, Page 59 of 84

60 Step 3 - End customer wants to store the payment data and has to type in a PIN. Step 4 - Payment was successful and the PIN was saved. Version 2.8.0, 2013/02/14, Page 60 of 84

61 Step 5 - Second time payment, PIN is used, stored payment method is available. Step 6 - When stored credit card is used, all the payment data is prefilled with the previously stored data, user has to only provide cv2. Version 2.8.0, 2013/02/14, Page 61 of 84

62 Step 7 - If a PIN is already assigned to the userid and a new payment method is submitted, user is again asked to type in his PIN and in case it doesn t match the previously stored one, the user can re-write the PIN. Rewriting the PIN will cause the previously stored payment data to be lost (old card data will be lost, new card data will be stored under the new PIN). Version 2.8.0, 2013/02/14, Page 62 of 84

63 15 Transactions Refund admin. Credit card, Lastschrift, and Carte Bleue transactions can be refunded at any time, by merchant or by Step 1 - Refund from transaction list Step 2 - Type in refund amount Version 2.8.0, 2013/02/14, Page 63 of 84

64 Step 3 - refund overview and transaction status update to REFUNDED One or several partial refunds can be submitted, as long as the sum of refunds for one transaction is <= original transaction amount. Version 2.8.0, 2013/02/14, Page 64 of 84

65 amount. Step 4 - Partial refund inserted, transaction status updated to PARTIAL_REFUND A next refund for this transaction cannot be made of an amount higher than the remaining transaction Version 2.8.0, 2013/02/14, Page 65 of 84

66 Step 5 - Partial refund of the remaining amount Version 2.8.0, 2013/02/14, Page 66 of 84

67 The same functionality can be used from transaction details view Step 5 - Refund from transaction details Sofort transaction refunds can be performed 3 months after the original transaction. In this case refund would work the same as described above, for Credit card, Lastschrift, and Carte Bleue. To refund a sofort transaction after 3 months you would have to contact our accountant to issue a Bank transfer refund for you. Rechnungskauf transactions can be refunded from the same views as the other payment methods, with the difference that refund for rechnungskauf transactions is accepted from merchant only before IRREVOCABLE merchant status. To refund a rechnungskauf transaction after IRREVOCABLE status, you will have to contact your account administrator. A rechnungskauf transaction which is paid by the user cannot be refunded. A transaction refunded before PAYOUT_REQUESTED status will not a ppear in the reports, as well as the refund will not appear in the report. Credit card, Lastschrift, and Carte Bleue and Rechnungskauf transactions can be refunded from the interface, as well as by url request - details can be found at paragraph 17 Refund API Version 2.8.0, 2013/02/14, Page 67 of 84

68 16 Payment API Payment API offers you the possibility to make payments without redirecting users to Masterpayment servers, you can make your own forms, custom pages, use your desired styles, etc. and make the payments using the below described http requests. The main difference between gateway integration and API integration is that there are no payment steps, no end customer redirects: in payment API the payment data is all collected at once. Also, payment API is server to server communication, whereas gateway payment is browser to server. In order to make payments using the Credit card or Carte bleue API you must send an http POST request to to make payments using Lastschrift you must send an POST request to Taking into consideration the specific of payment API, keep in mind that pattern urls keep their significance here and they are still called, but redirect urls are not used anymore, as there is no end customer that needs to be redirected back to the merchant shop. Note: Only credit card, debit card and Lastschrift payments can be processed via the payment API. Note: 3 D secure process is not possible in the payment via the API, as well as risk check processes, because these imply user redirects and user inputs. Note: The request content type header must be application/x-www-form-urlencoded. This is the default content type. Forms submitted with this content type must be encoded as follows: and multipart/form-data will be ignored. Version 2.8.0, 2013/02/14, Page 68 of 84

69 i. Payment/transaction processing parameters for credit card and carte bleue Mandatory parameters are marked with Req. Parameter Data Type Description merchantname String (50) Merchant login name ( ). txid String (200) Merchant s transaction Id - unique string. basketdescription String (250) This value will be used as transaction description visible to the user on his bank account/credit card billing. basketvalue Int The amount to be charged in cents (in currency specified as separate parameter). currency String enum One of [ EUR, GBP, CHF ]. Contact your account manager to enable different currencies for you. language String (2) Requested user interface language (double-character, i.e.: "de", "en") - must conform to the ISO 639 standard. userid String (100) Unique merchant s user ID string that identifies paying customer within merchant s shop system. sex String - enum User sex, one of [ man, woman, unknown ] firstname String (100) User first name. lastname String (150) User last name. street String (150) User address street name. housenumber String 50 User address house number. zipcode String 20 User address postal code. city String 100 User address city name. country String 50 User address - country name (or code) according to ISO 3166 standard. If empty then default value is used - DE birthdate String(10) User birth date - format: "YYYY-MM-DD". mobile String (20) User mobile phone number, including country code prefix. String (120) User - used for transaction status confirmation. userip String (20) IP number used by user format: "##0.##0.##0.##0". Version 2.8.0, 2013/02/14, Page 69 of 84

70 paymenttype String enum One of [ credit_card, debit_card ]. gatewaystyle String - enum One of [ standard, afterbuy ]. items Array Array of Item entities (see "Items array content"). Content of this field can be used by the system to create more informative transaction description visible to the user on his bank account/credit card billing. controlkey String (100) Check sum of other form fields concatenated together with merchant Secret Key. Item index (number) should be placed within square brackets (by replacing n with appropriate index, for example: "items[1][itemprice]" parameter holds a price of second item in items array). cardholder String Card holder name, ex : Max Schmidt cardnumber String Card number cardissuenumber String The issue number of the card cardstartmonth Integer Integer value in the range of cardstartyear Integer A valid year, ex: cardexpirymonth Integer Integer value in the range of cardexpiryyear Integer A valid year, ex: cv2 String Cv2 number from credit card. cardtype String Payment card brand, possible values - MASTER,VISA operation String (2) The kind of operation that will be performed - if null or DB is received a debit request will be performed, if PA is received, preauthorization will be performed. Credit card payment method only. Version 2.8.0, 2013/02/14, Page 70 of 84

71 ii. Payment/transaction processing parameters for Lastschrift Mandatory parameters are marked with Req. Parameter Data Type Description merchantname String (50) Merchant login name ( ). txid String (200) Merchant s transaction Id - unique string. basketdescription String (250) This value will be used as transaction description visible to the user on his bank account/credit card billing. basketvalue Int The amount to be charged in cents (in currency specified as separate parameter). currency String enum One of [ EUR, USD ]. language String (2) Requested user interface language (double-character, i.e.: "de", "en") - must conform to the ISO 639 standard. userid String (100) Unique merchant s user ID string that identifies paying customer within merchant s shop system. sex String - enum User sex, one of [ man, woman,unknown ] firstname String (100) User first name. lastname String (150) User last name. street String (150) User address street name. housenumber String 50 User address house number. zipcode String 20 User address postal code. city String 100 User address city name. country String 50 User address - country name (or code) according to ISO 3166 standard. If empty then default value is used - DE birthdate String(10) User birth date - format: "YYYY-MM-DD". mobile String (20) User mobile phone number, including country code prefix. String (120) User - used for transaction status confirmation. Version 2.8.0, 2013/02/14, Page 71 of 84

72 userip String (20) IP number used by user format: "##0.##0.##0.##0". paymenttype String enum elv gatewaystyle String - enum One of [ standard, afterbuy ]. items Array Array of Item entities (see "Items array content"). Content of this field can be used by the system to create more informative transaction description visible to the user on his bank account/credit card billing. controlkey String (100) Check sum of other form fields concatenated together with merchant Secret Key. Item index (number) should be placed within square brackets (by replacing n with appropriate index, for example: "items[1][itemprice]" parameter holds a price of second item in items array). accountholder String Account holder name, ex : Max Schmidt bankaccount String Bank account number sortcode String The sort code to the bank account bankcountry String The country of the bank account termsaccepted Boolean A parameter confirming that the terms and conditions were accepted Version 2.8.0, 2013/02/14, Page 72 of 84

73 iii. Items array content Items array is composed of zero of more entities: Req. Parameter Data Type Description items[n][itemdescrip tion] String (100) Name and/or description of the basket item. items[n][itemamount] Double Amount purchased. items[n][itemprice] Int In cents. Items are indexed from 0. Item index (number) should be placed within square brackets, as shown in table above (by replacing n with appropriate index, for example: "items[1][itemdescription]" parameter holds the description of the second item in items array). iv. Control key computation To compute control key: 1. Do not use url encoded parameters. 2. Create array of all parameters that will be passed to the gateway (with exception control Key of parameter). 3. Sort the array by parameter names, ascending (take into consideration that parameter names are case sensitive). 4. Create temporary string by concatenating all parameter values ( delimited) from the sorted array in effect, string will contain parameter values ordered according to their names, ascending. 5. Concatenate delimiter ( ) and merchants Secret Key to the end of the temporary string. 6. Compute MD5 checksum of the temporary string make sure that byte array used for MD5 computation is created from temporary string. 7. Add computed checksum as a value of "control Key" field (this should be 32 characters long string 16 bytes, hex encoded). Version 2.8.0, 2013/02/14, Page 73 of 84

74 v. Form example for credit card or carte bleue <form action= method= post > <input name= merchantname value= /> <input name= txid value= tx1234-asd3 /> <input name= basketvalue value= 110 /> <input name= basketdescription value= basket description /> <input name= currency value= EUR /> <input name= language value= de /> <input name= userid value= 1234 /> <input name= sex value= woman /> <input name= firstname value= Elizabeth /> <input name= lastname value= Bathory /> <input name= street value= Nation str. /> <input name= housenumber value= 13/1 /> <input name= zipcode value= /> <input name= city value= demo city /> <input name= country value= DE /> <input name= birthdate value= /> <input name= mobile value= /> <input name= value= /> <input name= userip value= /> <input name= paymenttype value= credit_card /> <input type="text" value="first item description" name="items[0][itemdescription]" /> <input type="text" value="2" name="items[0][itemamount]" /> <input type="text" value="1" name="items[0][itemprice]" /> <input type="text" value="second item description" name="items[1][itemdescription]" /> <input type="text" value="2" name="items[1][itemamount]" /> <input type="text" value="25" name="items[1][itemprice]" /> <input name= controlkey value= fdd89c943e38d994c36d2f74f15f6de6 /> <input name= cardtype value= MASTER /> <input name= cardholder value= Max Schmidt /> <input name= cardnumber value= /> <input name= cardexpirymonth value= 12 /> <input name= cardexpiryyear value= 2012 /> <input name= cv2 value= 029 /> <input type= submit /> </form> Version 2.8.0, 2013/02/14, Page 74 of 84

75 vi. Form example for Lastschrift <form action= method= post > <input name= basketdescription value= basket description /> <input name= merchantname value= /> <input name= txid value= nnbf453dcgf /> <input name= basketvalue value= 110 /> <input name= currency value= EUR /> <input name= language value= de /> <input name= userid value= /> <input name= sex value= man /> <input name= firstname value= Maxóą /> <input name= lastname value= Schmidtóą /> <input name= street value= demo street name óą /> <input name= housenumber value= 12 /> <input name= zipcode value= /> <input name= city value= demo city óą /> <input name= country value= DE /> <input name= birthdate value= /> <input name= mobile value= /> <input name= value= /> <input name= userip value= /> <input name= paymenttype value= elv /> <input name= controlkey value= f48dbe523ab f691dba4 /> <input name= accountholder value= Max Schmidt /> <input name= bankaccount value= /> <input name= sortcode value= /> <input name= bankcountry value= de /> <input name= termsaccepted value= 1 /> <input type="text" value="first item description" name="items[0][itemdescription]" /> <input type="text" value="2" name="items[0][itemamount]" /> <input type="text" value="1" name="items[0][itemprice]" /> <input type="text" value="second item description" name="items[1][itemdescription]" /> <input type="text" value="2" name="items[1][itemamount]" /> <input type="text" value="25" name="items[1][itemprice]" /> <input type= submit /> </form> Version 2.8.0, 2013/02/14, Page 75 of 84

76 vii. Response example <?xml version="1.0" encoding="utf-8"?> <response> <status></status> <error></error> </response> Status tag (<status>) - holds the value of the current transaction when it s available. Possible values: 1) SUCCESS - processed successfully; 2) CANCELLED ended, cancelled by user; 3) TIMED_OUT - ended, timed out ; 4) FAILED ended, failed. Error tag (<error>) - holds a free form text description of the error. Example: <response> <status></status> <error>database already contains transaction associated with merchant [email protected] with merchant tx id=" w3" and status "SUCCESS" - parameter "merchanttxid" is invalid!</error> </response> If the transaction is successful you will get the following response: <?xml version="1.0" encoding="utf-8"?> <response> <status>success</status> <error>none</error> </response> and you will get a request on your callback URL, if the URL is configured in merchant account. Version 2.8.0, 2013/02/14, Page 76 of 84

77 17 Refund API API offers you the possibility to request refunds without having to log in to Masterpayment searching the transaction and then requesting a refund. In order to request a refunds using the refund API you must send an http POST request to refund.do. Note: Refund API can only process Credit card, Card Bleue, Lastschrift or Rechnungskauf refunds. i. Payment/transaction processing parameters for refund Mandatory parameters are marked with Req. Parameter Data Type Description merchantname String (50) Merchant login name ( ). txid String (200) Merchant s transaction Id - unique string. This parameter or the masterpayment transaction id should be present in the request. At least one of them. mptxid String (200) Masterpayment transaction Id - unique string. This parameter or the merchant transaction id should be present in the request. At least one of them. amount Int The amount to be charged in cents. comment String (5000) A comment you can add to the refund. controlkey String (100) Check sum of other form fields concatenated together with merchant Secret Key. ii. Control key computation To compute control key: 1. Create array of all parameters that will be passed to the gateway (with exception control Key of parameter). 2. Sort the array by parameter names, ascending (take into consideration that parameter names are case sensitive). 3. Create temporary string by concatenating all parameter values ( delimited) from the sorted array in effect, string will contain parameter values ordered according to their names, ascending. Version 2.8.0, 2013/02/14, Page 77 of 84

78 4. Concatenate delimiter ( ) and merchants Secret Key to the end of the temporary string. 5. Compute MD5 checksum of the temporary string make sure that byte array used for MD5 computation is created from temporary string. 6. Add computed checksum as a value of "control Key" field (this should be 32 characters long string 16 bytes, hex encoded). iii. Form example for refund <form action= method= post > <input name= merchantname value= [email protected] /> <input name= txid value= 4353gjgfjftghujhklhggfjhjhgjfj36gb /> <input name= amount value= 95 /> <input name= comment value= none /> <input name= controlkey value= 1c5ac16d1ce102d fe3783d8e /> <input type= submit /> </form> iv. Response example <?xml version="1.0" encoding="utf-8"?> <response> <status>partial_refund</status> <error>none</error> </response> Status tag (<status>) - holds the value of the current transaction when it s available. Possible values: 1) REFUNDED/PARTIAL_REFUND - refund request processed successfully; 2) ERROR ended, failed. Error tag (<error>) - holds a free form text description of the error. Example: <?xml version="1.0" encoding="utf-8"?> <response> <status>partial_refund</status> <error>invalid parameters error: Cannot refund amount of 95 from transaction 4353gjgfjftghujhklhggfjhjhgjfj36gb - amount exceeds current transaction balance of 70! - parameter "amount" is invalid! </error> </response> <?xml version="1.0" encoding="utf-8"?> Amount is to high Version 2.8.0, 2013/02/14, Page 78 of 84

79 <response> MasterPayment API <status>error</status> <error>control key 1c5ac16d1ce102d00ggg043413fe3783d8e for specified input parameters and merchant is invalid. </error> </response> Invalid control key <?xml version="1.0" encoding="utf-8"?> <response> <status>error</status> <error>server error: No transaction was found with merchanttxid= for merchant 11 </error> </response> Transaction with the specified id for the specified merchant was not found If the refund is successful you will get the following response: <?xml version="1.0" encoding="utf-8"?> <response> <status>refunded</status> <error>none</error> </response> Version 2.8.0, 2013/02/14, Page 79 of 84

80 18 Transaction service post. We have a service available that will return transaction details if you send the merchant transaction id by i. Request example <form action= method= post > <input type="hidden" name= merchantname value= [email protected] /> <input type="hidden" name= txid value= tx /> <input type="hidden" name= controlkey value= 94c5ad50f802ae0068d3c7a057f79bc9 /> <input type="submit" name="submitform" value="get status " /> </form> ii. Response parameters Lp. Financial Name Description 1 TX_ID Merchant s transaction ID 2 METHOD Payment method used credit_card, debit_card, elv, ratenzahlung, rechnungskauf, anzahlungskauf, sofortbanking. 3 CUST_ID Merchant s customer ID (empty if not passed to the payment gateway) 4 STATUS Transaction status code 5 STATUS_TEXT Additional status description text - can be empty 6 INVOICE_NO Invoice number to include on invoice sent to the paying customer (valid and not empty only if payment method is invoice ) 7 CUSTOMER_NO Unique customer number for use on invoices; this is either value of merchant s customer ID passed to the gateway invocation or generated value (valid and not empty only if payment method is invoice ) 8 CURRENCY Transaction currency 9 VALUE Transaction value expressed in 1/100 of transaction currency 10 FEE Transaction fee in euro cents 11 DISAGIO Transaction disagio expressed in 1/100 of transaction currency 12 FINAL_VALUE Transaction final value expressed in 1/100 of transaction currency 13 CTRL_KEY Control key of all parameters see below. 14 CTRL_KEY_SHORT Control key of TX_ID, METHOD and STATUS parameters, computed using method see below. Version 2.8.0, 2013/02/14, Page 80 of 84

81 iii. Response examples <response> <CTRL_KEY>3ba6bccb84c95092f007daf b</CTRL_KEY> <CTRL_KEY_SHORT>0e1ebbe4f29dcf030b9d20e46c0055dd</CTRL_KEY_SHORT> <CURRENCY>EUR</CURRENCY> <disagio>2460</disagio> <FEE>50</FEE> <FINAL_VALUE>9600</FINAL_VALUE ><CUST_ID> </CUST_ID> <TX_ID>tx </TX_ID> <METHOD>ratenzahlung</METHOD> <STATUS>SUCCESS</STATUS> <STATUS_TEXT>processed successfuly</status_text> <VALUE>12300</VALUE> </response> Successful submission of post request. <response> <ERROR>Required payload/parameters missing or received data is invalid.</error> </response> Parameters missing or have invalid values or control key is invalid. Version 2.8.0, 2013/02/14, Page 81 of 84

82 19 Payment, Preauthorize, Capture and Void operations Payment is the easiest way to bill an amount over a card. The Payment operation collects immediately the amount desired. This is the equivalent of doing an authorization and capture all at once. This kind of payment is processed when in the payment request nothing or 'DB' is sent from the merchant for parameter 'operation'. The authorize operation allows the mercha nt to book the desired money from the card that will be invoiced. This operation has two-steps and must be always completed by voiding the transaction or capturing, within a time of 20 days. This kind of payment is processed when in the payment request 'PA' is sent from the merchant for parameter 'operation'. If the capture is not performed the we will void authorizations older than 20 days. This means that merchants will not be able to capture authorizations after they are voided. The Capture operation consists of collecting the money from authorizations previously done. Capture is performed for the full transaction amount. The Void operation is used to avoid collecting the money from authorizations previously done. This releases the money blocked from the credit card without collecting it. The void can only be performed for the total amount of the Authorization. Payment method for preauthorize, capture and void - credit card only. Version 2.8.0, 2013/02/14, Page 82 of 84

83 Fig. 6 - Authorize, capture and void The void and capture operations can be performed from the interface, by merchant and admin. Fig. 7 - Capture and void in transaction list Fig. 8 - Capture and void in transaction details Also, capture and void can be called with POST via URL Version 2.8.0, 2013/02/14, Page 83 of 84

84 i. Void request example <form action= method= post > <input type="hidden" name= merchantname value= /> <input type="hidden" name= txid value= tx '/> <input type="hidden" name= controlkey value= 4d75981bff344d2cba3fbb67d142dad6 /> <input type="submit" name="submitform" value="void " /> </form> ii. Capture request example <form action= method= post > <input type="hidden" name= merchantname value= /> <input type="hidden" name= txid value= tx '/> <input type="hidden" name= controlkey value= 5f74cdf8bbac022fc bf6287 /> <input type="submit" name="submitform" value="capture" /> </form> iii. Responses <?xml version="1.0" encoding="utf-8"?> <response> <status>success</status> <error>none</error> </response> Success response for caption (transaction status changes from PREAUTHORIZED to SUCCESS) <?xml version="1.0" encoding="utf-8"?> <response> <status>cancelled</status> <error>none</error> </response> Success response for void (transaction status changes from PREAUTHORIZED to CANCELLED) Version 2.8.0, 2013/02/14, Page 84 of 84