HTTP Interface

HTTP Interface:	Overview
Description	Electronic Transaction Payment
Version	5.1
Authentication	IP address white-listing
Max request length	16384
Method	HTTP (SSL/TLS encrypted) POST and GET, x-www-form-urlencoded
Productive system	`<https://www.mpay24.com/app/bin/etpv5>`
Test system	`<https://test.mpay24.com/app/bin/etpv5>`

Legende:

Mandatory: All elements with an bold written name and an asterisk are mandatory (e.g. Example*).
Optional: All non-marked elements are optional and can be omitted.

Operations

Operation	Description
`AcceptPayment`	Direct payment interface
`AcceptWithdraw`	Direct withdraw interface
`SelectPayment`	Interactive payment interface
`ManualClear`	Clear transaction(s)
`ManualReverse`	Reversal (not cleared) transaction
`ManualCredit`	Credit already cleared transaction
`ListProfiles`	List stored payment profiles
`DeleteProfile`	Delete stored payment profile
`ListPaymentMethods`	List available payment methods (for specific pType)
`TransactionStatus`	Get transaction status for specified mpayTID or tid
`TransactionHistory`	Get transaction history for specified mpayTID

AcceptPayment

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`ACCEPTPAYMENT`	Operation to perform
`P_TYPE`*	`PaymentType`	`-`	Payment type of the transaction
`PRICE`*	`numeric`	`[0-9]{2,11}`	Amount stated in cents
`CURRENCY`*	`alphanumeric`	`[A-Z]{3}`	Three digit ISO country code
`TID`	`alphanumeric`	`.{1,32}`	Unique merchant transaction ID
`CLEARING`	`enumeration`	`1`, `0`	Deprecated
`AUTOCLEAR`	`enumeration`	`Y`, `N`	Defines if the transaction should be cleared automatically
`CUSTOMER`	`alphanumeric`	`.{1,50}`	Customer name
`CUSTOMER_ID`	`alphanumeric`	`.{1,32}`	Merchant ustomer ID
`CUSTOMER_EMAIL`	`alphanumeric`	`[-0-9a-zA-Z+.@_] {5,64}`	Customer e-mail
`PROFILE`	`enumeration`	`Y`, `N`	Defines if the payment details should be stored by mPAY24
`ORDERDESC`	`alphanumeric`	`.{1,255}`	Order description
`USER_FIELD`	`alphanumeric`	`.{1,255}`	User variable (is communicated over the URLs)
`ORDER`	`alphanumeric`	`.{1,2048}`	Order description provided as XML
`SUCCESS_URL`	`URL`	`-`	URL for customer redirection in case of success
`ERROR_URL`	`URL`	`-`	URL for customer redirection in case of error
`CONFIRMATION_URL`	`URL`	`-`	URL for receiving push notifications about the transaction state
`LANGUAGE`	`alphanumeric`	`[A-Z]{2}`	Two digits language ISO code
`BRAND`	`Brand`	`-`	Brand abbreviation

Output

Element	Type	Restriction	Description
`STATUS`*	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`*	`enumeration`	`OK`, `...`	Return code of the operation
`LOCATION`	`alphanumeric`	`(https://).{5,1016}`	Redirection location of the customer
`EXTERNAL_ERROR`	`alphanumeric`	`.{1,255}`	Further information upon an error
`MPAYTID`	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID

Input: CC

CreditCard specific payment parameters

Element	Type	Restriction	Description
`P_TYPE`*	`enumeration`	`CC`	Payment type of the transaction
`BRAND`*	`enumeration`	`AMEX`, `DINERS`, `JCB`, `MASTERCARD`, `VISA`	Brand abbreviation
`IDENTIFIER`*	`alphanumeric`	`.{1,20}`	Payment identifier
`EXPIRY`*	`alphanumeric`	`Format: YYMM`	Expiry date
`CVC`	`numeric`	`[0-9]{3,4}`	CVC
`AUTH_3DS`	`enumeration`	`Y`, `N`	Enable or disable 3DS authentication

Input: ELV

Direct debit specific payment parameters

Element	Type	Restriction	Description
`P_TYPE`*	`enumeration`	`ELV`	Payment type of the transaction
`BRAND`*	`enumeration`	`ATOS`, `BILLPAY`, `HOBEX-AT`, `HOBEX-DE`, `HOBEX-NL`	Brand abbreviation
`IBAN`*	`alphanumeric`	`.{1,34}`	International bank account number of the customer
`BIC`	`alphanumeric`	`.{1,11}`	Bank identifier code of the customer
`MANDATE_ID`	`alphanumeric`	`.{1,35}`	Mandate ID of the transaction assigned by the merchant
`DATE_OF_SIGNATURE`	`alphanumeric`	`Format: YYYY-MM-DD`	Date of the mandate signature

Input: EPS

Online-banking (eps) specific payment parameters

Element	Type	Restriction	Description
`P_TYPE`*	`enumeration`	`EPS`	Payment type of the transaction
`BRAND`*	`enumeration`	`EPS`	Brand abbreviation
`BANK_ID`*	`numeric`	`[0-9]{1,3}`	Bank ID

Input: GIROPAY

Online-banking (giropay) specific payment parameters

Element	Type	Restriction	Description
`P_TYPE`*	`enumeration`	`GIROPAY`	Payment type of the transaction
`IBAN`	`alphanumeric`	`.{1,34}`	International bank account number of the customer
`BIC`*	`alphanumeric`	`.{1,11}`	Bank identifier code of the customer

Input: MAESTRO

Debit card specific payment parameters

Element	Type	Restriction	Description
`P_TYPE`*	`enumeration`	`MAESTRO`	Payment type of the transaction
`IDENTIFIER`*	`alphanumeric`	`.{1,20}`	Payment identifier
`EXPIRY`*	`alphanumeric`	`Format: YYMM`	Expiry date

Input: PAYPAL

PayPal specific payment parameters

Element	Type	Restriction	Description
`CUSTOM`	`alphanumeric`	`.{1,255}`	A free-form field for your own use

Input: PB

paybox specific payment parameters

Element	Type	Restriction	Description
`P_TYPE`*	`enumeration`	`PB`	Payment type of the transaction
`IDENTIFIER`*	`alphanumeric`	`.{1,20}`	Payment identifier
`PAYDAYS`	`numeric`	`[0-9]{1,2}`
`RESERVEDAYS`	`numeric`	`[0-9]{1,2}`

Input: KLARNA

Klarna specific payment parameters

Element	Type	Restriction	Description
`P_TYPE`*	`enumeration`	`KLARNA`	Payment type of the transaction
`BRAND`*	`enumeration`	`INVOICE`, `HP`	Brand abbreviation
`GENDER`*	`enumeration`	`M`, `F`	Customer gender
`PERSONAL_NUMBER`*	`alphanumeric`	`.{1,11}`	Personal number of the user or the birthday for countries without personal number
`PHONE`*	`alphanumeric`	`.{1,20}`	Customer phone number
`PCLASS`	`numeric`	`[0-9]{1,5}`	Payment class defined by Klarna

AcceptWithdraw

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`ACCEPTWITHDRAW`	Operation to perform
`P_TYPE`*	`PaymentType`	`-`	Payment type of the transaction
`PRICE`*	`numeric`	`[0-9]{2,11}`	Amount stated in cents
`CURRENCY`*	`alphanumeric`	`[A-Z]{3}`	Three digit ISO country code
`TID`	`alphanumeric`	`.{1,32}`	Unique merchant transaction ID
`CUSTOMER`	`alphanumeric`	`.{1,50}`	Customer name
`CUSTOMER_ID`	`alphanumeric`	`.{1,32}`	Merchant ustomer ID
`CUSTOMER_EMAIL`	`alphanumeric`	`[-0-9a-zA-Z+.@_] {5,64}`	Customer e-mail
`ORDERDESC`	`alphanumeric`	`.{1,255}`	Order description
`USER_FIELD`	`alphanumeric`	`.{1,255}`	User variable (is communicated over the URLs)
`ORDER`	`alphanumeric`	`.{1,2048}`	Order description provided as XML
`CONFIRMATION_URL`	`URL`	`-`	URL for receiving push notifications about the transaction state
`BRAND`	`Brand`	`-`	Brand abbreviation

Output

Element	Type	Restriction	Description
`STATUS`*	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`*	`enumeration`	`OK`, `...`	Return code of the operation
`EXTERNAL_ERROR`	`alphanumeric`	`.{1,255}`	Further information upon an error
`MPAYTID`	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID

Input: CC

CreditCard specific payment parameters

Element	Type	Restriction	Description
`P_TYPE`*	`enumeration`	`CC`	Payment type of the transaction
`BRAND`*	`enumeration`	`AMEX`, `DINERS`, `MASTERCARD`, `VISA`	Brand abbreviation
`IDENTIFIER`*	`alphanumeric`	`.{1,20}`	Payment identifier
`EXPIRY`*	`alphanumeric`	`Format: YYMM`	Expiry date

Input: MAESTRO

Debit card specific payment parameters

Element	Type	Restriction	Description
`P_TYPE`*	`enumeration`	`MAESTRO`	Payment type of the transaction
`IDENTIFIER`*	`alphanumeric`	`.{1,20}`	Payment identifier
`EXPIRY`*	`alphanumeric`	`Format: YYMM`	Expiry date

SelectPayment

All payment relevant information (e.g. amount, customer name, shopping cart, ...) are provided within the MDXI XML.

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`SELECTPAYMENT`	Operation to perform
`MDXI`*	`alphanumeric`	`.	[\n\r\t]1,8192`

Output

Element	Type	Restriction	Description
`STATUS`*	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`*	`enumeration`	`OK`, `...`	Return code of the operation
`LOCATION`	`alphanumeric`	`(https://).{5,1016}`	Redirection location of the customer

ManualClear

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`MANUALCLEAR`	Operation to perform
`MPAYTID`*	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID
`PRICE`	`numeric`	`[0-9]{2,11}`	Amount stated in cents
`ORDER`	`alphanumeric`	`.	[\n\r\t]1,2048`

Input

Element	Type	Restriction	Description
`MERCHANTID`	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`MANUALCLEAR`	Operation to perform
`MPAYTID_XXX`*	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID
`PRICE_XXX`	`numeric`	`[0-9]{2,11}`	Amount stated in cents
`ORDER_XXX`	`alphanumeric`	`.	[\n\r\t]1,2048`
`SUM`	`numeric`	`[0-9]{1,3}`	Sum of elements

Output

Element	Type	Restriction	Description
`STATUS`*	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`*	`enumeration`	`OK`, `...`	Return code of the operation
`MPAYTID`	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID
`TIMESTAMP`	`numeric`	`[0-9]{14}`	Timestamp of the operation

ManualReverse

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`MANUALREVERSE`	Operation to perform
`MPAYTID`*	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID

Output

Element	Type	Restriction	Description
`STATUS`	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`	`enumeration`	`OK`, `...`	Return code of the operation
`MPAYTID`	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID
`TID`	`alphanumeric`	`.{1,32}`	Unique merchant transaction ID
`TIMESTAMP`	`numeric`	`[0-9]{14}`	Timestamp of the operation

ManualCredit

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`MANUALCREDIT`	Operation to perform
`MPAYTID`*	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID
`STATEID`	`numeric`	`[0-9]{1,11}`	Unique ID of a transaction state
`PRICE`	`numeric`	`[0-9]{2,11}`	Amount stated in cents

Output

Element	Type	Restriction	Description
`STATUS`*	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`*	`enumeration`	`OK`, `...`	Return code of the operation
`MPAYTID`	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID
`TIMESTAMP`	`numeric`	`[0-9]{14}`	Timestamp of the operation

ListProfiles

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`LISTPROFILES`	Operation to perform
`B_IDX`	`numeric`	`[0-9]{1,6}`	Index of the first element being listed
`E_IDX`	`numeric`	`[0-9]{1,6}`	Index of the last element being listed

Output

Element	Type	Restriction	Description
`STATUS`*	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`*	`enumeration`	`OK`, `...`	Return code of the operation
`ALL`*	`numeric`	`[0-9]{1,3}`	Total number of payment methods
`SUM`*	`numeric`	`[0-9]{1,3}`	Sum of elements
`CUSTOMER_ID_XXX`	`alphanumeric`	`.{1,3}`	Merchant ustomer ID
`UPDATED_XXX`	`alphanumeric`	`Format: YYYY-MM-DD HH:MM:SS`	Timestamp of last change

DeleteProfile

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`DELETEPROFILE`	Operation to perform
`CUSTOMER_ID`*	`alphanumeric`	`.{1,32}`	Merchant ustomer ID

Output

Element	Type	Restriction	Description
`STATUS`*	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`*	`enumeration`	`OK`, `...`	Return code of the operation

ListPaymentMethods

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`numeric`	`[0-9]{5}`	Operation to perform
`P_TYPE`	`PaymentType`	`-`	Payment type of the transaction

Output

Element	Type	Restriction	Description
`STATUS`*	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`*	`enumeration`	`OK`, `...`	Return code of the operation
`ALL`	`numeric`	`[0-9]{1,3}`	Total number of payment methods
`P_TYPE_XXX`	`PaymentType`	`-`	Payment type of the transaction
`BRAND_XXX`	`Brand`	`-`	Brand abbreviation
`DESCRIPTION_XXX`	`alphanumeric`	`.{1,255}`	Payment system description

TransactionStatus

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`TRANSACTIONSTATUS`	Operation to perform
`MPAYTID`	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID
`TID`	`alphanumeric`	`.{1,32}`	Unique merchant transaction ID

Output

Additional to the returned elements below, the operation returns also the details of the payment notification.

Element	Type	Restriction	Description
`STATUS`*	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`*	`enumeration`	`OK`, `...`	Return code of the operation

TransactionHistory

Input

Element	Type	Restriction	Description
`MERCHANTID`*	`numeric`	`[0-9]{5}`	mPAY24 merchant ID
`OPERATION`*	`enumeration`	`TRANSACTIONHISTORY`	Operation to perform
`MPAYTID`	`numeric`	`[0-9]{1,11}`	Unique mPAY24 transaction ID

Output

Element	Type	Restriction	Description
`STATUS`*	`enumeration`	`OK`, `ERROR`	Response status of the operation
`RETURNCODE`*	`enumeration`	`OK`, `...`	Return code of the operation
`STATEID_XXX`	`numeric`	`[0-9]{1,11}`	Unique ID of a transaction state
`PARENTSTATEID_XXX`	`numeric`	`[0-9]{1,11}`	ID of the related parent state
`TS_XXX`	`numeric`	`[0-9]{14}`	Timestamp of the transaction state
`AMOUNT_XXX`	`numeric`	`[0-9]{2,11}`	Amount stated in cents
`TXSTATE_XXX`	`alphanumeric`	`.{1,255}`	Transaction state
`PROFILESTATUS_XXX`	`alphanumeric`	`.{1,255}`	Profile status of the action

Special types

Simple types / enumerations

Element	Type	Restriction	Description
`PaymentType`	`enumeration`	`CC`, `MAESTRO`, `EPS`, `PB`, `GIROPAY`, `ELV`, `PSC`, `QUICK`, `PAYPAL`, `MPASS`, `BILLPAY`, `INVOICE`, `HP`, `KLARNA`, `SOFORT`, `PROFILE`	Payment type
`Brand`	`enumeration`	`AMEX`, `DINERS`, `JCB`, `MASTERCARD`, `VISA`, `EPS`, `ELV`, `ATOS`, `HOBEX-AT`, `HOBEX-DE`, `HOBEX-NL`, `B4P`, `BILLPAY`, `KLARNA`	Brand abbreviation
`URL`	`alphanumeric`	`{5,1016}`	URL definition