NAV
  • Payment forms
  • Return pages
  • Account settings
  • How to check a payment status
  • Automated invoicing of goods/services
  • Appendices
  • Payment forms

    Workflow

    A company (merchant) interacts with PayMaster in the following way:

    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.

    alt text

    Payment order form

    To initiate a payment, this form is sent from the buyer’s browser (using the GET or POST method) to https://paymaster.ru/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
    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 ID of the payment method selected by the buyer.
    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 ID of the payment method selected by the user
    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
    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:

    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:

    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://paymaster.ru/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