NAV
  • HTTP-protocol
  • Return pages
  • Account settings
  • How to check a payment status
  • Automated invoicing of goods/services
  • Appendices
  • 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:

    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://psp.paymaster.tn/payment/init .

    ParameterMandatoryDescription
    LMI_MERCHANT_IDYesWebsite ID in PayMaster. You can find this ID in your Personal Account in the first column of the Website List page
    LMI_PAYMENT_AMOUNTYesThe 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_CURRENCYYesPayment currency ID. Paymaster recognizes both the 3-letter currency code (RUB, EUR) and ISO codes
    LMI_PAYMENT_NONoIn 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_DESCNo(*)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_BASE64No(*)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_MODENoAn 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_TYPENoHOLD is a pre-authorized payment (authorization held). The service will hold the authorization if the payment system allows it.
    LMI_INVOICE_CONFIRMATION_URLNoIf 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_URLNoIf 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_URLNoIf 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_METHODNoGET/POST, SuccessUrl method
    LMI_FAIL_URLNoIf 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_METHODNoGET/POST, SuccessUrl method
    LMI_PAYER_PHONE_NUMBERNoThe 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_EMAILNoThe 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_EXPIRESNoThe 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_IDYes (for integrators only)Sub-merchant identifier. Mandatory if merchant works as an aggregator.
    LMI_PAYMENT_METHODNoID 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 parametersNoPayMaster 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.

    ParameterDescription
    LMI_PREREQUESTThe preflight request flag. The value is always "1"
    LMI_MERCHANT_IDWebsite ID in PayMaster
    LMI_PAYMENT_NOInvoice number specified in the payment request form
    LMI_PAYMENT_AMOUNTPayment amount requested by the merchant. A fractional number separated with ".", no more than 2 characters after the separator
    LMI_CURRENCYPayment currency requested by the merchant.
    LMI_PAID_AMOUNTPayment 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_CURRENCYThe currency used to make payment. The currency inline code (not necessary ISO).
    LMI_PAYMENT_METHODID of the payment method selected by the buyer.
    LMI_SIM_MODEThe 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_DESCPayment 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 parametersDefined 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).

    ParameterDescription
    LMI_MERCHANT_IDWebsite ID in PayMaster.
    LMI_PAYMENT_NOThe merchant’s internal account number specified in the payment request
    LMI_SYS_PAYMENT_IDPayment ID in PayMaster. The merchant is recommended to save this ID
    LMI_SYS_PAYMENT_DATEPaymaster payment date. Format: YYYY-MM-DDThh:mm:ss, UTC time zone
    LMI_PAYMENT_AMOUNTA decimal number separated by a period (.). Not more than two characters after the period
    LMI_CURRENCYPayment currency requested by the merchant
    LMI_PAID_AMOUNTPayment 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_CURRENCYThe currency used to make payment. The currency inline code (not necessary ISO). For example: WMZ, YANDEX.RUB
    LMI_PAYMENT_METHODID of the payment method selected by the user
    LMI_SIM_MODEThe 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_DESCPayment 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_HASHThe request reference signature generated by the rules for generating a reference signature
    LMI_PAYER_IDENTIFIERBuyer ID in the payment system (WMID, masked bank card number, etc.)
    LMI_PAYER_COUNTRYThe buyer’s country code for their location if the payment system provides it
    LMI_PAYER_PASSPORT_COUNTRYThe buyer’s citizenship country code if the payment system provides it
    LMI_PAYER_IP_ADDRESSBuyer’s IP
    LMI_PAYMENT_SYSTEMPayment gateway code.
    Additional merchant parametersDefined 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

    ParameterDescription
    LMI_MERCHANT_IDWebsite ID in PayMaster
    LMI_PAYMENT_NOThe merchant’s internal account number specified in the payment request
    LMI_SYS_PAYMENT_IDPayment ID in PayMaster. The merchant is recommended to save this ID
    LMI_SYS_PAYMENT_DATEPayment date in PayMaster. The format is YYYY-MM-DDThh:mm:ss, UTC time zone
    LMI_PAYMENT_AMOUNTPayment amount requested by the merchant. A fractional number separated with ".", no more than 2 characters after the separator
    LMI_CURRENCYPayment currency requested by the merchant
    Additional merchant parametersDefined by the merchant. These include all additional fields from the payment order form

    Account settings

    Company site’s settings

    ParameterDescription
    StateThe status of the website’s readiness to accept test or real payments (*)
    Secret KeyA 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 duplicatesIf 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 siteIf 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 failureIf 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 URLURL where the Payment Notification request should be sent
    Invoice Confirmation URLURL 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, methodURL of the successful payment page and the request methods (GET, POST)
    Failure URL, methodURL of the failed payment page and the request methods (GET, POST)
    Allow URL overrideIt is allowed to use the return URLs indicated in the payment request form.
    Signature MethodSHA1 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:

    RoleAvailable actions
    CashierCan view a list of payments and issue invoices.
    AccountantHas the cashier options + can view the website information, documents, the list of transfers, payment statistics, make refunds, and issue invoices.
    ProgrammerCan view and edit the website settings, view the list of payments and the network exchange of transactions.
    AdministratorHas 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://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

    CodeDescription
    -1Unknown error
    -2Unknown network error
    -5Payment system network error
    -6Access denied
    -7Invalid request signature
    -8The Merchant rejected the invoice
    -9Invoice expired
    -10Payment system failure
    -11Cannot refund
    -12The refund amount exceeds
    -13Identifier not found
    -14New request with the same nonce
    -15The payment timeout period has expired
    -16Simulation error by Merchant
    -17You have declined to pay
    -18Invalid payment amount
    -19Insufficient funds
    -20Internal error, refresh the page
    -21A previous payment is in progress
    -22Authorization denied by the payment system
    -23Action does not match the payment status
    -24Payment system is temporarily suspended
    -253Dsec authorization failed
    -26Incorrect card number
    -27Card expired
    -28Card blocked
    -29Payment amount limit exceeded
    -30Number of payments limit exceeded
    -31Invalid card transaction