SOAP Interface

SOAP Interface:Overview
DescriptionmPAY24 ETP (Electronic Transaction Processing) Interface WebService
Version1.5
AuthenticationHTTP Basic (Username/Password specified by mPAY24)
Transport protocolSOAP over HTTPS
WSDL location prod.https://www.mpay24.com/soap/etp/1.5/ETP.wsdl
WSDL location test.https://test.mpay24.com/soap/etp/1.5/ETP.wsdl
Endpoint prod.https://www.mpay24.com/app/bin/etpproxy_v15
Endpoint testhttps://test.mpay24.com/app/bin/etpproxy_v15

Legend:

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

Operations

OperationDescription
SelectPaymentInteractive payment interface
CreatePaymentTokenInteractive interface for tokenization of sensitive payment data
AcceptPaymentDirect payment interface
ManualCallbackProcess suspended payment
ManualClearClear transaction(s)
ManualReverseReversal (not cleared) transaction
ManualCreditCredit already cleared transaction
AcceptWithdrawDirect withdraw interface
TransactionStatusGet transaction status for specified mpayTID or tid
TransactionConfirmationGet transaction confirmation calls for specified mpayTID
TransactionHistoryGet all transaction's states for specified mpayTID or the last transaction with the specified TID
ListNotClearedList transactions to be cleared
ListPaymentMethodsList available payment methods (for specific pType)
CreateProfileInteractive creation of payment profiles
ListProfilesList stored payment profiles
DeleteProfileDelete stored payment profile
CreateCustomerCreate profiles without payment

SelectPayment

Input: SelectPayment

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
mdxi*stringLength: 1 - 8192MDXI XML structure to provide transaction data

Output: SelectPaymentResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
errNointLength: 1 - 5Error number
errTextstringLength: 1 - 255Further information upon an error
location*anyURI-Redirection location of the customer

CreatePaymentToken

Input: CreatePaymentToken

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
pType*PaymentType-Payment type of the transaction
templateSetstringLength: 1 - 255Template set name
stylestringLength: 1 - 255Styling information
customerIDstringLength: 1 - 32Merchant customer ID
profileIDstringLength: 1 - 12Profile ID assigned by the customer
domainstring-Merchant domain
languagestringLength: 2Two digits language ISO code

Output: CreatePaymentTokenResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
tokenstring-Payment token identifier
apiKeystring-REST API key
errNointLength: 1 - 5Error number
errTextstringLength: 1 - 255Further information upon an error
locationanyURI-Redirection location of the customer

AcceptPayment

Input: AcceptPayment

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
tid*stringLength: 1 - 32Merchant transaction ID
pType*PaymentType-Payment type of the transaction
payment*Payment-Payment specifics
customerIDstringLength: 1 - 32Merchant customer ID
customerNamestringLength: 1 - 50Customer name
orderOrder-Order description
successURLanyURILength: 1 - 1024URL for customer redirection in case of success
errorURLanyURILength: 1 - 1024URL for customer redirection in case of error
confirmationURLanyURILength: 1 - 1024URL for receiving push notifications about the transaction state
languagestringLength: 2Two digits language ISO code

Output: AcceptPaymentResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
mpayTIDunsignedLongLength: 1 - 11Unique mPAY24 transaction ID
errNointLength: 1 - 5Error number
errTextstringLength: 1 - 255Further information upon an error
locationanyURI-Redirection location of the customer

ManualCallback

Input: ManualCallback

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
mpayTID*unsignedLongLength: 1 - 11Unique mPAY24 transaction ID
paymentCallback*Callback-Callback details of a payment
orderOrder-Order description

Output: ManualCallbackResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
mpayTIDunsignedLongLength: 1 - 11Unique mPAY24 transaction ID
errNointLength: 1 - 5Error number
errTextstringLength: 1 - 255Further information upon an error
locationanyURI-Redirection location of the customer

ManualClear

Input: ManualClear

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
clearingDetailsClearingDetails-Clearing transaction details

Output: ManualClearResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
transactionTransaction-Transaction status information

ManualReverse

Input: ManualReverse

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
mpayTID*unsignedLongLength: 1 - 11Unique mPAY24 transaction ID

Output: ManualReverseResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
transaction*Transaction-Transaction status information

ManualCredit

Input: ManualCredit

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
mpayTID*unsignedLongLength: 1 - 11Unique mPAY24 transaction ID
stateIDunsignedLongLength: 1 - 11Unique ID of a transaction state
amountunsignedIntLength: 2 - 11Amount stated in cents

Output: ManualCreditResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
transaction*Transaction-Transaction status information

AcceptWithdraw

Input: AcceptWithdraw

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
tid*stringLength: 1 - 32Merchant transaction ID
pType*PaymentType-Payment type of the transaction
withdraw*Withdraw-Withdraw specifics
customerIDstringLength: 1 - 32Merchant customer ID
customerNamestringLength: 1 - 50Customer name
orderOrder-Order description
confirmationURLanyURILength: 1 - 1024URL for receiving push notifications about the transaction state
languagestringLength: 2Two digits language ISO code

Output: AcceptWithdrawResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
mpayTIDunsignedLongLength: 1 - 11Unique mPAY24 transaction ID
errNointLength: 1 - 5Error number
errTextstringLength: 1 - 255Further information upon an error

TransactionStatus

Input: TransactionStatus

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
mpayTIDunsignedLongLength: 1 - 11Unique mPAY24 transaction ID
tidstringLength: 1 - 32Merchant transaction ID

Output: TransactionStatusResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
parameterParameter-Basic name/value parameter

TransactionConfirmation

Input: TransactionConfirmation

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
mpayTID*unsignedLongLength: 1 - 11Unique mPAY24 transaction ID

Output: TransactionConfirmationResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
confirmationConfirmation-Confirmation/notification details of a transaction

TransactionHistory

Input: TransactionHistory

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
mpayTID*unsignedLongLength: 1 - 11Unique mPAY24 transaction ID

Output: TransactionHistoryResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
historyEntryHistoryEntry-Entry of the transaction history

ListNotCleared

Input: ListNotCleared

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
beginunsignedIntLength: 1 - 6Index of the first element being listed
sizeunsignedIntLength: 1 - 3Size of returned list
sortFieldSortField-Field to order result by
sortTypeSortType-Method to order result
listInProgressbooleantrue, falseList transactions which are currently in progress

Output: ListNotClearedResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
transactionDetailsTransactionDetails-Detailed transaction status information
all*unsignedInt-Total number of elements

ListPaymentMethods

Input: ListPaymentMethods

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
pTypePaymentType-Payment type of the transaction

Output: ListPaymentMethodsResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
paymentMethodPaymentMethod-Configured payment method
all*unsignedInt-Total number of elements

CreateProfile

Input: CreateProfile

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
mdxi*stringLength: 1 - 8192MDXI XML structure to provide transaction data

Output: CreateProfileResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
errNointLength: 1 - 5Error number
errTextstringLength: 1 - 255Further information upon an error
locationanyURI-Redirection location of the customer

ListProfiles

Input: ListProfiles

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
customerIDstringLength: 1 - 32Merchant customer ID
expiredBydateYYYY-MM-DDReturns only profiles expired until the given date
beginunsignedIntLength: 1 - 6Index of the first element being listed
sizeunsignedIntLength: 1 - 3Size of returned list

Output: ListProfilesResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
profileProfile-Customer payment profile
all*unsignedInt-Total number of elements

DeleteProfile

Input: DeleteProfile

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
customerID*stringLength: 1 - 32Merchant customer ID
profileIDstringLength: 1 - 12Profile ID assigned by the customer

Output: DeleteProfileResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation

CreateCustomer

Input: CreateCustomer

ElementTypeRestrictionDescription
merchantID*unsignedIntLength: 5mPAY24 merchant ID
pType*PaymentType-Payment type of the transaction
paymentData*Payment-Payment specifics
customerIDstringLength: 1 - 32Merchant customer ID
customerNamestringLength: 1 - 50Customer name
billingAddressxmlthe billingAddress of the customer
languagestringLength: 2Two digits language ISO code

Output: CreateCustomerResponse

ElementTypeRestrictionDescription
status*Status-Response status
returnCode*stringLength: 1 - 255Return code of the operation
errNointLength: 1 - 5Error number

Special types

Simple types / enumerations

ElementTypeRestrictionDescription
StatusstringOK, ERROROperation status
PaymentTypestringCC, MAESTRO, EPS, PB, PSC, ELV, QUICK, GIROPAY, PAYPAL, BILLPAY, INVOICE, HP, KLARNA, SOFORT, MASTERPASS, TOKEN, PROFILE, PAYOLUTION, ELVSECURE, IDEALPossible payment systems
TxStatestringINIT, AUTHORIZE, SUSPENDED, REDIRECTED, CALLBACK, RESERVED, EXECUTE, BILLED, REVOKE, CREDITED, REJECT, ARCHIVED, WITHDRAW, WITHDRAWNTransaction states
TStatusstringNOTFOUND, FAILED, RESERVED, BILLED, REVERSED, CREDITEDTransaction status
ConfirmationStatusstringOK, ERROR, PENDING, FAILUREStatus of the confirmation-url call
ConfirmedstringRESERVED, BILLED, REVERSED, CREDITED, WITHDRAWN, SUSPENDED, ERRORTransaction status confirmed on the confirmation-url call
SortFieldstringMPAYTID, PTYPE, BRAND, CURRENCY, TID, ORDERDESC, ORDERNUMBER, CURRDATE, CURRTIMETransaction field to be used for sorting
SortTypestringASC, DESCSort type to be used
AddressModestringREADONLY, READWRITEAddress fields modification mode
GenderstringMALE, FEMALEPerson gender

Complex types

Payment

Common payment parameters

ElementTypeRestrictionDescription
amount*unsignedIntLength: 2 - 11Amount stated in cents
currency*stringLength: 3Three digit ISO currency code
manualClearingbooleantrue, falseEnables or disables manual clearing
useProfilebooleantrue, falseEnables or disables profile usage
profileIDstringLength: 1 - 12Profile ID assigned by the customer

PaymentTOKEN

Extention: Payment

Payment with token specific payment parameters

ElementTypeRestrictionDescription
token*string-Payment token identifier

PaymentCC

Extention: Payment

CreditCard specific payment parameters

ElementTypeRestrictionDescription
brand*string-Brand abbreviation
identifier*stringLength: 1 - 20Identifier of the payment system
expiry*unsignedIntLength: 4 - YYMMExpiry date
cvcstringLength: 3 - 4CVC
auth3DSbooleantrue, falseEnable or disable 3DS authentication

PaymentMAESTRO

Extention: Payment

Maestro specific payment parameters

ElementTypeRestrictionDescription
identifier*stringLength: 1 - 20Identifier of the payment system
expiry*unsignedIntLength: 4Expiry date

PaymentEPS

Extention: Payment

EPS online bank transfer specific payment parameters

ElementTypeRestrictionDescription
brand*string-Brand abbreviation
bankIDunsignedIntLength: 1 - 3Bank ID
bicstringLength: 1 - 11Bank identifier code of the customer

PaymentPB

Extention: Payment

Paybox specific payment parameters

ElementTypeRestrictionDescription
identifier*stringLength: 1 - 20Identifier of the payment system
payDaysunsignedIntLength: 1 - 2
reserveDaysunsignedIntLength: 1 - 2

PaymentELV

Extention: Payment

Direct debit specific payment parameters

ElementTypeRestrictionDescription
brand*string-Brand abbreviation
iban*stringLength: 1 - 34International bank account number of the customer
bicstringLength: 1 - 11Bank identifier code of the customer
mandateIDstringLength: 1 - 35Mandate ID of the transaction assigned by the merchant
dateOfSignaturedate-Date of mandate signature

PaymentGIROPAY

Extention: Payment

Giropay online bank transfer specific payment parameters

ElementTypeRestrictionDescription
ibanstringLength: 1 - 34International bank account number of the customer
bic*stringLength: 1 - 11Bank identifier code of the customer

PaymentPAYPAL

Extention: Payment

PayPal specific payment parameters

ElementTypeRestrictionDescription
commitbooleantrue, falseUsed for PayPal Express Checkout
customstringLength: 1 - 255A free-form field for your own use

PaymentBILLPAY

Extention: Payment

BillPay specific payment parameters

ElementTypeRestrictionDescription
brand*string-Brand abbreviation

PaymentKLARNA

Extention: Payment

Klarna specific payment parameters

ElementTypeRestrictionDescription
brand*string-Brand abbreviation
personalNumber*stringLength: 1 - 11Personal number of the user or the birthday for countries without personal number
pClassunsignedIntLength: 1 - 5Payment class defined by Klarna

PaymentMASTERPASS

Extention: Payment

MasterPass specific payment parameters

ElementTypeRestrictionDescription
auth3DSbooleantrue, falseEnable or disable 3DS authentication
commitbooleantrue, falseUsed for PayPal Express Checkout

ProfilePaymentCC

Extention: Payment

CreditCard specific profile payment parameters for interactive payments

ElementTypeRestrictionDescription
cvcstringLength: 3 - 4CVC
auth3DSbooleantrue, falseEnable or disable 3DS authentication

ProfilePaymentPB

Extention: Payment

Paybox specific profile payment parameters

ElementTypeRestrictionDescription
payDaysunsignedIntLength: 1 - 2
reserveDaysunsignedIntLength: 1 - 2

ProfilePaymentELV

Extention: Payment

Direct debit specific profile payment parameters

ElementTypeRestrictionDescription
mandateIDstringLength: 1 - 35Mandate ID of the transaction assigned by the merchant
dateOfSignaturedate-Date of mandate signature

Withdraw

Common withdraw parameters

ElementTypeRestrictionDescription
amount*unsignedIntLength: 2 - 11Amount stated in cents
currency*stringLength: 3Three digit ISO country code

WithdrawCC

Extention: Withdraw

CreditCard specific withdraw parameters

ElementTypeRestrictionDescription
brand*string-Brand abbreviation
identifier*stringLength: 1 - 20Identifier of the payment system
expiry*unsignedIntLength: 4Expiry date

WithdrawMAESTRO

Extention: Withdraw

Maestro Card specific withdraw parameters

ElementTypeRestrictionDescription
identifier*stringLength: 1 - 20Identifier of the payment system
expiry*unsignedIntLength: 4Expiry date

Item

Shopping cart item

ElementTypeRestrictionDescription
numberstringLength: 1 - 255Shopping cart row number
productNrstringLength: 1 - 255Product number for the item
descriptionstringLength: 1 - 255Description respectively title
packagestringLength: 1 - 255Scale size of the item
quantityunsignedIntLength: 1 - 255Quantity of the item ordered
taxintLength: 2 - 11Tax of all units stated in cents
amount*intLength: 2 - 11Amount stated in cents

ShoppingCart

Shopping cart content

ElementTypeRestrictionDescription
itemItem-Item in the shopping cart
discountintLength: 2 - 11Discount of the total amount
shippingCostsintLength: 2 - 11Shipping costs of the order
shippingTaxintLength: 2 - 11Tax amount of the shipping costs
taxintLength: 2 - 11Tax of all units stated in cents

IndustrySpecific

Common industry specific parameters

AirlineTicket

Extention: IndustrySpecific

Industry specific parameters for airline tickets

ElementTypeRestrictionDescription
iataCode*string-
ticketID*string-

Address

Customer address definition

ElementTypeRestrictionDescription
modeAddressMode-Editing mode of the address
name*stringLength: 1 - 50Customer name
genderGender-Customer gender
birthdaydate-Customer birthday
street*stringLength: 1 - 50First street line
street2stringLength: 1 - 50Second street line
zip*stringLength: 1 - 50Zip code
city*stringLength: 1 - 50City name
statestringLength: 1 - 40State name
countryCode*stringLength: 2Country as two digit ISO code
emailstringLength: 1 - 64Customer e-mail address
phonestringLength: 1 - 20Customer phone number

Order

Customer order definition

ElementTypeRestrictionDescription
clientIPstring-IP address of the customer
descriptionstringLength: 1 - 255Description respectively title
userFieldstringLength: 1 - 100User variable (is communicated over the URLs)
shoppingCartShoppingCart-Shopping cart of the order
industrySpecificIndustrySpecific-Common industry specific parameters
billingAddress-Customer address definition for billing
shippingAddress-Customer address definition for shipping

Callback

Common payment callback parameters

ElementTypeRestrictionDescription
amountunsignedIntLength: 2 - 11Amount stated in cents

CallbackPAYPAL

Extention: Callback

PayPal specific payment callback parameters

ElementTypeRestrictionDescription
cancelbooleantrue, false

CallbackMASTERPASS

Extention: Callback

MasterPass specific payment callback parameters

ElementTypeRestrictionDescription
cancelbooleantrue, false

ClearingDetails

Clearing transaction details

ElementTypeRestrictionDescription
mpayTID*unsignedLongLength: 1 - 11Unique mPAY24 transaction ID
amountunsignedIntLength: 2 - 11Amount stated in cents
orderOrder-Order description

Transaction

Transaction status

ElementTypeRestrictionDescription
mpayTID*unsignedLongLength: 1 - 11Unique mPAY24 transaction ID
tStatus*TStatus-Defines possible states of a transaction result
stateIDunsignedLongLength: 1 - 11Unique ID of a transaction state
tid*stringLength: 1 - 32Merchant transaction ID

TransactionDetails

Extention: Transaction

Detailed transaction status

ElementTypeRestrictionDescription
orderDescription*stringLength: 1 - 255Order description
pType*PaymentType-Payment type of the transaction
brand*string-Brand abbreviation
amount*unsignedIntLength: 2 - 11Amount stated in cents
currency*stringLength: 3Three digit ISO country code
bifStatus*string-Status returned by the payment interface

Parameter

Basic name/value parameter

ElementTypeRestrictionDescription
name*stringLength: 1 - 50Customer name
value*stringLength: 1 - 255Parameter value

HistoryEntry

Entries in the transaction history

ElementTypeRestrictionDescription
stateID*unsignedLongLength: 1 - 11Unique ID of a transaction state
parentStateIDunsignedLongLength: 1 - 11ID of the related parent state
txState*TxState-Transaction state
amount*unsignedIntLength: 2 - 11Amount stated in cents
timeStamp*dateTime-Timestamp of the transaction state
approvalCodestringLength: 1 - 255Payment ID or code returned by the acquirer
errNointLength: 1 - 5Error number
errTextstringLength: 1 - 255Further information upon an error
profileStatus*string-Profile status of the action

Confirmation

Results of a confirmation-url call

ElementTypeRestrictionDescription
status*ConfirmationStatus-Response status
confirmed*Confirmed-Confirmed transaction status
timeStamp*dateTime-Timestamp of the transaction state
url*anyURILength: 1 - 1024URL for receiving push notifications about the transaction state
result*stringLength: 0 - 255Merchant response of the confirmation receipt

PaymentMethod

Configured payment method

ElementTypeRestrictionDescription
pType*PaymentType-Payment type of the transaction
brand*string-Brand abbreviation
description*stringLength: 1 - 255Description respectively title

PaymentProfile

Payment profile details

ElementTypeRestrictionDescription
pMethodIDunsignedIntLength: 1 - 3ID of the payment method
profileID*stringLength: 1 - 12Profile ID assigned by the customer
updated*dateTime-Timestamp of the last update
identifier*stringLength: 1 - 20Identifier of the payment system
expiresdate-Expiry date if applicable
addressAddress-

Profile

Customer profile with payment data

ElementTypeRestrictionDescription
customerID*stringLength: 1 - 32Merchant customer ID
updated*dateTime-Timestamp of the last update
paymentPaymentProfile-Payment specifics