MasterPayment API. Version 2.8.0

(1)

MasterPayment API

Version 2.8.0

(2)

1 Payments/transactions processing ... 5

i. Payment/transaction processing parameters ... 6

ii. Items array content ... 9

iii. Control key computation ... 10

2 Transaction status notification ... 13

i. Transaction status and notification type ... 13

ii. Notification configuration... 14

iii. Notification contents ... 16

3 Redirect on transaction completion ... 18

4 Payment gateway ... 19

i. Invoking the gateway using test tool... 20

ii. Displaying gateway invocation code/URL ... 21

iii. Troubleshooting ... 22

iv. List of transaction statuses and their meanings ... 23

5 Credit Card ... 24

i. Payment steps ... 24

ii. Request example ... 26

6 Three D secured transactions ... 27

i. Payment request ... 27

ii. Payment steps ... 28

7 Lastschrift ... 31

8 Carte Bleue transactions... 34

i. Request example ... 35

9 Sofortbanking ... 36

10 Ratenzahlung... 38

ii. Set "Items sent" status ... 41

iii. Request example ... 42

11 Rechnungskauf transactions ... 43

i. Short description ... 43

(3)

iv. Request example ... 46

v. Rechnungskauf Set statuses... 47

12 Anzahlungskauf transactions... 48

i. Short description ... 48

iii. Gateway screens... 51

13 M aster Gateway ... 54

ii. Payment scenarios... 55

14 PIN gateway ... 57

ii. Payment steps ... 59

15 Transactions Refund ... 63

16 Payment API ... 68

i. Payment/transaction processing parameters for credit card and carte bleue ... 69

ii. Payment/transaction processing parameters for Lastschrift ... 71

iii. Items array content ... 73

iv. Control key computation ... 73

v. Form example for credit card or carte bleue... 74

vi. Form example for Lastschrift ... 75

vii. Response example ... 76

17 Refund API ... 77

i. Payment/transaction processing parameters for refund ... 77

ii. Control key computation ... 77

iii. Form example for refund... 78

iv. Response example ... 78

18 Transaction service ... 80

ii. Response parameters ... 80

iii. Response examples... 81

(4)

Release Description Date Changes

1.5 Initial version 10 - June - 2011 Initial Workflow Description

1.6 Major release 20 - December - 2011 Recurrent methods description

2.0 Major release 15 - February - 2012 Rechnungskauf and anzahlungskauf _descriptions

2.2 Major release 27 - May - 2012 credit card payment API description

2.3 Major release 17 - July - 2012 Lastschrift payment API description, _{refund API description}

2.6 Major release 25 - August - 2012 Master gateway description

2.7 Major release 26 - September - 2012 Reatenkauf changes description, three _{d secure description, css path and} email form payment parameters added, refund procedure description 2.8 Major release 12 - February - 2013 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: https://www.masterpayment.com/en/payment/gateway ;or include the form with the payment post request in your payment page:

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:

https://www.masterpayment. 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

(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 (email).

 _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. email String (120) User email - used for transaction status confirmation.  userIp String (20) IP number used by user – format: "##0.##0.##0.##0".

(7)

‘anzahlungskauf’, ‘sofortbanking’].

 gatewayStyle String - enum One of [‘standard’, ‘mobile’, ‘pin mobile’ 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’).

(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][ite mPrice]" 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.

 disableEmailForm String (bool) Boolean value (true/1 or false/0) - if true, end customer will not see the email 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} Number

String (30) Sofort account holder name, if provided, together with the other 2 sofort specific parameters (sofortSenderHolder, sofortSenderBankCode), end

(9)

customer gets redirected to sofortbanking site without seeing the masterpayment gateway.

 sofortSenderBankCod e

String (30) Sofort account holder name, if provided, together with the other 2 sofort specific 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).

(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|101|1980-01-01|demo+city|DE|EUR|demotransaction%40fin-

bet.net|Max|standard|12|DE|Schmidt|demo%40fin-bet.net|800200200|credit_card|unknown|true|demo+street+name|tx1343132094627|6124823|89.01.199.12|21231|3d7 e5869-7afd-451a-a887-8e6a1530d4ea"

(11)

Correct computation example:

Parameter name Parameter value

basketDescription demo transaction

basketValue 101 country DE currency EUR email [email protected] firstname Max gatewayStyle standard language DE lastname Schmidt merchantName [email protected] mobile 800200200 paymentType credit_card txId tx1343132094627 userId 6124823

user street demo street name

houseNumber 12

zipCode 21231

city demo city

userIp 89.01.199.12

sex unknown

birthdate 1980-01-01

(12)

Temporary string:

"demo transaction|101|1980-01-01|demo

city|DE|EUR|[email protected]|Max|standard|12|DE|Schmidt|[email protected]|800200200|credit_card|unknown|true|demo street name|tx1343132094627|6124823|89.01.199.12|21231|3d7e5869 -7afd-451a-a887-8e6a1530d4ea" Control key: "04be2b0aff6edd4bca7f163f2819d10c" Gateway URL: " https://masterpayment.com/de/payment/[email protected]&txId=tx1343132094627&paymentType=credit_card&gatewayStyle=standard&language=DE&currency=EUR&basket Value=101&basketDescription=demo+transaction&userId=6124823&sex=unknown&firstname=Max&lastn ame=Schmidt&str eet=demo+street+name&houseNumber=12&zipCode=21231&city=demo+city&country=DE&birthdate=19800101&mobile=800200200&email=demotransaction%40fin -bet.net&userIp=89.01.199.12&showCancelOption=true&controlKey=04be2b0aff6edd4bca7f163f2819d10c"

(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 Gateway invocation succeeded, payment is waiting for manual activation by merchant (i.e. ‘rechnungskauf’ payments).

txSuccess

SCHEDULED Gateway invocation succeeded, payment is scheduled for automatic execution (i.e. ‘rechnungskauf’ payments).

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

(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

(15)

Enter appropriate information into notification callbacks related fields (marked on screenshot below):

(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.

(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:

http://www.mycompany.com/txcallback/success/${TX_ID}?status=${STATUS} would be evaluated to:

http://www.mycompany.com/txcallback/success/1223221?status=SUCCESS

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 http://www.mycompany.com/../..&statusText=${STATUS_TEXT}&..

will be evaluated to:

http://www.mycompany.com/../..&statusText=&.. 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.

(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:http://facebook.com) – 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).

(19)

4 Payment gateway

Masterpayment portal is equipped with a utility page for executing gateway invocations – available at address https://www.masterpayment.com/de/tools/testgateway. 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 .

(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 HTML form for invoking gateway with HTTP POST method (and entered invocation parameters). o URL for invoking gateway using HTTP GET method (and entered invocation parameters). o Control key computed for entered parameters and current secret key.

o 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.

(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):

(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:

(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

(24)

5 Credit Card

i. Payment steps

Step 1 - Submission of the payment data by the end customer on masterpayment.

(25)

If the customer doesn’t want to receive the confirmation email, 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.

(26)

ii. Request example

(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

(28)

ii. Payment steps

Step 1 - End customer fills in his credit card data.

(29)

(30)

(31)

7 Lastschrift

(32)

Step 3a - Transaction procession result.

If the customer doesn’t want to receive the confirmation email, 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.

(33)

(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.

(35)

i. Request example

(36)

9 Sofortbanking

This is how the sofortbanking gateway looks like:

The end customer has to have a sofortbanking account to be able to pay. The merchant doesn’t need to have one.

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.

(37)

(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.

Ratenzahlung step 1 - Show to the end customer the number of installments and the period between them chosen by the merchant

(39)

(40)

Ratenzahlung step 3 - Billing information, Lastschrift form, only the first payment amount will be billed.

Ratenzahlung step 5 - Address information

(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

(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

(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 email

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 https://masterpayment.com/services/rest/remote/itemssent < form action=‘https://masterpayment.com/services/rest/remote/itemssent’ method=‘post’>

</form>

For customer status NO_PAYMENT (50) the following parameters in URL request using POST command are

required:

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 https://masterpayment.com/services/rest/remote/invoiceduedate <form action=‘https://masterpayment.com/services/rest/remote/invoiceduedate’ method=‘post’>

(44)

ii. Merchants transactions statuses

Status Meaning

APPROVED (00) Gateway invocation succeeded, payment is waiting for activation.

DELIVERED (10) 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

IRREVOCABLE (20) 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.

PAYOUT_REQUESTED (40) Payment is requested 5 days since the transaction was active. The number of days can be set in the admin.

PAYOUT_SENT (50) Payment sent from the customer’s account.

PAYOUT_COMPLETE (60) Payment was completed successfully.

LEGAL_ISSUES (70) The merchant can set the status manually from his admin.

REFUNDED (90) Full refund inserted. iii. Customer transactions statuses

Status Condition

NOT_CHARGED (10) Status set automatically, when the transaction is created.

PURCHASE_FINAL (20) The default value is 5 days since the transaction is created and wasn’t revoked by the user.

ELV (33) Status set automatically when the user pays via Lastschrift.

BANK_TRANSFER (30) Status set manually when the user pays via bank transfer.

CREDIT_CARD (31) Status set automatically when the user pays via Credit Card. SOFORT_UEBERWEISUNG (32) Status set automatically when the user pays via Sofortüberweisung. PAYMENT_COMPLETE (40) The payment was made successfully; the money cannot be taken away. NO_PAYMENT (50) Status set depending on merchant status DELIVERED. The number of

days can be set in the admin or sent via url (using POST)

ELV_BANK_CHARGEBACK (60) Status set manually by the merchant, when the end customer account

didn’t have the amount available after the payment was made via Lastschrift.

(45)

requested a charge back after the payment was made via Lastschrift. CREDIT_CARD_CHARGEBACK

(62)

Status set manually by the merchant, when the end customer

requested a charge back after the payment was made via Credit Card.

EMAIL_REMINDER (71) Status set automatically 10 days after ELV_BANK_RETRY or

NOT_PAID_BUT_DUE, unless successful payment was made. SECOND_EMAIL_REMINDER (72) Status set automatically 10 days after first EMAIL_REMINDER LAST_EMAIL_REMINDER (73) Status set automatically 10 days after SECOND_EMAIL_REMINDER POSTAL_REMINDER (74) Status set automatically 14 days after LAST_EMAIL_REMINDER. SECOND_POSTAL_REMINDER

(75)

Status set automatically 14 days after POSTAL_EMAIL_REMINDER. INKASSO (76) Status set manually, available only after

2ND_POSTAL_MAIL_REMINDER

THIRD_PARTY (100) Status set manually, only after 2ND_POSTAL_MAIL_REMINDER, it means that the invoice vas sold to a third party.

REVOKED (200) Payment revoked by customer.

REFUNDED (250) 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.

(46)

iv. Request example

(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.

(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:

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 https://masterpayment.com/services/rest/remote/itemssent < form action=‘https://masterpayment.com/services/rest/remote/itemssent’ method=‘post’>

(49)

For customer status NO_PAYMENT (50) the following parameters in URL request using POST command are required:

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 https://masterpayment.com/services/rest/remote/invoiceduedate <form action=‘https://masterpayment.com/services/rest/remote/invoiceduedate’ method=‘post’>

</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.

(50)

(51)

iii. Gateway screens

(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).

(53)

Anzahlungskauf step 5 - Option of submitting the email for payment confirmation.

(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.)

(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.

(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).

(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.