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:

login - user login. This login cannot be used to enter the personal account: only to authenticate REST requests.
password - the user's password.
nonce - one-time request ticket. This is a free-form string containing no more than 255 characters and without ";". You should generate a one-time ticket for each request. This is done so that an intruder, even if they have intercepted the request once, cannot repeat it.
hash - hash of the request fields. The description of each request indicates what fields are to be hashed. The values of these fields are separated with a semicolon and placed in one line, then, using the resulting UTF8 string, the SHA1 hash is calculated, and then it is encoded with base64. If the request does not contain an optional parameter, but the latter participates in hashing, then a blank string should be inserted into the hash instead of it. PHP cashing code: $hash = base64_encode(sha1($str, true)), where $str is the parameter string.

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 name	Description
paymentID	Payment ID in PayMaster (LMI_SYS_PAYMENT_ID field)

Hashed parameters: login;password;nonce;paymentID

Response parameters

Parameter	Description
State	Payment status, see List of payment statuses
ErrorCode	Failure reason code, see Error codes
Amount	Payment amount
CurrencyCode	3-letter ISO currency code
IsTestPayment	Test 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
PaymentAmount	Paid amount
PaymentCurrencyCode	Payment currency
PaymentID	Payment ID
PaymentMethod	Payment method
Purpose	Payment notes
SiteID	Payment recipient site ID
SiteInvoiceID	Account number (LMI_PAYMENT_NO parameter)
UserIdentifier	User identifier in the payment system
UserPhoneNumber	Buyer'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

Parameter	Description
invoiceID	Account number (LMI_PAYMENT_NO field)
siteAlias	Site 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

Parameter	Description
accountID	account 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
siteAlias	site ID (LMI_MERCHANT_ID). If specified, only the payments of the given site will be returned
periodFrom	the beginning of the time period (yyyy-MM-dd), UTC timezone. If specified, only payments after the specified date will be returned
periodTo	the end of the time period (yyyy-MM-dd), UTC timezone. If specified, only payments before the specified date will be returned
invoiceID	account number. If specified, only payments with the specified account number will be returned
state	Payment 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

Parameter	Description
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
Payments	Payment 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

Parameter	Description
paymentID	Payment ID in PayMaster
amount	Refund amount
externalID	Optional refund ID in the merchant's system (a non-unique value is allowed)

Response parameters

Parameter	Description
ExternalID	Refund operation ID
PaymentID	Payment ID
Status	Refund status, see List of refund statuses
Amount	Refund amount
Refund.ErrorCode	Error code if the refund is not successful (may be absent)
Refund.ErrorDesc	Textual 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

Parameter	Description
accountID	Account number in PayMaster
paymentID	Payment ID. If available, only the refunds for this payment are returned
periodFrom	The beginning of the time period (yyyy-mm-dd). If absent, there is no restriction for the earliest date
periodTo	The end of the time period, inclusive (yyyy-mm-dd). If absent, there is no restriction for the latest date
externalID	Optional 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

Parameter	Description
ErrorCode	Request error code (see Error codes)
Overflow	True, if the full list of refunds is not returned. In this case, specify a narrower range for the search
Refunds	Refund 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

Parameter	Description
paymentID	Payment ID in PayMaster (LMI_SYS_PAYMENT_ID field)
amount	Actual 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

Parameter	Description
paymentID	Payment ID in PayMaster (LMI_SYS_PAYMENT_ID field)
error	Optional 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

Parameter	Description
accountID	Account number in PayMaster. You can find this in the URL of the Account page in the personal account
periodFrom	The beginning of the time period (yyyy-MM-dd), UTC timezone. If specified, only documents created after the specified date will be returned
periodTo	The 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

Parameter	Description
Created	Document creation date
Description	Document description
DocumentID	Identifier for the content upload
FileName	File 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

Parameter	Description
documentID	Document 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

Parameter	Description
accountID	Account number in PayMaster. You can find this in the URL of the Account page in the personal account
periodFrom	The beginning of the time period (yyyy-MM-dd), UTC timezone
periodTo	The beginning of the time period (yyyy-MM-dd), UTC timezone

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

Response parameters

Parameter	Description
Created	Payment date
CurrencyCode	Payment currency code
TransferAmount	Payment amount
PaymentOrderID	Number of the payment order
RegisterID	Register ID

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

Parameter	Description
registerID	Register ID

Hashed parameters: login;password;nonce;registerID

Response parameters

Parameter	Description
PeriodFrom	The beginning of the time period
PeriodTo	The end of the time period
RegisterNumber	Register number
Operations	List of payments and refunds according to the register
OperationID	Operation ID
InvoiceID	Merchant's account number
Stamp	Operation date
CurrencyCode	Operation currency code
OperationAmount	Operation amount
TransferAmount	Payment amount for the operation

Directories

Error codes

Possible values of the ErrorCode field from PayMaster:

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

Payment statuses

Status	Description
INITIATED	Payment initiated
PROCESSING	The payment is being processed
COMPLETE	The payment has been completed successfully
CANCELLED	The payment was unsuccessful
HOLD	The funds are on hold

Refund statuses

Status	Description
PENDING	Queued for the refund operation
EXECUTING	Executing the payment refund transaction
SUCCESS	The refund has been completed successfully
FAILURE	The refund failed