General

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

The Paymaster Direct protocol is designed for Companies (Sellers) charging funds from payers without their additional confirmation of each transaction (direct payments, Direct Debit). The following may serve as examples thereof: a subscription to news content, renewals of domain or hosting services, one-click purchases in games, and other environments where it is not desirable to exit the process, mobile applications, and so on.

Obviously, the Seller cannot carry out a direct debit without the payer's permission in the selected payment system. This permission (long-term acceptance, long-term payment order) represents their right to spend a specified amount within a specified period of time without payment authorization procedures (one-time acceptance). After they have obtained permission and as long as it is valid, funds can be charged at the level of inter-server communication (without the payer's participation).

The Seller should initiate the process of obtaining special permissions for this from the payment system that the paying client wishes to use. The Seller directs the payer to the Paymaster website; the payer interacts with the selected payment system, arranges the permissions (acceptance), and informs the Seller about the transaction status. After the transaction has been completed successfully, the Seller gets access to the direct debiting of the payer's funds.

Interaction scheme

Technical information

Data transmission

All requests should be directed to https://paymaster.ru using the client verification key.

The Seller can use one of two communication protocols:

• JWS
• Rest

The protocol type should be transmitted in the HTTP header type of each request (or in the get or post parameter). If there is no value, JWS is used by default. If the resp-type HTTP header (or in the get or post parameter) transmits the "xml" value, the response will be in XML format. If there is no value, the response will be in the JWS format. The signature data and signature transfer method are defined for each protocol.

Signature types

The Seller can use 2 types of request signatures:

• RSA - RSA (SHA256) signature, UTF-8 string encoding.
• Hash - SHA256 hash from "signature data; secret key", UTF-8 string encoding.

Payloads (data)

The header of all requests should contain the mandatory field iat (meaning "initiated at") with an integer value in seconds (UTC 1970-01-01T0:0:0Z). In each request, this field should contain the actual time when the request was sent. Service can use the iat field to prevent the risk of a repeated payment by comparing the time entered in this field and the specified time interval with the actual time interval.

JWS

The request content will take a form of messages in the format of JSON Web Signature (JWS). Signed request body: "HeaderEncoded.BodyEncoded" (the separator is a decimal point ".") - all parameters except the sign. HeaderEncoded is the UrlSafeBase64Encoding encoded message header, BodyEncoded is the UrlSafeBase64Encoding encoded request body. The signature is written with a decimal point (.) after Body ("HeaderEncoded.BodyEncoded.SignEncoded") and encoded with UrlSafeBase64Encoding.

The header should contain the standard alg field and should be coercible to RS256 ("alg":"RS256"). For PayMaster's convenience in implementing this specification, HTTPS is used in the "request" parameter to transfer the request data.

Rest

Signature generation for the REST request

{
var encoding = Encoding.UTF8;

var iat = GetUnixtime();
var payload = string.Empty
    + "access_token=" + accessToken
    + "&type=rest"
    + "&merchant_id=" + merchantId
    + "&merchant_transaction_id=" + transactionId
    + "&currency=" + currencyCode
    + "&amount=" + chargeAmount;

var dataToSign = string.Format("{0};{1};{2}", payload, iat, secretKey);
var bytesToSign = encoding.GetBytes(dataToSign);

string signBase64Encoded;
using (var sha256 = SHA256.Create())
{
    var sign = sha256.ComputeHash(bytesToSign);
    signBase64Encoded = Convert.ToBase64String(sign);
}

var result = SendRequest("/payment/init", payload, iat, signBase64Encoded);

Signed request body:

In the case of the Get request, this is "QueryString;iat", where: QueryString is the parameter string after the question mark in Url; iat is the "initiated at" field. In the case of the Post request, this is "Body;iat;secret key", where: Body is the request body; iat is the "initiated at" field; secret key is assigned by the Seller in their personal account ("Direct Signature Settings").

Requests are formed and sent with Get or Post (application/x-www-form-urlencoded) parameters. The signature is transmitted in the "sign" header or in the request parameters and encoded with Base64Encoding. Note for PHP developers: if $str is the parameter string, the hash is calculated as follows base64_encode(hash('sha256', $string, true)). URLs: for all types of requests listed below, PayMaster assigns a unique URL and passes it to the Seller. URLs for different types of requests do not need to be on the same host.

Authorization

Authorization is implemented with the OAuth 2.0 Authorization protocol. Authorization occurs as follows:

1. The Seller directs a user to the PayMaster Direct website. The user will be prompted to login if he/she is not yet authorized or has not permitted the Seller to use his/her Web wallet.
2. After authorization, the user is redirected to redirect_uri, specified by the Seller when redirecting the user, with the addition of a temporary token.
3. In PayMaster, the Seller generates a token request with a temporary token in order to get a permanent token.
   

Authorization Request

POST /direct/security/auth

The authorization request is defined by the OAuth protocol.

Request Parameters

This is defined by the OAuth protocol. Authorization request should be sent to /direct/security/auth. This URL will be used by the customers to authorize access to their account in the payment system by merchant. The processor for this URL accepts HTTP POST parameters. Following parameters should always be provided: !!!!URLS

Redirection example:

HTTP/1.1 302 Found
Location: https://www.example.com/?code=Pbl8KuP8vg

Reply parameters

The reaction to successful completion of the authorization process is the user's redirection to the provided redirect_uri with the following parameters:

POST /direct/security/token

The request is determined by the OAuth protocol. The Seller transmits the request to PayMaster to exchange the temporary token from the initial request to a permanent token to be used for future payments.

Request to get an access token

Request header:

{
  "iat": 1347447988,
  "alg": "RS256"
}

Request data:

{
  "client_id": "54bf4d42-b85c-48e2-8bda-ad0cf876f411",
  "code": "Pbl8KuP8vg",
  "grant_type": "authorization_code",
  "redirect_uri": "example.com"
}

Response:

{
  "access_token": "thN250MQ5scFlaa-1Kc61PP8gpAusuHgpJKoflAzF5g",
  "token_type": "bearer",
  "expires_in": 31535999,
  "account_identifier": "WebMoney Purse R111111111111"
}

POST /direct/security/token

The request is determined by the OAuth protocol. The Seller transmits the request to PayMaster to exchange the temporary token from the initial request to a permanent token to be used for future payments.

Request parameters

Reply parameters

Request to revoke an access token

Request header:

{
  "iat": 1384949320,
  "alg": "RS256"
}

Request data:

{
  "client_id": "1",
  "access_token": "7J-YBO_7cI9A5lb1U2PgLwoDyZxnTJhkM2o5XWIpjjE"
}

Response:

{
    "status": "complete"
}

POST /direct/security/revoke

To cancel the existing trust, the Seller transmits the request to PayMaster at the buyer's request. Once the request is completed, the access token will be revoked.

Request parameters

Reply parameters

Payment processing

Payment initiation

Request header:

{
  "alg": "RS256",
  "iat": 1347448234
}

Request data:

{
  "access_token": "thN250MQ5scFlaa-1Kc61PP8gpAusuHgpJKoflAzF5g",
  "merchant_id": "54bf4d42-b85c-48e2-8bda-ad0cf876f411",
  "merchant_transaction_id": "da47e4ee-ef12-469e-a9f0-1fa0d4a4365c",
  "amount": 1,
  "currency": "RUB"
}

Response:

{
    "status": "success",
    "processor_transaction_id": "36"
}

POST /direct/payment/init

To initiate a payment, the Seller transmits the request to PayMaster. A successfully completed request does not guarantee that the funds will be transferred to the Seller. It merely indicates that the user is in the payment system and is ready to pay the full amount at the time when the request is sent. If the request failed for any reason, the user will see an error message and will not be able to repeat the current payment.

Request Parameters

Reply parameters

Payment processing

Request header:

{
    "alg": "RS256",
    "iat": 1347448499
}

Request data:

{
  "access_token": "thN250MQ5scFlaa-1Kc61PP8gpAusuHgpJKoflAzF5g",
  "merchant_id": "54bf4d42-b85c-48e2-8bda-ad0cf876f411",
  "merchant_transaction_id": "da47e4ee-EF12-469e-a9f0-1fa0d4a4365c",
  "processor_transaction_id": "36"
}

Response:

{
  "status": "complete"
}

POST /direct/payment/complete

The request is required in order to complete the payment that was initiated by the payment initiation request. If the request is successful, the funds are considered to have been transferred from the client to the Seller. If the request fails for any reason and is marked as repeated, the user will be notified of the incomplete payment and he/she cannot repeat the current payment. If the request is returned with the in_progress status without the return code 200 or payment timeout, the request should be repeated later (the recommended time to resend the request is 15 seconds). The Seller should be able to process this request using only the merchant_transaction_id parameter to identify the transaction.

The processor_transaction_id parameter is used only for the executor's convenience. A payment processing request that is in its final state (processed or declined) should return the last result of the payment processing request. Requests that haven't reached "processed" or "declined" state within 120 hours from the start of the payment are regarded as cancelled and get the "declined" state.

Request Parameters

Reply parameters

Inline tokenization of cards

Additional methods allow the card to be linked (tokenized) directly from the store site (or from the application) without having to direct the user to the PayMaster website.

Authorization request

Request header:

{
  "alg": "RS256",
  "iat": 1347447988
}

Request data:

{
  "response_type": "code",
  "client_id": "54bf4d42-b85c-48e2-8bda-ad0cf876f411",
  "card_number": "5470000000000000",
  "card_holder": "IVAN IVANOV",
  "card_expiry": "04/18",
  "card_cvv": "123"
}

Response with token:

{
  "access_token":"thN2****zF5g",
  "token_type":"bearer",
  "expires_in":31535999,
  "account_identifier":"4************1234"
}

Response with 3DS request:

{
  "confirmation": "3DSecure",
  "code": "Pbl8KuP8vg",
  "redirect_url": "https://acs.somebank.ru",
  "pa_req": "bhzV****jzVL"
}

Response with the amount confirmation request:

{
  "confirmation": "DebitAmount",
  "code": "Pbl8KuP8vg",
}

POST /direct/authorize/card

Creating a link by bank card. Depending on the settings, additional confirmation may be required: via 3DSecure authorization or confirmation of a random amount that is locked on the card account.

Accordingly, the following response can be given to this request:

1. Access token
2. 3DSecure authorization settings
3. Indication of confirmation by locking a random amount
   

Request Parameters

Reply parameters

Confirmation of the amount charged

Request header:

{
  "alg": "RS256",
  "IAT": 1438247717
}

Request data:

{
  "response_type": "code",
  "client_id": "54bf4d42-b85c-48e2-8bda-ad0cf876f411",
  "code": "Pbl8KuP8vg",
  "amount": "83.98"
}

Response:

{
  "access_token":"thN2****zF5g",
  "token_type":"bearer",
  "expires_in":31535999,
  "account_identifier":"4************1234"
}

POST /direct/authorize/confirm

Request Parameters

3DSecure authorization

For 3DSecure authorization, the user should be redirected to a special page of the card issuer with the address of redirect_url. The following parameters are transmitted in the request:

• PaReq - encoded operation information, the pa_req value is substituted
• MD - the seller's request number, in order to identify the result
• TermUrl - the store page, in order to return the user after authorization

The POST method is used to send the request.

After authorization, the issuer will redirect the user to the Seller's page, as specified in TermUrl with the following fields:

• PaReq - encoded authorization result
• MD - the Seller's request number, copied from the request

To complete the linking, the obtained PaRes authorization result should be transmitted by calling the linking completion method.

Completion of the 3DSecure authorization

Request header:

{
  "alg": "RS256",
  "IAT": 1438647742
}

Request data:

{
"response_type": "code",
"client_id": "54bf4d42-b85c-48e2-8bda-ad0cf876f411",
"code": "Pbl8KuP8vg",
"pa_res": "eJzV****jX/L"
}

Response:

{
  "access_token":"thN2****zF5g",
  "token_type":"bearer",
  "expires_in":31535999,
  "account_identifier":"4************1234"
}

POST /direct/authorize/complete3ds

Request Parameters

Directories

Error codes

Appendix A

The example of the secret RSA key (used, for example, to sign a message in this document):

-----BEGIN RSA PRIVATE KEY----- 

MIIEowIBAAKCAQEAxw6Wp7mDULZksgyOfvDJYTpbwdQeDXWTG0mq6Z6geDT2naYm 
6q3bL17oy2IbBhXqrh6CzufPoppb3H8v+2mdR484fO955HwCWekVqaWUw5MzYpaq 
KbBqBepENi9lxaOGEg4Tuy48ARsmZc7KBubnEohA6BjDyx8AdwCLeKYNKhKSwzrl 
EKteCwWvqpXwszOck2zqK1VzDKZT8+G7g7aZH496sw16iBtId0QcI5sV/IAq58Vj 
QqCsKj7khweiPaxtWpsawnmylazm0O8/8Mj5d+GSLmO3hhT2ZoPpeSdvruC2RPLA 
YliWAl+NouqrAp2Di4yYFwKAX2nwvuZVFk5TiQIDAQABAoIBABzvwvjY3/0Atryn 
VKOhbzTiHeqcYk4ElID4AY96jstKr7sVJz0gTueg/Whrd5A36WisaMmZKzbxB3+T 
Qa9jmAiKCmUnDuonGNRnLM3/kxOnN2YSjuQGkDMR7h6OX1YOwnOndjjUrMZgYwGT 
wQylzluEUSMsTnIdrJygCKZeRTWjQYOwzIDoLamsaaYTq5MPKs30DDsiQW8GRRra 
510CiXuDzig10ohpqZNvXAjoGhSCWm83ZrCF9R4ge8D7WJju8zX5IJfaauqecfpK 
6Z8N87tScFJJ8sIEbsK0cAqKpDbeRo40r8rQG8CECzeDn9bzBbDUdiWE435INV8o 
mWaaH4ECgYEA/LMU2Cd+Md6/EQlbs7oqh60YnU0S/a5GlVuB60EQR209qXOGmG7G 
7nff3aCzMIKon5pm/QURmW7udLGekJKWeyXwUTmsE4xGfeFXBqmxV1nhCN0klj0h 
YCzYxYgSHNgDGCf9UXvecAa4SD1Axtdmww58mMCMz/n/jy+mtvZ7zlkCgYEAyagm 
QptkufmmHErUI0O3iCVtJqcbdBJBpUCj5hT4vwGiktOPTPxG1fNvi1QQ5uI5Ygo4 
+Hl2vNmHJj+TNsvoSdWI40Ad6wADKMZngkl+y/mPeQp2DZbmLyT49zO7XbVYKjSg 
JQudk3cvU31Jml2Zx/1QTONRCWNogmm144bU6LECgYBplY3VDxNMVQyyWp2lR9jz 
XaDWQNj5g/Lb/yMWn9XkckF8ZtfLIyYdh5rTKI0WbNF19nanq5GB8XbS7VAaihU0 
GVMDLTy34jml6RyKnSaLH/PF11itKZejbrmYN1WSFbOdSUAv5ri3SCeBj45cRq4a 
PBhVXsa3M3bTZg6bjfuG6QKBgHp3pSzEZKrRY8FA7I6yHG8Rk7VqvTCDudxbYm5k 
BCE0JACZfSja+UYMPozWNCGT+BeDb8/vLF5KmVpwN76KnXrhtO2WTdUfP8vumoQ0 
kE3eNPTklodwQkEVaiHvB/ZEINQY+70jzcH2GwbQSvf1qmQbgj3/u4JBHgI9otoY 
U4sxAoGBAO6mMtFer5H2XepHqQ+MELswkLX7K1WC7Pc/vLhRHxpaZX6Mcdn3KbB1 
B3eb8YtNmkUIFP4mYzmf/vL0qdOLFOzvJ0XwXGvSoDLspvwz/tZHqk6rtV22TA57 
j8PDSV2Byd8TAgedFnF3cPlVCXsvQVH7k5MBhEY4b1jJWp8U1i6M 

-----END RSA PRIVATE KEY-----

The example of the public RSA key (can be used to check the message signature in this document):

-----BEGIN PUBLIC KEY----- 

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxw6Wp7mDULZksgyOfvDJ
YTpbwdQeDXWTG0mq6Z6geDT2naYm6q3bL17oy2IbBhXqrh6CzufPoppb3H8v+2md 
R484fO955HwCWekVqaWUw5MzYpaqKbBqBepENi9lxaOGEg4Tuy48ARsmZc7KBubn 
EohA6BjDyx8AdwCLeKYNKhKSwzrlEKteCwWvqpXwszOck2zqK1VzDKZT8+G7g7aZ 
H496sw16iBtId0QcI5sV/IAq58VjQqCsKj7khweiPaxtWpsawnmylazm0O8/8Mj5 
d+GSLmO3hhT2ZoPpeSdvruC2RPLAYliWAl+NouqrAp2Di4yYFwKAX2nwvuZVFk5T 
iQIDAQAB 

-----END PUBLIC KEY-----

Appendix B

Test activities before accepting final settings:

1. Test the request using a token with the wrong code. Check the error message in the reply.
2. Test the request using a token with the wrong client_id. Check the error message in the reply.
3. Test the payment initialization request using an access token that is not identical to the one used on the authorization page.
4. Test the payment initialization request using a particular merchant_transaction_id parameter. Make an other request using the same value for the merchant_transaction_id parameter and make sure that processor_transaction_id contains the same value as in the first request.
5. Test the payment initialization request with a negative amount. Receive the error message.
6. Test the payment processing request without the processor_transaction_id parameter. Make sure that the request is successful.
7. Test the payment processing request with merchant_transaction_id and processor_transaction_id parameters that relate to different operations. Receive the error message.