NAV
  • General information
  • Methods of checking payment status
  • Refunds
  • Holds
  • Documents and payments
  • Directories
  • General information

    This is an old version of the API. Switch to the new API version.

    Interface method PayMaster's API methods are available via HTTP requests to the specific URLs.

    All the requests should be transmitted over TLS. The base endpoint address is https://psp.paymaster.tn

    Authenticating requests

    All requests are carried out on behalf of users that were created with the Automatic access login method. Users should have assigned the Cashier (acquiring a payment status and list of payments) or Accountant (Cashier + payment refund + list of refunds + confirmation and cancellation of holds) role. All requests must contain three fields: login, nonce, and hash, which are used to authenticate requests:

    If the request signature (hash) is incorrect, PayMaster returns the error code -7 (see Error codes).

    Attention! When the GET string is generated, all parameters (especially the hash) should be encoded with URL!

    Response format

    Response example:

    {
      "ErrorCode": 0,
      "Payment": {
        "PaymentID": 1,
        "SiteInvoiceID": "12345",
        "SiteID": 1,
        "CurrencyCode": "RUB",
        "Amount": 100,
        "PaymentCurrencyCode": "RUB",
        "PaymentAmount": 100,
        "State": "COMPLETE",
        "IsTestPayment": false,
        "LastUpdateTime": "2013-05-22T18:08:52"
      }
    }
    

    In response to the request, PayMaster always returns HTTP code 200. If another code is returned, there has been a server error while parsing the request. PayMaster generates responses in the JSON format.

    All responses contain a numeric ErrorCode field equal to the request error code (see Error codes). The parameters of request responses can be expanded by making the appropriate changes to the documentation. Write the response processing code in such as way as to take into account that you may receive additional fields.

    Methods of checking payment status

    Checking payment status by Payment ID

    Request example:

    GET /api/v1/getPayment?login=TestLogin&nonce=74DF1SM&hash=***&paymentid=1 HTTP/1.1
    Host: psp.paymaster.tn
    

    Response example:

    {
      "ErrorCode": 0,
      "Payment": {
        "PaymentID": 1,
        "SiteInvoiceID": "12345",
        "SiteID": 1,
        "CurrencyCode": "RUB",
        "Amount": 100,
        "PaymentMethod": "BankCard",
        "PaymentCurrencyCode": "RUB",
        "PaymentAmount": 100,
        "State": "COMPLETE",
        "Purpose": "Payment by order #12345",
        "IsTestPayment": false,
        "LastUpdateTime": "2017-05-22T18:08:52",
        "ErrorCode": 0
      }
    }
    

    GET /api/v1/getPayment

    This request is used to receive the payment information according to its number in PayMaster.

    Request parameters

    First nameDescription
    paymentIDPayment ID in PayMaster (LMI_SYS_PAYMENT_ID field)

    Hashed parameters: login;password;nonce;paymentID

    Response parameters

    ParameterDescription
    StatePayment status, see List of payment statuses
    ErrorCodeFailure reason code, see Error codes
    AmountPayment amount
    CurrencyCode3-letter ISO currency code
    IsTestPaymentTest payment indicator (the payment is made in test mode)
    LastUpdate (LastUpdateTime for JSON)Time of last status update. For completed payments, this is the payment completion time
    PaymentAmountPaid amount
    PaymentCurrencyCodePayment currency
    PaymentIDPayment ID
    PaymentMethodPayment method
    PurposePayment notes
    SiteIDPayment recipient site ID
    SiteInvoiceIDAccount number (LMI_PAYMENT_NO parameter)
    UserIdentifierUser identifier in the payment system
    UserPhoneNumberBuyer's phone number

    Checking payment status by invoice ID

    Request example:

    GET /api/v1/getPaymentByInvoiceID?login=TestLogin&nonce=74DF1SM&hash=***&invoiceid=1&siteAlias=yyy HTTP/1.1
    Host: psp.paymaster.tn
    

    Response example:

    {
      "ErrorCode": 0,
      "Payment": {
        "PaymentID": 1,
        "SiteInvoiceID": "12345",
        "SiteID": 1,
        "CurrencyCode": "RUB",
        "Amount": 100,
        "PaymentMethod": "BankCard",
        "PaymentCurrencyCode": "RUB",
        "PaymentAmount": 100,
        "State": "COMPLETE",
        "Purpose": "Payment by order #12345",
        "IsTestPayment": false,
        "LastUpdateTime": "2017-05-22T18:08:52"
      }
    }
    

    GET /api/v1/getPaymentByInvoiceID

    This request is used to receive the payment information according to its number in the merchant's accounting system.

    Request parameters

    ParameterDescription
    invoiceIDAccount number (LMI_PAYMENT_NO field)
    siteAliasSite ID (LMI_MERCHANT_ID field)

    Hashed parameters: login;password;nonce;invoiceID;siteAlias

    Response parameters

    See Payment details

    Getting a list of payments

    Request example:

    GET /api/v1/listPaymentsFilter?login=TestLogin&nonce=74DF1SM&hash=***&periodFrom=2011-12-01 HTTP/1.1
    Host: psp.paymaster.tn
    

    Response example:

    {
      "ErrorCode": 0,
      "Response": {
        "Overflow": false,
        "Payments": [{
            "PaymentID": 1,
            "SiteInvoiceID": "12345",
            "SiteID": 1,
            "CurrencyCode": "RUB",
            "Amount": 100,
            "PaymentMethod": "BankCard",
            "PaymentCurrencyCode": "RUB",
            "PaymentAmount": 100,
            "State": "COMPLETE",
            "Purpose": "Payment by order #12345",
            "IsTestPayment": false,
            "LastUpdateTime": "2017-05-22T18:08:52"
          }, {
            "PaymentID": 2,
            "SiteInvoiceID": "12346",
            "SiteID": 1,
            "CurrencyCode": "RUB",
            "Amount": 100,
            "PaymentMethod": "BankCard",
            "PaymentCurrencyCode": "RUB",
            "PaymentAmount": 100,
            "State": "COMPLETE",
            "Purpose": "Payment by order #12346",
            "IsTestPayment": false,
            "LastUpdateTime": "2017-05-22T18:08:52"
          }
        ]
      }
    }
    

    GET /api/v1/listPaymentsFilter

    This request is used to get a list of payments that meet the search criteria.

    Request parameters

    ParameterDescription
    accountIDaccount number in PayMaster. You can find this in the URL of the Account page in the personal account. You may not specify the accountID parameter if you have only one accoun
    siteAliassite ID (LMI_MERCHANT_ID). If specified, only the payments of the given site will be returned
    periodFromthe beginning of the time period (yyyy-MM-dd), UTC timezone. If specified, only payments after the specified date will be returned
    periodTothe end of the time period (yyyy-MM-dd), UTC timezone. If specified, only payments before the specified date will be returned
    invoiceIDaccount number. If specified, only payments with the specified account number will be returned
    statePayment status. If specified, only payments with the specified status will be returned

    Hashed parameters: login;password;nonce;accountID;siteAlias;periodFrom;periodTo;invoiceID;state

    Response parameters

    ParameterDescription
    Overflow"true" if the response does not include all payments that match the filter. If you do not need all the payments, narrow the search
    PaymentsPayment list (see Payment details)

    Refunds

    Payment refund

    Request example:

    POST /api/v1/refundPayment HTTP/1.1
    Host: psp.paymaster.tn
    Content-Type: application/x-www-form-urlencoded
    
    login=TestLogin&nonce=74DF1SM&hash=***&paymentID=131212&amount=23.10
    

    Response example:

    {
      "ErrorCode": 0,
      "Refund": {
        "RefundID": 1073969831,
        "ExternalID": null,
        "PaymentID": 131212,
        "Amount": 23.10,
        "ErrorCode": null,
        "ErrorDesc": null,
        "State": "EXECUTING"
      }
    }
    

    POST /api/v1/refundPayment

    This request is used to refund the payment.

    Request parameters

    ParameterDescription
    paymentIDPayment ID in PayMaster
    amountRefund amount
    externalIDOptional refund ID in the merchant's system (a non-unique value is allowed)

    Response parameters

    ParameterDescription
    ExternalIDRefund operation ID
    PaymentIDPayment ID
    StatusRefund status, see List of refund statuses
    AmountRefund amount
    Refund.ErrorCodeError code if the refund is not successful (may be absent)
    Refund.ErrorDescTextual description of the error. The description may be absent if the specific reason for failure is unknown

    Getting a list of refunds

    Request example:

    GET /api/v1/listRefunds?login=TestLogin&nonce=74DF1SM&hash=***&paymentID=131212&periodFrom=2017-01-01&periodTo=2017-11-11 HTTP/1.1
    Host: psp.paymaster.tn
    

    Response example:

    {
      "ErrorCode": 0,
      "Response": {
        "Overflow": false,
        "Refunds": [{
            "RefundID": 1234,
            "ExternalID": null,
            "PaymentID": 12345,
            "Amount": 10.2,
            "ErrorCode": null,
            "ErrorDesc": null,
            "LastUpdate": "2017-04-17T23:12:02",
            "State": "SUCCESS"
          }, {
            "RefundID": 1236,
            "ExternalID": null,
            "PaymentID": 12346,
            "Amount": 120,
            "ErrorCode": -15,
            "ErrorDesc": "we’ve been waiting for too long time",
            "LastUpdate": "2017-04-17T12:15:02",
            "State": "FAILURE"
          }
        ]
      }
    }
    

    GET /api/v1/listRefunds

    This request is used to get a list of refunds for the specified period.

    Request parameters

    ParameterDescription
    accountIDAccount number in PayMaster
    paymentIDPayment ID. If available, only the refunds for this payment are returned
    periodFromThe beginning of the time period (yyyy-mm-dd). If absent, there is no restriction for the earliest date
    periodToThe end of the time period, inclusive (yyyy-mm-dd). If absent, there is no restriction for the latest date
    externalIDOptional refund ID in the merchant's system

    Hashed parameters: login;password;nonce;accountID;paymentID;periodFrom;periodTo;externalID

    In this case, if the parameter is absent, an empty string (i.e. two consecutive semicolons) is inserted into the hashed string.

    Response parameters

    ParameterDescription
    ErrorCodeRequest error code (see Error codes)
    OverflowTrue, if the full list of refunds is not returned. In this case, specify a narrower range for the search
    RefundsRefund list. Each object is the same as the Response object of the first request

    Holds

    Confirm payment

    Request example:

    POST /api/v1/confirmPayment HTTP/1.1
    Host: psp.paymaster.tn
    Content-Type: application/x-www-form-urlencoded
    
    login=TestLogin&nonce=74DF1SM&hash=***&paymentID=1232&amount=11
    

    Response example:

    {
      "ErrorCode": 0,
      "Payment": {
        "PaymentID": 1,
        "SiteInvoiceID": "12345",
        "SiteID": 1,
        "CurrencyCode": "RUB",
        "Amount": 100,
        "PaymentMethod": "BankCard",
        "PaymentCurrencyCode": "RUB",
        "PaymentAmount": 100,
        "State": "COMPLETE",
        "Purpose": "Payment by order #12345",
        "IsTestPayment": false,
        "LastUpdateTime": "2017-05-22T18:08:52"
      }
    }
    

    POST /api/v1/confirmPayment

    This method is used to complete the payment with the held funds. In some cases, you can specify a smaller amount (than the holding value) to be charged.

    Request parameters

    ParameterDescription
    paymentIDPayment ID in PayMaster (LMI_SYS_PAYMENT_ID field)
    amountActual amount charged

    Hashed parameters: login;password;nonce;paymentID;amount

    Payment cancellation

    Request example:

    POST /api/v1/cancelPayment HTTP/1.1
    Host: psp.paymaster.tn
    Content-Type: application/x-www-form-urlencoded
    
    login=TestLogin&nonce=74DF1SM&hash=***&paymentID=1232&error=-8
    

    Response example:

    {
      "ErrorCode": 0,
      "Payment": {
        "PaymentID": 1,
        "SiteInvoiceID": "12345",
        "SiteID": 1,
        "CurrencyCode": "RUB",
        "Amount": 100,
        "PaymentMethod": "BankCard",
        "PaymentCurrencyCode": "RUB",
        "PaymentAmount": 100,
        "State": "COMPLETE",
        "Purpose": "Payment by order #12345",
        "IsTestPayment": false,
        "LastUpdateTime": "2017-05-22T18:08:52"
      }
    }
    

    POST /api/v1/cancelPayment

    This request is used to cancel the hold and unblock the payer's funds.

    Request parameters

    ParameterDescription
    paymentIDPayment ID in PayMaster (LMI_SYS_PAYMENT_ID field)
    errorOptional parameter. Error code from the list of Error codes

    Hashed parameters: login;password;nonce;paymentID;error

    Documents and payments

    List of documents

    Request example:

    GET /api/v1/listDocuments?login=TestLogin&nonce=74DF1SM&hash=***&accountID=123&periodFrom=2005-02-17&periodTo=2013-06-17&xml=1 HTTP/1.1
    Host: psp.paymaster.tn
    

    Response example:

    <RestController.RestResponse xmlns="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Controllers" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <ErrorCode>0</ErrorCode>
      <Response xmlns:a="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Models.REST" i:type="a:RestDocumentList">
        <a:Documents>
          <a:RestDocumentInfo>
            <a:Created>2013-06-17T12:57:03.6470638Z</a:Created>
            <a:Description>Acceptance report, March 2012</a:Description>
            <a:DocumentID>123456</a:DocumentID>
            <a:FileName>act_052012.xls</a:FileName>
          </a:RestDocumentInfo>
          <a:RestDocumentInfo>
            <a:Created>2013-06-17T12:57:03.6470638Z</a:Created>
            <a:Description>Invoice #1123 for 05/2012</a:Description>
            <a:DocumentID>123456</a:DocumentID>
            <a:FileName>doc_052012.xls</a:FileName>
          </a:RestDocumentInfo>
        </a:Documents>
      </Response>
    </RestController.RestResponse>
    

    GET /api/v1/listDocuments

    This request can be used to obtain a list of documents for the specified period.

    Request parameters

    ParameterDescription
    accountIDAccount number in PayMaster. You can find this in the URL of the Account page in the personal account
    periodFromThe beginning of the time period (yyyy-MM-dd), UTC timezone. If specified, only documents created after the specified date will be returned
    periodToThe beginning of the time period (yyyy-MM-dd), UTC timezone. If specified, only documents created before the specified date will be returned

    Hashed parameters: login;password;nonce;accountID;periodFrom;periodTo

    Response parameters

    ParameterDescription
    CreatedDocument creation date
    DescriptionDocument description
    DocumentIDIdentifier for the content upload
    FileNameFile name

    Document download

    Request example:

    GET /api/v1/getDocumentContent?login=TestLogin&nonce=74DF1SM&hash=***&documentID=123456 HTTP/1.1
    Host: psp.paymaster.tn
    

    GET /api/v1/getDocumentContent

    This request can be used in order to download a document according to its identifier. The response includes the content of the document.

    Request parameters

    ParameterDescription
    documentIDDocument ID

    Hashed parameters: login;password;nonce;documentID

    Getting a list of payments

    Request example:

    GET /api/v1/listTransfers?login=TestLogin&nonce=74DF1SM&hash=***&accountID=123&periodFrom=2005-02-17&periodTo=2013-06-17&xml=1 HTTP/1.1
    Host: psp.paymaster.tn
    

    Response example:

    <RestController.RestResponse xmlns="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Controllers" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <ErrorCode>0</ErrorCode>
      <Response xmlns:a="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Models.REST" i:type="a:RestTransferList">
        <a:Transfers>
          <a:RestTransferInfo>
            <a:Created>2017-09-04T09:36:29.186576Z</a:Created>
            <a:CurrencyCode>RUB</a:CurrencyCode>
            <a:PaymentOrderID>11223/4</a:PaymentOrderID>
            <a:RegisterID>54</a:RegisterID>
            <a:TransferAmount>101150.00</a:TransferAmount>
          </a:RestTransferInfo>
          <a:RestTransferInfo>
            <a:Created>2017-09-04T09:36:29.186576Z</a:Created>
            <a:CurrencyCode>RUB</a:CurrencyCode>
            <a:PaymentOrderID>11223/5</a:PaymentOrderID>
            <a:RegisterID>55</a:RegisterID>
            <a:TransferAmount>20000.00</a:TransferAmount>
          </a:RestTransferInfo>
        </a:Transfers>
      </Response>
    </RestController.RestResponse>
    

    GET /api/v1/listTransfers

    This request can be used to obtain a list of payments for the specified period.

    Request parameters

    ParameterDescription
    accountIDAccount number in PayMaster. You can find this in the URL of the Account page in the personal account
    periodFromThe beginning of the time period (yyyy-MM-dd), UTC timezone
    periodToThe beginning of the time period (yyyy-MM-dd), UTC timezone

    Hashed parameters: login;password;nonce;accountID;periodFrom;periodTo

    Response parameters

    ParameterDescription
    CreatedPayment date
    CurrencyCodePayment currency code
    TransferAmountPayment amount
    PaymentOrderIDNumber of the payment order
    RegisterIDRegister ID

    Register upload, grouped by payments

    Getting a transfer register

    Request example:

    GET /api/v1/getTransferRegister?login=TestLogin&nonce=74DF1SM&hash=***&registerID=123&xml=1 HTTP/1.1
    Host: psp.paymaster.tn
    

    Response example:

    <RestController.RestResponse xmlns="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Controllers" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
      <ErrorCode>0</ErrorCode>
      <Response xmlns:a="http://schemas.datacontract.org/2004/07/PaymasterBackoffice.Models.REST" i:type="a:RestRegisterInfo">
        <a:Operations>
          <a:RestRegisterOperationInfo>
            <a:CurrencyCode>RUB</a:CurrencyCode>
            <a:InvoiceID>SO223</a:InvoiceID>
            <a:OperationAmount>1000.00</a:OperationAmount>
            <a:OperationID>11022</a:OperationID>
            <a:Stamp>2017-09-04T00:00:00Z</a:Stamp>
            <a:TransferAmount>998.00</a:TransferAmount>
          </a:RestRegisterOperationInfo>
          <a:RestRegisterOperationInfo>
            <a:CurrencyCode>RUB</a:CurrencyCode>
            <a:InvoiceID>SO224</a:InvoiceID>
            <a:OperationAmount>1500.00</a:OperationAmount>
            <a:OperationID>11027</a:OperationID>
            <a:Stamp>2017-09-04T00:00:00Z</a:Stamp>
            <a:TransferAmount>1497.00</a:TransferAmount>
          </a:RestRegisterOperationInfo>
        </a:Operations>
        <a:PeriodFrom>2017-09-03T00:00:00Z</a:PeriodFrom>
        <a:PeriodTo>2017-09-04T00:00:00Z</a:PeriodTo>
        <a:RegisterID>54</a:RegisterID>
        <a:RegisterNumber>540/44</a:RegisterNumber>
      </Response>
    </RestController.RestResponse>
    

    GET /api/v1/getTransferRegister

    This request can be used to obtain a register that is used to pay funds.

    Request parameters

    ParameterDescription
    registerIDRegister ID

    Hashed parameters: login;password;nonce;registerID

    Response parameters

    ParameterDescription
    PeriodFromThe beginning of the time period
    PeriodToThe end of the time period
    RegisterNumberRegister number
    OperationsList of payments and refunds according to the register
    OperationIDOperation ID
    InvoiceIDMerchant's account number
    StampOperation date
    CurrencyCodeOperation currency code
    OperationAmountOperation amount
    TransferAmountPayment amount for the operation

    Directories

    Error codes

    Possible values of the ErrorCode field from PayMaster:

    CodeDescription
    -1Unknown error. The PayMaster system failed. In case of a repeated failure, please contact Technical Support.
    -2Network error. The PayMaster system failed. In case of a repeated failure, please contact Technical Support.
    -6No access. The login is incorrect or does not have the necessary rights to the requested information.
    -7Invalid request signature. The generated hash is invalid.
    -8The merchant declined the payment at the pre-request stage.
    -9The account expired.
    -10The payment system declined the payment.
    -13Cannot find the payment according to the account number.
    -14Repeat the request with the same nonce.
    -15The payment expired or was cancelled.
    -17The user refused to pay.
    -18Incorrect amount value (in the case of refunds, this refers to the amount value).
    -19The user does not have enough funds to pay.
    -22Cannot log into the payment system.
    -253D Secure authorization failed
    -26Invalid card number
    -27Card expired
    -28Card blocked
    -29Payment amont limit exceeded
    -30Payment quantity ;imit exceeded
    -31Inadmissible card operation

    Payment statuses

    StatusDescription
    INITIATEDPayment initiated
    PROCESSINGThe payment is being processed
    COMPLETEThe payment has been completed successfully
    CANCELLEDThe payment was unsuccessful
    HOLDThe funds are on hold

    Refund statuses

    StatusDescription
    PENDINGQueued for the refund operation
    EXECUTINGExecuting the payment refund transaction
    SUCCESSThe refund has been completed successfully
    FAILUREThe refund failed