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
Method Properties
Please note all properties must be in PascalCase!
| Property | Typical value | Type | Required | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Amount | 23.45 | Double | YES | The amount of the payment requested. | ||||||||||||||
| Currency | EUR | A(3) | YES | ISO 3-character currency code. The currency for the payment should be registered and approved. | ||||||||||||||
| OrderID | 20120331999999 | String | YES | Placeholder 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. | ||||||||||||||
| SID | 000000000000010 | String | YES | Store ID (SID) - Reference number for the Merchant Checkout in the myPOS system | ||||||||||||||
| WalletNumber | 61938166610 | String | YES | myPOS Client Number | ||||||||||||||
| KeyIndex | 1 | Int | YES | Indicates which key pair is being used. | ||||||||||||||
| URL_OK | http://site.ext/paymentOK | String | YES | The page where the cardholder should be redirected on successful payment. | ||||||||||||||
| URL_Cancel | http://site.ext/paymentNOK | String | YES | The page where the cardholder should be redirected when Cancel is pressed on the payment page. | ||||||||||||||
| URL_Notify* | https://site.ext/paymentNotify | String | YES | Address supplied by the partner, where the IPCPurchaseNotify API call will send the parameters for the successful payment. | ||||||||||||||
| PaymentMethod | 1 | String | NO | If the
Multiple payment methods: to enable multiple specific payment methods, you must provide the values as a comma-separated list. | ||||||||||||||
| CardTokenRequest | 0 | N(1) | YES | 0 – Do not request a payment card token. 1 – Store new card and request a token. Not applicable if PaymentMethod = 2. Disables PaymentMethod = 3 2 – Pay with a card and request a token. Not applicable if PaymentMethod = 2. Disables PaymentMethod = 3. Token will be available in IPCPurchaseNotify callback. | ||||||||||||||
| PaymentParametersRequired | 1 | N(1) | YES | 1- Full request (All parameters described as conditional are required in the request. The client will not be able to edit them on the payment page.) 2 – Simplified 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.) 3 – Simplified 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.) | ||||||||||||||
| CustomerEmail | name@website.com | String | Conditional | Conditional. The parameter is required when PaymentParametersRequired = 1. This is a customer’s email. | ||||||||||||||
| CustomerPhone | +23568956958 | String | NO | This is a customer’s phone. | ||||||||||||||
| CustomerFirstNames | John Santamaria | String | Conditional | Conditional. The parameter is required when PaymentParametersRequired = 1. All customer’s names without the surname. | ||||||||||||||
| CustomerFamilyName | Smith | String | Conditional | Conditional. The parameter is required when PaymentParametersRequired = 1. The customer’s surname. | ||||||||||||||
| CustomerCountry | DEU | String | NO | ISO3 country code | ||||||||||||||
| CustomerCity | Hamburg | String | NO | |||||||||||||||
| CustomerZIPCode | 20095 | String | NO | |||||||||||||||
| CustomerAddress | Kleine Bahnstr. 41 | String | NO | Customer’s address. | ||||||||||||||
| AccountSettlement | 11111111119 | N(11) | NO | Account for payment settlement. | ||||||||||||||
| expires_in | 86400.00 | Double | NO | Custom set time (in seconds) how long the session lifetime should be for the payment page (86400.00 seconds = 24 hours) | ||||||||||||||
| Note | String | NO | Text associated with the purchase. | |||||||||||||||
| CartItems | 2 | Int | Conditional | The 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. | ||||||||||||||
| Cart | Logical Holder | Logical Record | Conditional | Array 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. | ||||||||||||||
| Delivery | 5 | Double | NO | You 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>.
| Property | Typical value | Type | Description |
|---|---|---|---|
| Article | HP ProBook 6360b sticker | String | Name of an article in the shopping cart. |
| Quantity | 2 | Int | How many pieces of an article. |
| Price | 2.34 | Double | Price of a single unit. |
| Amount | 4.68 | Double | Quantity*Price for the article. |
| Currency | EUR | A(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.
| Property | Typical value | Type | Description |
|---|---|---|---|
| PartnerID | mps-p-XXXXXXXX | String | Identical number for the partner |
| ApplicationID | mps-app-XXXXXXXX | String | Identical number for the application |
Example Request
IPCmethod=IPCPurchase&
IPCVersion=1.4&
IPCLanguage=EN&
SID=000000000000010&
walletnumber=61938166610&
Amount=20.55&
Currency=EUR&
OrderID=1600091872&
URL_OK=https://site.ext/paymentOK&
URL_Cancel=https://site.ext/paymentNOK&
URL_Notify=https://site.ext/paymentNotify&
CardTokenRequest=0&
KeyIndex=1&
PaymentParametersRequired=1&
PaymentMethod=1&
customeremail=name@website.com&
customerfirstnames=John Santamari&
customerfamilyname=Smith&
customerphone=+359888222333&
customercountry=DEU&
customercity=Hamburg&
customerzipcode=20095&
customeraddress=Kleine Bahnstr. 41&&
Note=Some note here &
Source=&
CartItems=2&
Article_1=HP ProBook 6360b sticker &
Quantity_1=2&
Price_1=10&
Currency_1=EUR&
Amount_1=20&
Article_2=Discount&
Quantity_2=1&
Price_2=-3.45&
Currency_2=EUR&
Amount_2=-3.45&
delivery=4&
Signature=UzvTG8AKhBHsZQ6x+SjWlgZp8pAkJgMmQLYq/Pbs4a9znL4xaKEaGV82IzZjF+2UAQynjSAmHeVpJZT7R8q3lzQwKk9gmY8iDWsmig7NMPDK1Bqo3Zvrd64lCUpo19wy6kNLTljRUJ8eFqOJStTHP3TBZSnbEH5yGSjUXTMTfL0=