myPOS Remote API definitions

Request structure

This API documentation describes only the application data for the RPC, the tags between the SOAP wrappers:

<soap:Body>
</soap:Body>

The nested child element is named after the RPC to be executed. For example:

<urn:MPRSubscribe " xmlns:urn="urnIPayService">
.
.
</urn:MPRSubscribe>

This element holds the tags containing the input parameters for the RPC. Each command has a few common parameters (they are the same for all commands) and its own specific parameters. The common parameters are:

<urn:login>string</urn:login>
<urn:key_index>int</urn:key_index>
<urn:version>string</urn:version>
<urn:tid>an(8)</urn:tid>
<urn:signature>base64</urn:signature>

Security

To ensure that only authorized myPOS members connect to the service myPOS system uses the following levels of security:

• A required API username of the member (partner) - <urn:login>
• Request authentication using an API signature included in the request - <urn:signature>
• Secure Sockets Layer (SSL) data transport.

A failure of authenticated security at any one of these levels denies access to the myPOS Remote API service.

Parameter signature, key_index, and public/private key pairs

The signature parameter is supplied in each message from both sides. For the signing process, both myPOS and the partner generate public/private key pairs and exchange the public certificate. Key pairs are generated using the RSA algorithm. The certificates must be PEM-encoded PKCS7 file. Each of the parties is using the private key to sign the message and the opposite side authenticate the sender with corresponding public certificate.

The partner can provide several public certificates. A key_index is assigned to each certificate. For each of the partner’s public certificate, there is a correspondingmyPOS public certificate.

The signature parameter is generated using the following mechanism:

• All data from the request message parameters (without the ‘signature’) are concatenated with a semicolon (‘;’) into a single string in the order that they are specified in the table for every method. 
• A hash is produced over the string using the SHA-256 algorithm.
• The hash is signed with the private key and a signature is produced.
• The signature needs to be Base64 encoded.

The opposite side should:

• Concatenate all data from the request message parameters (without the ‘signature’) with a semicolon (‘;’) into a single string in the order that they are specified in the table for every method. 
• A hash is produced over the string using the SHA-256 algorithm.
• The received signature is Base64-decoded.
• Then verify the obtained string with the sent signature property and the public key extracted from the myPOS public certificate.

Response Structure

Each request message has to have a corresponding response (either success or error). If the response is not received, the partner has to repeat the request with the same parameters(call method and the ruid have to stay unchanged for the repeated attempts) until it receives a response. For each received request, the myPOS server will analyze whether it’s new, or a repeated attempt (based on the combination of the call method and the ruid for a particular partner). If it’s repeated and the request has already been processed, the server will return the last result, without executing the command itself. Each response of a request is with the same ‘SOAP logic’ structure, where the data elements are nested in an element whose name is formed by the name of the request call, concatenated with the string ‘Response’.

For example:

<MPRSubscribeResponse>
.
.
</MPRSubscribeResponse>

Each response has a few common parameters (they are the same for all commands) and its own specific parameters. The common parameters are:

<urn:status>n(2)</urn:status>
<urn:status_msg>string</urn:status_msg>
<urn:signature>base64</urn:signature>

The status parameter should be used for program based analysis and further action (please refer to Appendix I). The status_msg is mostly informational - for logging and human analysis purposes. The parameter signature within the response is used as a confirmation that the particular request has been received and processed. It is generated using the same signing mechanism as for the request command. The signed data is from all response parameters (without the signature). The string is signed with the corresponding private key (for request key_index).

Request and Response Examples

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/“ >
<soapenv:Header/>
<soapenv:Body>
<urn:MPRSubscribe xmlns:urn="urnIPayService">
<urn:key_index>1</urn:key_index>
<urn:version>1.0</urn:version>
<urn:login>name@website.com</urn:login>
<urn:tid>90000015</urn:tid>
<urn:ruid>201203319999999</urn:ruid>
<urn:currency>EUR</urn:currency>
<urn:action>1</urn:action>
<urn:signature>
bUViE5SzWy9iYpWzxlEVO/8Yb6bvtJVn1P6/rat5NBdgJaBU7OxeRm8rxi/fW1xuekqDM06F4MbzUPnTIA/sZ1ZwlMjSTExY
5+7DqkdejN7mDgnB8zogrOfF6/P1snxuNgPRtHuJ0ZeTdTWNm9kKPGE7IadvIGtOpF+7yspfWd4=</urn:signature>
</urn:MPRSubscribe >
</soapenv:Body>
</soapenv:Envelope>

Response

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Body>
<MPRSubscribeResponse xmlns:urn="urnIPayService">
<MPRSubscribeResult xmlns:a="http://schemas.datacontract.org/2004/07/iPay.Core"
xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
 <a:key_index>1</a:key_index>
<a:version>1.0</a:version>
<a:login>name@website.com</a:login>
 <a:tid>90000015</a:tid>
 <a:ruid>201203319999999</a:ruid>
<a:currency>EUR</a:currency>
<a:action>1</a:action>
<a:code>78025608</a:code>
<a:status>0</a:status>
<a:status_msg>OK</a:status_msg>
<a:signature>
bUViE5SzWy9iYpWzxlEVO/8Yb6bvtJVn1P6/rat5NBdgJaBU7OxeRm8rxi/fW1xuekqDM06F4MbzUPnTIA/sZ1ZwlMjSTExY
5+7DqkdejN7mDgnB8zogrOfF6/P1snxuNgPRtHuJ0ZeTdTWNm9kKPGE7IadvIGtOpF+7yspfWd4=</a:signature>
</MPRSubscribeResult>
</MPRSubscribeResponse>
</s:Body>
</s:Envelope>

Presence Notations

Presence notations indicate if and how data is present for each method.

Data Type Formats