Payment Session Create

Programmatically Launch a Payment Session via API

Purpose

This method initiates a payment session for a customer (purchase) to be used in other IPC API calls.

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
IPCmethodIPCPaymentSessionCreateStringYESThis 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
OrderID20120331999999String (max 255)YESPlaceholder for the merchant. Used to put some data that will help the merchant to recognize for which order is the payment. Up to 255 characters.
Amount23.45DoubleYESThe amount of payment requested.
CurrencyEURA(3)YESISO 3-character currency code. The currency for the payment should be registered and approved.
SID000000000000010StringYESStore ID (SID) - Reference number for the Merchant Store in the myPOS system
WalletNumber61938166610StringYESmyPOS Client Number
KeyIndex1IntYESIndicates which key pair is being used.
RequestToken0N(1)NO0 – Do not request a payment card token. 1 – Pay with a card and request a token. Token will be available in IPCPurchaseNotify callback.
AccountSettlement11111111119N(11)NOAccount for payment settlement
NotePromo purchaseStringNOText associated with the purchase.
CartItems2IntYESThe 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 RecordYESArray provided by the Merchant. The array describes the content of the shopping cart. The content will be displayed on the myPOS Checkout payment page.
OutputFormatXMLStringNOOutput format of data. The property can be “XML” or “JSON”. If it is not specified in the request, the default value is “XML”.

Cart Logical Record

Cart logical record consists of standard POST parameters with the form name=value. For each 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)It should be the same currency as in the purchase amount.

Example Request

<?php

declare(strict_types=1);

/**
 * Calls an API endpoint using POST and returns the decoded JSON response.
 *
 * @param string $url
 * @param array $data
 * @return array|null
 */
function callApi(string $url, array $data): ?array
{
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_POST, true);
    curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($data));
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_TIMEOUT, 30);
    $result = curl_exec($curl);
    if ($result === false) {
        error_log('Curl error: ' . curl_error($curl));
        curl_close($curl);
        return null;
    }
    curl_close($curl);
    $decoded = json_decode($result, true);
    if (json_last_error() !== JSON_ERROR_NONE) {
        error_log('JSON decode error: ' . json_last_error_msg());
        return null;
    }
    return $decoded;
}

/**
 * Signs the concatenated POST data using RSA private key and returns the signature.
 *
 * @param array $postData
 * @param string $privateKey
 * @return string
 */
function signPostData(array $postData, string $privateKey): string
{
    $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-----';

// Prepare POST data
$orderId = uniqid((string)rand(), true);
$postData = [
    'IPCmethod'     => 'IPCPaymentSessionCreate',
    'IPCVersion'    => '1.4',
    'IPCLanguage'   => 'EN',
    'OrderID'       => $orderId,
    'Amount'        => 0.50,
    'Currency'      => 'EUR',
    'SID'           => '000000000000010',
    'WalletNumber'  => '61938166610',
    'KeyIndex'      => 1,
    'RequestToken'  => 0,
    'CartItems'     => 1,
    'Article_1'     => 'Cart Store Test',
    'Quantity_1'    => 1,
    'Price_1'       => 0.50,
    'Amount_1'      => 0.50,
    'Currency_1'    => 'EUR',
    'OutputFormat'  => 'JSON',
];

// Sign and add signature
try {
    $postData['Signature'] = signPostData($postData, PRIVATE_KEY);
} catch (RuntimeException $e) {
    die('Signature error: ' . $e->getMessage());
}

// Call API
$apiResponse = callApi(API_URL, $postData);
if ($apiResponse === null) {
    die('API call failed.');
}

// Output session token
if (isset($apiResponse['SessionToken'])) {
    echo 'Session Token: ' . htmlspecialchars($apiResponse['SessionToken'], ENT_QUOTES, 'UTF-8');
} else {
    echo 'Session token not found in response.';
}

Response Properties

PropertyTypical valueTypeDescription
SessionTokeneyJpbG...JVNjdnLS0ifQString (<255)Session token used for other IPC Calls
Created2023-06-15T07:07:14ZDateTimeCreation date of the token
ExpDate2023-06-15T08:07:15ZDateTimeExpire date of the session
Status0Int0 indicates success; any other value indicates an error.
StatusMsgSuccessStringHuman-readable message describing the result of the operation.
Signature(Base64 encoded string)StringSignature used to verify the authenticity of the response.

JSON

{
  "Status": 0,
  "StatusMsg": "Success",
  "Created": "2023-06-15T10:04:17Z",
  "ExpDate": "2023-06-15T11:04:18Z",
  "SessionToken": "eyJpbmZvIjoiMzQ2Mzk0LVZNSklVQ0JYTC0xLTEtRVVSLTUwLWJnIiwiaWRlbnRpdHkiOiJJcENSN1VmfmVic1BqeFg4SG9FUUZYTGU4MVdQTlYybmRUMlVONnppbUVVVnVzZ0tNRHhhbGRsWGFuRUtsYU1DMGVXbGFRLS0ifQ==",
  "Signature": "NgSPrI16qrt91HU733Z2KtwW62MtsUptWVLtVF1OGLvG7LKl441aUwqD6fXYmIF/sR6/mbJiFVA2o/v0Izusqb+vHRvmqBdC1+p8n5Zt3mR6BwQZxj1PFWJ0abTUgy4AhJqbkRo47feXCoMxeT8r3n83pkD+MBoM6IaQjZlGRL4="
}

XML

<ipc_response is-array="true">
  <Status>0</Status>
  <StatusMsg>Success</StatusMsg>
  <Created>2023-06-15T07:07:14Z</Created>
  <ExpDate>2023-06-15T08:07:15Z</ExpDate>
  <SessionToken>eyJpbmZvIjoiMzQ2Mzk0LVZNSklVQ0JYTC0xLTEtRVVSLTUwLWJnIiwiaWRlbnRpdHkiOiJ0cVMyR3gzUmY1TnNEbjAxVFJRTlNwUmNwSmJKNEpMU01oYThtWlh3aFlVWEhYamszVkdjdFIzb21mb3dXTllZOFJVNjdnLS0ifQ</SessionToken>
  <Signature>QCwWG6KQX53mkelgakPuIUqYGColcjprAaMGb+GjPNcJpnbGfitaef0GBhOa7Qb5wC659yKZaGcZvBuwqXi5TdbB6Mr5M+XXhp8BouPpMVoiuSpJSmQuq9pT/pmf7OeTfJ1fguLcShUdYS1ed1aLrk5O5Dmfj7535JI75ZAvezc=</Signature>
</ipc_response>