myPOS Remote API definitions
This API documentation describes only the application data for the RPC, the tags between the SOAP wrappers:
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>
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.
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’.
<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
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/“ > <soapenv:Header/> <soapenv:Body> <urn:MPRSubscribe xmlns:urn="urnIPayService"> <urn:version>3.0</urn:version> <urn:login>email@example.com</urn:login> <urn:key_index>1</urn:key_index> <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>
<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:version>3.0</a:version> <a:login>firstname.lastname@example.org</a:login> <a:key_index>1</a:key_index> <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 indicate if and how data is present for each method.
|M||Mandatory. The data element is required in the message.|
|C||Conditional. The data element is required in the message if the conditions described in the accompanying text apply.|
|O||Optional. The data element is not required but may be included in the message at the message initiator’s option.|
|ME||Mandatory Echo. The data element is required in a response message and must contain the same value (“echoed”) from the original request or advice message.|
|CE||Conditional Echo. The data element is required in a response message if it was present in the original request or advice message, and it must contain the same value (“echoed”) from the original message|
Handling specific respons codes (1A, 70, 65, 55)
In order to better handle cases where the cardholder is required by their bank to enter a PIN code we have made some ammendments to our CRR API.
To ensure the correct workflow of your CRR integration you will need to implement the following procedure in your code:
- If a payment results in one of the following response codes (1A, 70, 65, 55) - this means that the payment required a PIN code entry. This does not mean that the payment has failed or you need to initiate the payment again.
- At this point the client has (probably) seen the prompt to input their PIN code on the POS and entered it.
- You should initiate an MPRGetTnxStatus request (with the same RUID) to check for this transactions status again. We recommend you wait around 20 seconds and initiate the MPRGetTnxStatus in order to make sure the client has finished entering their PIN code.
- If the result again is one of the following response codes (1A, 70, 65, 55) - this means that the client has not yet entered their PIN code. (We recommend you wait around 20 seconds and initiate the MPRGetTnxStatus again.)
- If the client has already entered their PIN code you should get the final response code that will be different from the upper mentioned ones and will show you the actuall result of the payment (sucess/failed).
Data Type Formats
Data Type in document
|String||String||This is a string|
|Date||ISO 8601 date string YYYY-MM-DD||2012-03-31|
|DateTime||ISO 8601 datetime string YYYY-MM-DD HH:mm:SS||2012-03-31 23:59:59|
|A(n)||Alpha string. [n] characters required||Alpha string|
|AN(n)||Alphanumeric string. [n] characters required||Alphanumeric string|
|N(n)||Numeric string. [n] characters required. Number is left-padded with zeroes.||000123|
|double||Numeric string with decimal point. Only point is used (no commas or other characters for decimal point)||34.56|
|BASE64||Sting used to pass binary data. The binary data should be converted to base64 standard.||YW55IGNhcm5hbCBwbGVhc3VyZQ==|