Purchase Method

Define the Flow and Logic of Your Payment Process

Purpose

This method initiates the beginning of the payment process for a customer. The customer is placed on a page that requests entering payment card details.

myPOS Checkout API will check for:

  • Valid myPOS Account number (also referred to as Client number)
  • Valid Checkout Store ID (SID) corresponding with this myPOS Account number
  • Valid status of the Checkout (enabled)
  • Valid currency and total amount
  • Valid KeyIndex & corresponding Signature

Required for all Checkout API methods

PropertyTypical valueTypeRequiredDescription
IPCmethodIPCPurchaseStringYESThis is the method name used in the API call.
IPCVersion1.4floatYESThis is the version of the API being used.
IPCLanguageENStringYESThis is the language used in the API call.

Method Properties

PropertyTypical valueTypeRequiredDescription
Amount23.45DoubleYESThe amount of the payment requested.
CurrencyEURA(3)YESISO 3-character currency code. The currency for the payment should be registered and approved.
OrderID20120331999999StringYESPlaceholder for the merchant. Used to put some data that will help the merchant to recognize for which order is the payment. Up to 80 characters.
SID000000000000010StringYESStore ID (SID) - Reference number for the Merchant Checkout in the myPOS system
WalletNumber61938166610StringYESmyPOS Client Number
KeyIndex1IntYESIndicates which key pair is being used.
URL_OKhttp://site.ext/paymentOKStringYESThe page where the cardholder should be redirected on successful payment.
URL_Cancelhttp://site.ext/paymentNOKStringYESThe page where the cardholder should be redirected when Cancel is pressed on the payment page.
URL_Notifyhttps://site.ext/paymentNotifyStringYESAddress supplied by the partner, where the IPCPurchaseNotify API call will send the parameters for the successful payment.
PaymentMethod1StringNO

If the PaymentMethod property is not set, the customer is redirected to a myPOS Hosted Payment Page displaying all payment methods supported by myPOS Checkout.
Supported values:

ValuePayment Method behaviour
1Redirects the customer to a CARD-only checkout
2Redirects the customer to an iDEAL checkout
3Redirects the customer to a checkout where all available payment methods are shown
4Redirects the customer to a Satispay checkout
5Redirects the customer to a TWINT checkout
6Redirects the customer to an IRIS checkout

Multiple payment methods: to enable multiple specific payment methods, you must provide the values as a comma-separated list.
Example: PaymentMethod=1,2,6 This configuration will display CARD, iDEAL, and IRIS as available payment options on the checkout page.

CardTokenRequest0N(1)YESSupported values:
ValueBehaviour
0Do not request a payment card token.
1Store new card and request a token.
Not applicable if PaymentMethod = 2. Disables PaymentMethod = 3.
2Pay with a card and request a token.
Not applicable if PaymentMethod = 2. Disables PaymentMethod = 3.

Token will be available in IPCPurchaseNotify callback.

PaymentParametersRequired1N(1)YESSupported values:
ValueBehaviour
1Full request (All parameters described as conditional are required in the request. The client will not be able to edit them on the payment page.)
2Simplified request (All parameters described as conditional are not required in the request. The client will be forced to fill them in on the payment page.)
3Simplified request & Simplified payment page (All parameters described as conditional are not required in the request. On the payment page the client will see and fills in only the payment card details.)
CustomerEmailname@website.comStringConditionalConditional. The parameter is required when PaymentParametersRequired = 1. This is a customer’s email.
CustomerPhone+23568956958StringNOThis is a customer’s phone.
CustomerFirstNamesJohn SantamariaStringConditionalConditional. The parameter is required when PaymentParametersRequired = 1. All customer’s names without the surname.
CustomerFamilyNameSmithStringConditionalConditional. The parameter is required when PaymentParametersRequired = 1. The customer’s surname.
CustomerCountryDEUStringNOISO3 country code
CustomerCityHamburgStringNO
CustomerZIPCode20095StringNO
CustomerAddressKleine Bahnstr. 41StringNOCustomer’s address.
AccountSettlement11111111119N(11)NOAccount for payment settlement.
expires_in86400.00DoubleNOCustom set time (in seconds) how long the session lifetime should be for the payment page (86400.00 seconds = 24 hours)
NoteStringNOText associated with the purchase.
CartItems2IntConditionalThe number of rows (items) in the logical record Cart. If there will be some additional fees/taxes for the cardholder, they need to be added as new items.
CartLogical HolderLogical RecordConditionalArray provided by the Merchant. The array describes the content of the shopping cart. The content will be displayed on the myPOS Checkout API payment page.
Delivery5DoubleNOYou can specify your delivery price.

NOTE: The URL_Notify URL should be SSL-enabled address only (i.e. it must start with "https://"). Unsecured URLs will cause a communication error.

URLs must not have the port specified.

  • https://example.com/ - Correct
  • https://www.example.com/ - Correct
  • https://example.com:8000 - NOT Correct

Same OrderID is used for the request of a partner, except in a case where the order has been marked as paid. Then OrderID is a unique identifier and myPOS Checkout API will reject duplicated transmission.

Cart Logical Record

Cart logical record consists of standard POST parameters with the form name=value. For every consequent item, an index is added that shows the logical record number for the item (ex. Article_1). Indexes are from 1 to <CartItems>.

PropertyTypical valueTypeDescription
ArticleHP ProBook 6360b stickerStringName of an article in the shopping cart.
Quantity2IntHow many pieces of an article.
Price2.34DoublePrice of a single unit.
Amount4.68DoubleQuantity*Price for the article.
CurrencyEURA(3)Should be the same currency as in the purchase amount.

Partner Identification

If you are part of our Partners Program, you will need to submit these two additional parameters with each of your requests to the API. This will provide you with analytics about the usage in your myPOS Partners Portal account and help our support teams assist you better.

Note - This requires you to set the API version of your requests to 1.4.1. No other changes in the code/requests are necessary.

PropertyTypical valueTypeDescription
PartnerIDmps-p-XXXXXXXXStringIdentical number for the partner
ApplicationIDmps-app-XXXXXXXXStringIdentical number for the application

Example Request

<?php
declare(strict_types=1);

function signPostData(array $postData, string $privateKey): string
{
    // Same signing logic as your sample:
    // base64_encode(implode('-', $postData)) then RSA-SHA256 sign then base64(signature).
    $concatenated = base64_encode(implode('-', $postData));

    $privateKeyObj = openssl_get_privatekey($privateKey);
    if ($privateKeyObj === false) {
        throw new RuntimeException('Invalid private key');
    }

    $signature = '';
    $success = openssl_sign($concatenated, $signature, $privateKeyObj, OPENSSL_ALGO_SHA256);
    openssl_free_key($privateKeyObj);

    if (!$success) {
        throw new RuntimeException('Failed to sign data');
    }

    return base64_encode($signature);
}

// Sandbox endpoint (per myPOS docs / test data)
const API_URL = 'https://www.mypos.com/vmp/checkout-test';

// Production endpoint 
// const API_URL = 'https://www.mypos.com/vmp/checkout';

// Test Private Key (Replace with your own private key from myPOS merchant account)
const PRIVATE_KEY = '-----BEGIN RSA PRIVATE KEY-----
MIICXAIBAAKBgQCf0TdcTuphb7X+Zwekt1XKEWZDczSGecfo6vQfqvraf5VPzcnJ
2Mc5J72HBm0u98EJHan+nle2WOZMVGItTa/2k1FRWwbt7iQ5dzDh5PEeZASg2UWe
hoR8L8MpNBqH6h7ZITwVTfRS4LsBvlEfT7Pzhm5YJKfM+CdzDM+L9WVEGwIDAQAB
AoGAYfKxwUtEbq8ulVrD3nnWhF+hk1k6KejdUq0dLYN29w8WjbCMKb9IaokmqWiQ
5iZGErYxh7G4BDP8AW/+M9HXM4oqm5SEkaxhbTlgks+E1s9dTpdFQvL76TvodqSy
l2E2BghVgLLgkdhRn9buaFzYta95JKfgyKGonNxsQA39PwECQQDKbG0Kp6KEkNgB
srCq3Cx2od5OfiPDG8g3RYZKx/O9dMy5CM160DwusVJpuywbpRhcWr3gkz0QgRMd
IRVwyxNbAkEAyh3sipmcgN7SD8xBG/MtBYPqWP1vxhSVYPfJzuPU3gS5MRJzQHBz
sVCLhTBY7hHSoqiqlqWYasi81JzBEwEuQQJBAKw9qGcZjyMH8JU5TDSGllr3jybx
FFMPj8TgJs346AB8ozqLL/ThvWPpxHttJbH8QAdNuyWdg6dIfVAa95h7Y+MCQEZg
jRDl1Bz7eWGO2c0Fq9OTz3IVLWpnmGwfW+HyaxizxFhV+FOj1GUVir9hylV7V0DU
QjIajyv/oeDWhFQ9wQECQCydhJ6NaNQOCZh+6QTrH3TC5MeBA1Yeipoe7+BhsLNr
cFG8s9sTxRnltcZl1dXaBSemvpNvBizn0Kzi8G3ZAgc=
-----END RSA PRIVATE KEY-----';

// IMPORTANT:
// - URL_Notify must be HTTPS and publicly reachable (not localhost), otherwise transaction can be cancelled.

// - Use a unique OrderID each time
$orderId = (string) time();

// Build POST params in the exact order you want them signed.
// (Signature must be added LAST.)
$postData = [
    'IPCmethod' => 'IPCPurchase',
    'IPCVersion' => '1.4',
    'IPCLanguage' => 'EN',
    
    // Replace with your own StoreID(can be found in your myPOS merchant account)
    'SID' => '000000000000010',

    // Replace with your own WalletNumber (Client Number from your myPOS merchant account)
    'WalletNumber' => '61938166610',

    'Amount' => '20.55',
 
    // Replace with the desired currency
    'Currency' => 'EUR',
    
    'OrderID' => $orderId,

    // Replace with your own URLs
    'URL_OK' => 'https://mypos.com/vmp/checkout-test/client/ipcOk',
    'URL_Cancel' => 'https://mypos.com/vmp/checkout-test/client/ipcCancel',
    'URL_Notify' => 'https://mypos.com/vmp/checkout-test/client/ipcNotify',

    // Set CardTokenRequest as per your needs (documentation above)
    'CardTokenRequest' => '0',

    // Replace with the KeyIndex provided to you by myPOS
    'KeyIndex' => '1',

    // Replace with PaymentParametersRequired value as per your needs (documentation above)
    'PaymentParametersRequired' => '1',

    // Set PaymentMethod as per your needs (documentation above)
    'PaymentMethod' => '1',

    'CustomerEmail' => 'name@website.com',
    'CustomerFirstNames' => 'John Santamaria',
    'CustomerFamilyName' => 'Smith',
    'CustomerPhone' => '+359888222333',
    'CustomerCountry' => 'DEU',
    'CustomerCity' => 'Hamburg',
    'CustomerZIPCode' => '20095',
    'CustomerAddress' => 'Kleine Bahnstr. 41',

    'Note' => 'Some note here',
    'Source' => 'Your Website Name',

    'CartItems' => 2,

    'Article_1' => 'HP ProBook 6360b sticker',
    'Quantity_1' => 2,
    'Price_1' => 10.00,
    'Currency_1' => 'EUR',
    'Amount_1' => 20.00,

    'Article_2' => 'Discount',
    'Quantity_2' => 1,
    'Price_2' => -3.45,
    'Currency_2' => 'EUR',
    'Amount_2' => -3.45,

    'delivery' => 4.00,
];

try {
    $postData['Signature'] = signPostData($postData, PRIVATE_KEY);
} catch (RuntimeException $e) {
    http_response_code(500);
    echo 'Signature error: ' . htmlspecialchars($e->getMessage(), ENT_QUOTES, 'UTF-8');
    exit;
}

// Render an auto-submitting form (the correct flow for IPCPurchase)
?>
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Redirecting to myPOS Checkout…</title>
</head>
<body>
  <p>Redirecting to payment page…</p>

  <form id="myposForm" method="post" action="<?= htmlspecialchars(API_URL, ENT_QUOTES, 'UTF-8') ?>">
    <?php foreach ($postData as $k => $v): ?>
      <input type="hidden" name="<?= htmlspecialchars((string)$k, ENT_QUOTES, 'UTF-8') ?>"
             value="<?= htmlspecialchars((string)$v, ENT_QUOTES, 'UTF-8') ?>">
    <?php endforeach; ?>
    <noscript>
      <button type="submit">Continue</button>
    </noscript>
  </form>

  <script>
    document.getElementById('myposForm').submit();
  </script>
</body>
</html>