NAV
  • General
  • Authorization
  • Initiate Payment Request
  • Complete Payment Request
  • Appendix A
  • Appendix B
  • General

    Host: Endpoint base url https://paymaster.ru

    Encoding: All text content will be encoded in UTF-8.

    Transport: All requests will be sent over HTTPS with client key verification.

    Payloads: Request contents will be a JSON Web Signature (JWS) message. The only signing algorithm acceptable in this protocol will be SHA-256 using RSA, identified in the JWS standard as "RS256". The header will contain the standard "alg" field which will always be set to "RS256". It will also contain a non-standard "iat" field (meaning "Issued At") which will contain an integer number of seconds since 1970-01-01T0:0:0Z as measured in UTC. The "iat" field can be used by the Processing Service to prevent replay attacks by checking that the time present in that field is within a limited window from the current time. The payload will be set to the value of the HTTP parameter named "request" for convenience of the Processing Service implementing this specification.

    URLs: Each request method below will be given a unique URL by the Processing Service and reported to Merchant. The URLs for each method are not required to reside on the same host.

    Authorization

    The authorization flow follows the OAuth 2.0 Authorization protocol.

    The authorization flow is as follows:

    1. User is sent to the Processing Service’s website authorization request. The user is prompted to login if they are not already and grant authorization to Merchant to use their web wallet.

    2. Processing Service returns a redirect response (HTTP 302) with the callback URL to Merchant. The user’s browser will make the request to the callback URL. The callback URL should have the correct parameters set as described below.

    3. Merchant will make the token request to the Processing Service with the temporary token to receive the permanent token.

    Authorization Request

    Example redirect:

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

    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

    Parameter Datatype Required Description
    response_type String Yes Constant. Should always be set to "code"
    client_id String Yes ID of the Merchant's site account. ID could be obtained from sites list in the merchant account
    redirect_uri String Yes The URL where the redirect response should send the customer when they successfully complete the authorization process
    scope String Yes The permission scope being requested. For testing

    The response to completing the authorization process should be a redirect to the redirect_uri provided. The redirect URL should be given the following parameters:

    Parameter Datatype Required Description
    code String Yes The temporary authorization token that will be exchanged for the permanent token. This token should expire in a period of time no greater than 10 minutes after the originating request.

    If the user denies access to their account, or an error occurs, the user should not be redirected to the redirect_uri.

    Access Token Request

    Header:

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

    Payloads:

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

    Response:

    HTTP/1.1 200 OK
    {
      "access_token": "thN250MQ5scFlaa-1Kc61PP8gpAusuHgpJKoflAzF5g",
      "token_type": "bearer",
      "expires_in": 31535999,
      "account_identifier": "WebMoney Purse R111111111111"
    }
    

    This is defined by the OAuth protocol. Access token request should be sent to /direct/security/token. The request will be issued by Merchant to the Processing Service to exchange a temporary token from the originating request for a permanent token that can be used for future payments. HTTP Method: POST

    Request parameters

    Parameter Datatype Required Description
    client_id String Yes ID of the Merchant's site account. ID could be obtained from sites list in the merchant account
    code String Yes The temporary token assigned during the authorization request
    grant_type String Yes Constant. Should always be set to "authorization_code"
    redirect_uri String Yes Should always exactly match the redirect_uri provided in the authorization request

    Responce parameters

    Parameter Datatype Description
    access_token String The permanent authorization token used for subsequent requests
    token_type String Constant. Should always be set to "bearer"
    expires_in Number The number of seconds from the issue time until this token expires
    account_identifier String The identifier for the customer’s account in the Processing Service’s system that is meaningful to the customer. This will be displayed to the user to differentiate different accounts with the same Processing Service
    error String Reason that the access token request failed. Valid values are: "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", and "invalid_scope"

    Initiate Payment Request

    Header:

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

    Payloads:

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

    Response:

    HTTP/1.1 200 OK
    {
     "status": "success", 
     "processor_transaction_id": "36"
    }
    

    Initiate payment request should be sent to /direct/payment/init. This request will be issued to initiate a payment to Merchant. If the request completes successfully, the funds are not guaranteed. A successful response only indicates that the user exists in the Processing Service’s system and that they are able to pay the requested amount in full at the time of the request. If this request fails for any reason, it will be reported to the user as a failed payment and will not be retried. !!!!(URKS)

    HTTP Method: POST

    Request parameters

    Parameter Datatype Required Description
    access_token String Yes The access token provided to Merchant previously
    merchant_id String Yes The ID of Merchant in the Processing Service’s system. This is the same as the "client_id" used to obtain the access_token
    merchant_transaction_id String Yes The transaction ID generated in Merchant’s system. This should be used to prevent duplicate payment requests if this request times out or does not return the processor_transaction_id
    amount Number Yes The amount to be transferred from the customer to Merchant
    currency String Yes The three-letter ISO code for the currency to transfer (should always be RUB)
    description String Optional Description (max 255 chars) for the payment
    custom String Optional Additional form fields which do not have "ap_" in the prefix name are automatically processed by PayMaster and transmitted to the Company site after payment is made

    Responce parameters

    Parameter Datatype Description
    status String The result of this request. Valid values are "success" and "failure"
    processor_transaction_id String The ID of this transaction in the payment Processing Service’s system. (Present only on success)
    error_code String The reason for the error response. See error codes below. (Present only on failure)
    error String A free-form description of the error that occurred which caused the request to fail. This is for use in troubleshooting and will not be displayed to the user. (Present only on failure)

    Complete Payment Request

    Header:

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

    Payloads:

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

    Response:

    HTTP/1.1 200 OK
    {
     "status": "complete"
    }
    

    Complete payment request should be sent to /direct/payment/complete. This request will be issued to complete a payment that was previously requested with an initiate payment request. If the request completes successfully, the funds are considered to be transferred from the user to Merchant. If this request fails for any reason that is not marked as retriable, the payment will be reported to the user as failed and will not be retried. If the request returns with a status of "in_progress", a non-200 return code, or the request times out, this request will be retried at a later time. Merchants implementing this handler must be able to process the request using only the merchant_transaction_id to identify the transaction. The processor_transaction_id is provided only for convenience of the implementor. Complete payment requests for payments which have reached a terminal state (either complete or failure) should return the last result of the complete payment request. Payment requests which do not reach a state of "complete" or "failure" within 120 hours from the initiate payment request should be considered cancelled and should return a status of "failure".

    HTTP Method: POST

    Request parameters

    Parameter Datatype Required Description
    access_token String Yes The access token provided to Merchant previously
    merchant_id String Yes The ID of Merchant in the Processing Service’s system. This is the same as the "client_id" used to obtain the access_token
    merchant_transaction_id String Yes The ID of this transaction in Merchant’s system
    processor_transaction_id String Optional The ID of this transaction in the Processing Service’s system. This will be included only if the initiate payment request returned this value and did not time out

    Responce parameters

    Parameter Datatype Description
    status String The result of this request. Valid values are "success" and "failure"
    error_code String The reason for the error response. See error codes below. (Present only on failure)
    error String A free-form description of the error that occurred which caused the request to fail. This is for use in troubleshooting and will not be displayed to the user. (Present only on failure)

    Error codes

    Code Description
    invalid_request The request is missing a required parameter, or a parameter is an incorrect type
    verification_failure The request failed signature verification, or the "iat" timestamp is outside the valid time window
    invalid_token The access_token is invalid, does not match the token provided in the HTTP Authorization header, has expired, or has been revoked by the customer
    unknown_transaction_id The transaction could not be found by the merchant_transaction_id or the processor_transaction_id (if supplied)
    insufficient_funds The customer does not have enough funds in their account to complete this payment in full. The Processing Service does not have to treat this as an error if the customer is allowed to allocate funds to this payment request in the Processing Service’s system after the initiate payment request
    payment_cancelled The payment was cancelled via a cancel payment request or timeout
    payment_limit_exceeded The transaction could not be performed due to payment limit
    payment_count_exceeded The transaction could not be performed due to payment quantity limit
    invalid_operation The operation could not be performed
    invalid_amount The amount of a payment is incorrect
    account_blocked Card is blocked
    account_expired Card is expired
    invalid_account Wrong card number
    other This code can be used for any other failure which does not match the above reasons. However, using this error code is much less useful than using one of the known error types above and should be avoided

    Appendix A

    Example RSA private key (used for signing the example messages in this document):

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

    MIICXQIBAAKBgQDjRMykIdoMaRZjza7IGEh+PXKiSuiGFn0CQBNVdLMvkP6ZHSQY CtUmOA+dBegJyPzm8omXxi2cJyVVyNNRubXHdBHn6BxrKGVgZGNnYWyW5/HgUN1A bNimIjF3sHsIfqiJQ6zPOovOxqSkWikgR9IKzc+8NoZseaDeGcW9J6yMmwIDAQAB AoGBAIs1JiBXN+eoKvXBFBEuhqEE5IWyWpFfjvzk4LLUg7lcGAcTiXtMj1kUt8OX zZTIzthrsYoM8v0WIVFVbNM/bK7yzvKVPBMhkmeK0s40OttE7HCQTG6kWamLRfAf 8aDcfVV3Tvapkge6jy6P5UfGJRKYyAE4zZkohZScqXK75xxJAkEA9A6cjyvFBNOr aN44p2SGCVYCAnBi4CjE0JqANJ929DmUGZxltAdzS6a4tpbyFB6AaoRZ78ytIuGE csxWsUTHZQJBAO5j3+JQQpFMWqrIXBtL06zjPsuKIx0LuawMGCEkwSiX2TwFAoyk HsqN7f3cRd1zXlKEwnIZGyAKA30DCJ6ow/8CQAIkKq165dSgAs39vSOC10Y3sfbR g5yR3wAxitRrXcDQzILZA29r7VAJm29GrcMNbXUBykQ3WIGI1v+m2U/e2Z0CQQDf Nf0HtwbdbZTnnDtCA7nrg8vkYS+Hntb3VUuynOuPyr7JCBffAD0kg8h3jqyMMd37 fftjQka3tSiXASQtCvCZAkAg5McNGVrLA/O2Z8lMs9mgoJmTLnMSvZkv2NMbGtrz TsB8kQcvvovUul5AWD0QlhCRkjGep2jd1zKrCSrNngFB

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

    Example RSA public key (can be used for verifying the signature of the example messages 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 cases that should be passing before acceptance:

    1. Test an echo request using an incorrect client cert. Verify that the connection fails during SSL negotiation.
    2. Test an echo using an incorrect signing key. Verify a failure HTTP code in the response.
    3. Test an echo using an invalid iat.
    4. Test an access token request with an invalid code. Verify an error response.
    5. Test an access token request with an invalid client_id. Verify an error response.
    6. Test an initiate payment request with an access_token that doesn’t match the one used in the Authorization header. Verify an error response.
    7. Test an initiate payment with a specific merchant_transaction_id. Make another initiate payment request with the same merchant_transaction_id and verify that the processor_transaction_id returned is the same as from the first call.
    8. Test an initiate payment request with a negative amount. Verify an error response.
    9. Test a complete payment request with no processor_transaction_id. Verify that the request succeeds.
    10. Test a complete payment request with a merchant_transaction_id and processor_transaction_id that refer to different transactions. Verify an error response.
    11. Test a cancel payment request for a transaction that doesn’t exist. Verify an error response.
    12. Test a cancel payment request for a transaction that has completed successfully. Verify that the transaction has been refunded.
    13. Test a cancel payment request for a transaction that has not completed yet. Verify that the transaction is now "failure" with a cancelled error code.