Cash Register Remote API - Reference

Complete technical reference for integrating with the myPOS Remote API.

Request Structure

All API requests follow a SOAP (Simple Object Access Protocol) envelope format. The actual API data is nested within the SOAP body.

SOAP Envelope

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <!-- API method goes here -->
  </soap:Body>
</soap:Envelope>

API Method Format

Each API method is named after the operation being called. For example, MPRSubscribe:

<urn:MPRSubscribe xmlns:urn="urnIPayService">
  <!-- Common parameters -->
  <!-- Method-specific parameters -->
</urn:MPRSubscribe>

Common Parameters

Every API request includes these required parameters in the same order:

Example Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>
    <urn:MPRSubscribe xmlns:urn="urnIPayService">
      <urn:version>3.0</urn:version>
      <urn:login>merchant@company.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>

Security

The myPOS Remote API uses three layers of security:

1. API Username

• Parameter: <urn:login>
• Purpose: Identifies your account
• Requirement: Must be registered with myPOS

2. Digital Signature Authentication

• Parameter: <urn:signature>
• Purpose: Verify request authenticity
• Mechanism: RSA-2048 with SHA-256 hash

3. SSL/TLS Transport

• Purpose: Encrypt all data in transit
• Requirement: Always use HTTPS endpoints

Digital Signatures

Signatures prove that you (the legitimate private key holder) created the request. Both parties sign their messages, and both sides verify signatures.

How Signatures Work

Signing a Request (Your Side):

1. Concatenate parameters – Join all request parameters (except signature) with semicolons (;) in the specified order
2. Hash the string – Use SHA-256 algorithm
3. Sign the hash – Use your private RSA key
4. Encode as Base64 – Convert signature bytes to Base64 string
5. Include in request – Add as <urn:signature> element

Example concatenation:

version;login;key_index;tid;ruid;currency;action

Verifying a Response (Your Side):

1. Extract parameters – Get all response data except the signature
2. Concatenate – Join in the specified order with semicolons
3. Hash the string – Use SHA-256
4. Decode signature – Convert Base64 signature back to bytes
5. Verify with public key – Use myPOS's public certificate to verify
6. Match confirmed – If verification succeeds, response is authentic

Key Management

• Key Pairs: Generated using RSA-2048 algorithm
• Certificate Format: PEM-encoded PKCS7
• Key Index: Assign unique index to each certificate (1, 2, 3, etc.)
• Certificate Exchange:
  • You provide your public certificate to myPOS
  • myPOS provides their public certificate to you
  • Keep your private key secure (never share)
• Multiple Certificates: Support certificate rotation by using different key_index values

Response Structure

Every request gets a corresponding response. If you don't receive one, retry with the same request ID.

SOAP Response Envelope

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <MPRSubscribeResponse xmlns:urn="urnIPayService">
      <!-- Response data -->
    </MPRSubscribeResponse>
  </s:Body>
</s:Envelope>

Response Element Naming

Response element names follow the pattern: [RequestMethod]Response

• Request: <urn:MPRSubscribe>
• Response: <MPRSubscribeResponse>

Common Response Parameters

Example 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">
        <a:version>3.0</a:version>
        <a:login>merchant@company.com</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

Presence notations describe whether a data element is required in a request or response.

Handling PIN Entry Responses

Some payments require cardholder PIN validation by their bank. The API returns special status codes to indicate this:

PIN-Required Response Codes: 1A, 70, 65, 55

Handling PIN Entry Workflow

1. Receive PIN-required response (status code 1A, 70, 65, or 55)

   • Customer saw PIN prompt on terminal
   • Payment is waiting for PIN entry

2. Wait 20 seconds

   • Allow customer time to enter PIN

3. Check transaction status

   • Call MPRGetTnxStatus with the same RUID
   • Use the original request ID

4. Check result:

   • If still 1A, 70, 65, or 55 → PIN not yet entered, wait and retry
   • If different code → PIN entry complete, this is the final result

5. Repeat as needed

   • Keep checking every 20 seconds
   • Maximum recommended: 5 retries (100 seconds total)

Implementation Example

async function handlePaymentWithPIN(transactionId, paymentAmount) {
  // Send initial payment request
  const response = await sendPaymentRequest(transactionId, paymentAmount);
  
  if (isPINRequiredCode(response.status)) {
    // PIN entry in progress
    let finalResponse = response;
    let attempts = 0;
    const maxAttempts = 5;
    
    while (isPINRequiredCode(finalResponse.status) && attempts < maxAttempts) {
      // Wait 20 seconds for customer to enter PIN
      await delay(20000);
      
      // Check transaction status
      finalResponse = await checkTransactionStatus(transactionId);
      attempts++;
    }
    
    return finalResponse;
  }
  
  return response;
}

function isPINRequiredCode(status) {
  return ['1A', '70', '65', '55'].includes(status);
}

Data Types

API data is formatted according to these type definitions:

Type Examples

String:     "This is a string"
A(10):      "ABCDEFGHIJ"     (10 letters max)
AN(8):      "TERM0001"       (8 alphanumeric max)
N(5):       "00123"          (123 with left padding)
double:     "34.56"          (point separator only, no commas)
Date:       "2024-02-11"
DateTime:   "2024-02-11 23:59:59"
BASE64:     "YW55IGNhcm5hbCBwbGVhc3VyZQ=="

Status Codes

Success

Information

Errors

Request Retry Logic

If you don't receive a response:

1. Wait 5 seconds before retrying
2. Use the same RUID (unique request ID)
3. Use same parameters as original request
4. Maximum 3 retries recommended
5. myPOS server will recognize it's a duplicate and return cached result (not reprocess)

Certificate Exchange Checklist

Before going live:

• ✓ Generated your RSA-2048 private key
• ✓ Generated your self-signed SSL certificate (PEM/PKCS7 format)
• ✓ Sent your public certificate to myPOS
• ✓ Received myPOS public certificate
• ✓ Installed myPOS certificate in your code
• ✓ Verified certificate is readable (file permissions)
• ✓ Tested signing and verification in development
• ✓ Confirmed key_index matches your certificate

Common Integration Mistakes

❌ Hardcoding credentials – Use environment variables
❌ Incorrect parameter order – Must be exact order for signature
❌ Wrong text encoding – Use UTF-8 for all strings
❌ Base64 signature errors – Verify encoding/decoding
❌ Timestamp mismatch – Server time must be synchronized
❌ Stale certificates – Renew annually
❌ Missing RUID – Must be unique per request
❌ Wrong endpoint – Test vs. production URLs different

Testing Your Integration

Development Checklist

1. Test in development environment using test endpoint
2. Verify signature generation with known test vectors
3. Test error responses (invalid credentials, timeout, etc.)
4. Test certificate validation (wrong cert, expired, etc.)
5. Monitor for timing issues (clock sync, timeout length)
6. Load test with concurrent requests
7. Test retry logic with request failures

Test Endpoint

https://demotest-crrservice.mypos.com/infromhttp

Use test credentials provided by myPOS.

Production Deployment

Before Going Live

1. Update endpoint to production URL:

   https://crr-api.mypos.com/infromhttp
   

   CopyCopied!

2. Switch to production credentials

3. Verify production certificates are installed

4. Monitor logs for signature verification errors

5. Start with low transaction volumes

6. Gradually increase volume over 24 hours

API Limits

• Request timeout: 30 seconds
• Maximum payload: 10MB
• Rate limit: 1000 requests per minute per account
• Connection timeout: 10 seconds
• Maximum retries: 3 recommended (total 5 minutes)