HTTP-protocol
This is an old version of the API. Switch to the new API version.
Workflow
A company (merchant) interacts with PayMaster in the following way:
- The merchant generates (or requests) a payment order form for PayMaster.
- The buyer submits this form to the Paymaster payment page.
- The merchant chooses a payment method on the PayMaster website.
- The system sends a pre-request to the merchant Invoice Confirmation.
- The buyer completes the payment, the merchant receives a Payment Notification.
- The buyer is returned to the Success or Fail page of the merchant'swebsite.
Language of the payment form
The language of the payment form is primarily defined by the cookies stored on the buyer's computer. If there is no cookie, the language is determined by the buyer’s browser settings. If no language is specified in the browser settings or an unsupported language is selected, then English language will be used. The default language is English.
Payment order form
To initiate a payment, this form is sent from the buyer’s browser (using the GET or POST method) to https://psp.paymaster.tn/payment/init .
| Parameter | Mandatory | Description |
| LMI_MERCHANT_ID | Yes | Website ID in PayMaster. You can find this ID in your Personal Account in the first column of the Website List page |
| LMI_PAYMENT_AMOUNT | Yes | The payment amount to be received by the merchant from the buyer. The amount must be more than zero and the fractional part should be separated by a decimal point |
| LMI_CURRENCY | Yes | Payment currency ID. Paymaster recognizes both the 3-letter currency code (RUB, EUR) and ISO codes |
| LMI_PAYMENT_NO | No | In this field, the merchant sets the account number (purchase ID) in accordance with its accounting system. Although the parameter is not mandatory, we recommend you always set it. The ID must be a non-empty string |
| LMI_PAYMENT_DESC | No(*) | A product or service description. It is generated by the merchant. The maximum length is 255 characters. It must contain either a LMI_PAYMENT_DESC or LMI_PAYMENT_DESC_BASE64 field! |
| LMI_PAYMENT_DESC_BASE64 | No(*) | A product or service description in UTF-8 then encoded using the Base64 algorithm. It is generated by the merchant. If present, the decoded result will be substituted for LMI_PAYMENT_DESC. Due to this, the encoding on the merchant’s website does not matter. It must contain either a LMI_PAYMENT_DESC or LMI_PAYMENT_DESC_BASE64 field! |
| LMI_SIM_MODE | No | An additional field that determines the type of test mode. It is only valid in test mode and it can take one of the following values: 0 or none: With this service, all test payments will be successful; 1: With this service, all test payments will fail; 2: About 80% of payment requests will be successful while the other 20% will fail |
| LMI_PAYMENT_TYPE | No | HOLD is a pre-authorized payment (authorization held). The service will hold the authorization if the payment system allows it. |
| LMI_INVOICE_CONFIRMATION_URL | No | If present, the Invoice Confirmation request will be sent to the specified URL (instead of the one in the settings). If URL replacement is disabled in the website settings, the system will ignore this parameter |
| LMI_PAYMENT_NOTIFICATION_URL | No | If present, a Payment Confirmation request will be sent to the specified URL (instead of the one in the settings). If URL replacement is disabled in the website settings, the system will ignore this parameter |
| LMI_SUCCESS_URL | No | If present and in case the payment is successful, the user will be sent to the specified URL (instead of the one in the settings). If URL replacement is disabled in the website settings, the system will ignore this parameter |
| LMI_SUCCESS_METHOD | No | GET/POST, SuccessUrl method |
| LMI_FAIL_URL | No | If present and in case the payment is canceled, the user will be sent to the specified URL (instead of the one in the settings). If URL replacement is disabled in the website settings, the system will ignore this parameter |
| LMI_FAIL_METHOD | No | GET/POST, SuccessUrl method |
| LMI_PAYER_PHONE_NUMBER | No | The buyer’s telephone number in international format without the leading ‘+’ (e.g. 79031234567). PayMaster will use this data to notify the user about the payment status. Also, some payment systems require a telephone number |
| LMI_PAYER_EMAIL | No | The buyer’s e-mail. PayMaster will use this data to notify the user about the payment status. Also, some payment systems require an e-mail. |
| LMI_EXPIRES | No | The date and time until the issued invoice is valid. The format is YYYY-MM-DDThh:mm:ss, UTC time zone. PayMaster will make every effort to reject the payment upon expiration, but it cannot guarantee it. |
| LMI_SHOP_ID | Yes (for integrators only) | Sub-merchant identifier. Mandatory if merchant works as an aggregator. |
| LMI_PAYMENT_METHOD | No | ID of the payment method selected by the user. If absent, the user will need to select it later on the PayMaster payment page. A payment method is specified in square brackets next to the payment system name in the website settings (For example, Webmoney [WebMoney]). |
| Additional merchant parameters | No | PayMaster automatically processes all the form fields without LMI_ and AP_ prefixes and, after the payment has occurred, the system transfers them to the merchant’s website |
Autoparameters
When you transfer the request parameters and know in advance what parameters the payment system requires from the user, you can set their values. The parameter naming principle is as follows: if you want to transfer the custom Name parameter, you should transfer the AP_Name parameter in the payment order form. The custom parameters will not be involved in further data exchange.
Invoice Confirmation
When the buyer has selected a payment system and is ready to make payment, PayMaster sends this HTTP POST request to the merchant’s web server URL indicated in the settings. Depending on the settings, the merchant may ignore the request or else they must reply to it. The encoding for requests is UTF-8.
| Parameter | Description |
| LMI_PREREQUEST | The preflight request flag. The value is always "1" |
| LMI_MERCHANT_ID | Website ID in PayMaster |
| LMI_PAYMENT_NO | Invoice number specified in the payment request form |
| LMI_PAYMENT_AMOUNT | Payment amount requested by the merchant. A fractional number separated with ".", no more than 2 characters after the separator |
| LMI_CURRENCY | Payment currency requested by the merchant. |
| LMI_PAID_AMOUNT | Payment amount in the currency used by the buyer to make payment. A fractional number separated with ".", no more than 2 characters after the separator. |
| LMI_PAID_CURRENCY | The currency used to make payment. The currency inline code (not necessary ISO). |
| LMI_PAYMENT_METHOD | Payment method (if specified in payment order). |
| LMI_SIM_MODE | The test mode flag. This field is available only if the payment is made in test mode. The values are the same as in the payment order form |
| LMI_PAYMENT_DESC | Payment description as it is shown to the user. That is, if the payment order form contained a value for LMI_PAYMENT_DESC64, this request will contain the description already decoded from Base64. |
| Additional merchant parameters | Defined by the merchant. These include all additional fields from the payment order form |
In response to the request, the merchant’s website may generate a blank document or the message "YES" (case-insensitive) indicating that the merchant accepts the payment. Any other response from the merchant will be interpreted as a refusal to accept the payment and the user will receive an error message.
Payment Notification
If the payment is successful, PayMaster sends this HTTP POST request to the merchant. It is important to understand that the Payment Notification request is the only one that the merchant should take into account when considering whether a payment is accepted (provide a service, etc.)
If the merchant for some reason could not process the Payment Notification correctly, they will have to deal with they user who paid money but did not receive the promised goods or services from the merchant.
The system has an option to retry the Payment Notification request with the same values of key parameters in case the first attempt failed.
Whatever these option settings are in the merchant’s personal account, you should check the LMI_PAYMENT_NO and LMI_SYS_PAYMENT_ID uniqueness in the notification sent by PayMaster and prevent repetition of services (re-shipment of goods) in case if you receive the Payment Notification with the same parameters.
Also, with PayMaster, the merchant can verify the payment status by payment number, date, etc. (both interactively and programmatically).
| Parameter | Description |
| LMI_MERCHANT_ID | Website ID in PayMaster. |
| LMI_PAYMENT_NO | The merchant’s internal account number specified in the payment request |
| LMI_SYS_PAYMENT_ID | Payment ID in PayMaster. The merchant is recommended to save this ID |
| LMI_SYS_PAYMENT_DATE | Paymaster payment date. Format: YYYY-MM-DDThh:mm:ss, UTC time zone |
| LMI_PAYMENT_AMOUNT | A decimal number separated by a period (.). Not more than two characters after the period |
| LMI_CURRENCY | Payment currency requested by the merchant |
| LMI_PAID_AMOUNT | Payment amount in the currency used by the buyer to make payment. A fractional number separated with ".", no more than 2 characters after the separator |
| LMI_PAID_CURRENCY | The currency used to make payment. The currency inline code (not necessary ISO). For example: WMZ, YANDEX.RUB |
| LMI_PAYMENT_METHOD | Payment method |
| LMI_SIM_MODE | The test mode flag. This field is available only if the payment is made in test mode. The values are the same as in the payment order form |
| LMI_PAYMENT_DESC | Payment description as it is shown to the user. That is, if the payment order form contained a value for LMI_PAYMENT_DESC64, this request will contain the description already decoded from Base64 |
| LMI_HASH | The request reference signature generated by the rules for generating a reference signature |
| LMI_PAYER_IDENTIFIER | Buyer ID in the payment system (WMID, masked bank card number, etc.) |
| LMI_PAYER_COUNTRY | The buyer’s country code for their location if the payment system provides it |
| LMI_PAYER_PASSPORT_COUNTRY | The buyer’s citizenship country code if the payment system provides it |
| LMI_PAYER_IP_ADDRESS | Buyer’s IP |
| LMI_PAYMENT_SYSTEM | Payment gateway code. |
| Additional merchant parameters | Defined by the merchant. These include all additional fields from the payment order form |
In response to this request, the merchant may return anything: PayMaster will ignore the response.
If a network request transfer failure occurred, in your personal account you can configure the request to be re-sent.
Request hash generation
To ensure the request integrity, PayMaster generates a reference signature for the Payment Notification request according to the following rule:
Place in one line the following parameters separated by ‘;’:
LMI_MERCHANT_ID, LMI_PAYMENT_NO, LMI_SYS_PAYMENT_ID, LMI_SYS_PAYMENT_DATE, LMI_PAYMENT_AMOUNT, LMI_CURRENCY, LMI_PAID_AMOUNT, LMI_PAID_CURRENCY, LMI_PAYMENT_SYSTEM, LMI_SIM_MODE (all of these are standard, except LMI_PAYMENT_DESC).
If any parameter is not available, use an empty string instead of it. Note that LMI_SIM_MODE in live(!) mode is always considered empty.
If the request is a Payment Status Notification, then LMI_PAYMENT_STATUS separated by a semicolon will be added to the parameters.
An additional ‘;’ and a secret word from the website settings will be added into the string. The resulting string is interpreted as a UTF-8 byte array and the MD5 or SHA1 hash will be calculated from this string (depending on the method specified in the merchant’s settings).
This hash (a sequence of bytes) will be transformed into a Base64 string. This string is the LMI_HASH value.
We recommend using a signature generation tool to verify the correctness of the algorithm.
Return pages
Successful and failed payment pages
| Parameter | Description |
| LMI_MERCHANT_ID | Website ID in PayMaster |
| LMI_PAYMENT_NO | The merchant’s internal account number specified in the payment request |
| LMI_SYS_PAYMENT_ID | Payment ID in PayMaster. The merchant is recommended to save this ID |
| LMI_SYS_PAYMENT_DATE | Payment date in PayMaster. The format is YYYY-MM-DDThh:mm:ss, UTC time zone |
| LMI_PAYMENT_AMOUNT | Payment amount requested by the merchant. A fractional number separated with ".", no more than 2 characters after the separator |
| LMI_CURRENCY | Payment currency requested by the merchant |
| Additional merchant parameters | Defined by the merchant. These include all additional fields from the payment order form |
Account settings
Company site’s settings
| Parameter | Description |
| State | The status of the website’s readiness to accept test or real payments (*) |
| Secret Key | A secret word is set independently in the personal account (the Technical data section), the key should not contain any Cyrillic characters as well as special symbols like <, >, . The secret word is not transferred by the network and is used to generate a reference signature for the Payment Notification request. |
| Check for account number duplicates | If this parameter is enabled, PayMaster will not allow sending payment requests with a duplicate (or missing) LMI_PAYMENT_NO. The system will immediately send the user the "wrong payment number" error and forward them to the Failure URL page |
| User has to return to the site | If this feature is enabled, the Payment Notification will be sent only after the user returns to the merchant’s website. Prior to that, the payment will will be given the status "Paid". Payments with this status are paid to the merchant and are included in the register of payable transfers but not in the register of daily payments. |
| Repeat the Payment Notification in case of failure | If the parameter is enabled, the Payment Notification will be repeated in case of network failures. Before enabling it, make sure that the funds will not be re-charged to the payer (fulfillment of the payment obligations) when the Payment Notification is received anew |
| Result URL | URL where the Payment Notification request should be sent |
| Invoice Confirmation URL | URL where the Invoice Confirmation request should be sent. If the parameter is disabled, it is considered equal to the Result URL (i. e. the request will be sent to the Result URL with LMI_PREREQUEST=1 flag) |
| Success URL, method | URL of the successful payment page and the request methods (GET, POST) |
| Failure URL, method | URL of the failed payment page and the request methods (GET, POST) |
| Allow URL override | It is allowed to use the return URLs indicated in the payment request form. |
| Signature Method | SHA1 or SHA256A is used to generate a hash |
Site status
The site may be in one of five states:
- Test mode, waiting for approval
- Test mode
- Production mode
- Disconnected
- Blocked
After the merchant has created a website and added the required data, it awaits verification. After PayMaster employees have verified the website, its status will be changed to Test. Then, the merchant’s authorized representatives may change its status to Production mode.
User roles
The merchant may give their employees access to the website and assign them one of the following roles:
| Role | Available actions |
| Cashier | Can view a list of payments and issue invoices. |
| Accountant | Has the cashier options + can view the website information, documents, the list of transfers, payment statistics, make refunds, and issue invoices. |
| Programmer | Can view and edit the website settings, view the list of payments and the network exchange of transactions. |
| Administrator | Has the accountant and programmer options + can change a website’s status and manage websites and users. |
How to check a payment status
PayMaster provides the following ways to check the status of a payment by its number:
- Manually in the merchant’s personal account on the PayMaster website.
- By sending a REST HTTP request to the PayMaster server. You can find more information about the REST interfaces here
- By searching for a payment in the successful payments file. Every day the service can (optional) send an email to the merchant’s email address with a list of transactions made (those with the Payment Notification generated and sent) and refunds for the previous period.
Automated invoicing of goods/services
Using PayMaster, companies/merchants can accept invoice based payments, greatly simplifying their operations with buyers. This is suitable for merchants who need to check the availability of goods before payment.
Workflow
Invoices are generated by sending a request to https://psp.paymaster.tn/builtinpayment/initonly. The request parameters are the same as in the standard payment request form but they differ as follows:
When generating invoices, the signature should contain the following parameters: LMI_MERCHANT_ID, LMI_PAYMENT_AMOUNT (the fractional part separated with a dot with two symbols required after it), LMI_CURRENCY, SecretKey (the value is set in the personal account). The values of these fields are separated with a semicolon (;) and placed in one line, then using the resulting UTF8-string, the SHA1 (\sha256\md5 depending on the Signature type option for the website) hash is calculated and then it is encoded with base64. PHP hash code when using SHA1:
$authhash = base64_encode(sha1($str, true)), where $str is the string parameter. Pay attention that base64 is calculated from the hash byte array and not from its hex value.
Appendices
Error codes
| Code | Description |
| -1 | Unknown error |
| -2 | Unknown network error |
| -5 | Payment system network error |
| -6 | Access denied |
| -7 | Invalid request signature |
| -8 | The Merchant rejected the invoice |
| -9 | Invoice expired |
| -10 | Payment system failure |
| -11 | Cannot refund |
| -12 | The refund amount exceeds |
| -13 | Identifier not found |
| -14 | New request with the same nonce |
| -15 | The payment timeout period has expired |
| -16 | Simulation error by Merchant |
| -17 | You have declined to pay |
| -18 | Invalid payment amount |
| -19 | Insufficient funds |
| -20 | Internal error, refresh the page |
| -21 | A previous payment is in progress |
| -22 | Authorization denied by the payment system |
| -23 | Action does not match the payment status |
| -24 | Payment system is temporarily suspended |
| -25 | 3Dsec authorization failed |
| -26 | Incorrect card number |
| -27 | Card expired |
| -28 | Card blocked |
| -29 | Payment amount limit exceeded |
| -30 | Number of payments limit exceeded |
| -31 | Invalid card transaction |