EN / ru

Paymaster Direct API

 

General

Authorization

Authorization Request

Access Token Request

Initiate Payment Request

Complete Payment Request

Appendix A

Appendix B

 

General

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

This is defined by the OAuth protocol. Authorization request should be sent to http://psp.wmtransfer.com/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:

 

Request Parameters:

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:

 

 

Response 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.

 

Example redirect:

HTTP/1.1 302 Found

Location: https://www.example.com/?code=Pbl8KuP8vg

Access Token Request

This is defined by the OAuth protocol. Access token request should be sent to http://psp.wmtransfer.com/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

 

Response Parameters:

Parameter

Datatype

Required

Description

access_token

String

Only on success

The permanent authorization token used for subsequent requests

token_type

String

Only on success

Constant. Should always be set to "bearer".

expires_in

Number

Only on success

The number of seconds from the issue time until this token expires

account_identifier

String

Only on success

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

Only on failure

Reason that the access token request failed. Valid values are: "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", and "invalid_scope" .

 

Example Request:

Unencoded Header:

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

 

Unencoded Payload:

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

 

HTTP message:

POST /... HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

 

request=eyJpYXQiOjEzNDc0NDc5ODgsImFsZyI6IlJTMjU2In0.eyJjbGllbnRfaWQiOiI1NGJmNGQ0Mi1iODVjLTQ4ZTItOGJkYS1hZDBjZjg3NmY0MTQiLCJjb2RlIjoiUGJsOEt1UDh2ZyIsImdyYW50X3R5cGUiOiJhdXRob3JpemF0aW9uX2NvZGUifQ.XXriIAXu7WCONVbJlWa-CW_gAbaMgNUL7NSI2BwSeeCtE47lkORGH7v-iILGF7Kw_TuK-8_2UGc5I5OAwHrt4oVUFNluip9fmS0nw2dDZYpNr1xYp4uFDbWXqWeW2LZKh7pDSh-0MQseJ-4lqqR0ilWGR7w9LOUvZuufSstCBbU

Example Response:

HTTP/1.1 200 OK

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

Initiate Payment Request

Initiate payment request should be sent to http://psp.wmtransfer.com/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.

 

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.

 

Response Parameters:

Parameter

Datatype

Required

Description

status

String

Yes

The result of this request. Valid values are "success" and "failure"

processor_transaction_id

String

Only on success

The ID of this transaction in the payment Processing Service’s system

error_code

String

Only on failure

The reason for the error response. See error codes below.

error

String

Only on failure

 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.

 

Error Codes:

Code

Datatype

Description

invalid_request

String

The request is missing a required parameter, or a parameter is an incorrect type

verification_failure

String

The request failed signature verification, or the "iat" timestamp is outside the valid time window

invalid_token

String

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

insufficient_funds

String

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.

other

String

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.

 

 

Example Request:

Unencoded Header:

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

 

Unencoded Payload:

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

 

HTTP message:

POST /... HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

 

request=eyJpYXQiOjEzNDc0NDgyMzQsImFsZyI6IlJTMjU2In0.eyJhY2Nlc3NfdG9rZW4iOiJ0aE4yNTBNUTVzY0ZsYWEtMUtjNjFQUDhncEF1c3VIZ3BKS29mbEF6RjVnIiwibWVyY2hhbnRfaWQiOiI1NGJmNGQ0Mi1iODVjLTQ4ZTItOGJkYS1hZDBjZjg3NmY0MTQifQ.CC1d1e2m8BkeVucVSn6I8oRulwQkTP2LxKyFt2jCMO3CIN1b9u3jpmLmONTNxF4N6NoPXtv6m1tU9ClLVaIj5PfqVLXEQx19lzh6Y-kYcHTKGAb7wmzPv03qLTFWRVXrMxYDCrHD5mT26iwaadhqkO18K4tnRvfyGpijCNrwtfc

 

Example Response:

HTTP/1.1 200 OK

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

Complete Payment Request

Complete payment request should be sent to http://psp.wmtransfer.com/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.

 

Response Parameters:

Parameter

Datatype

Required

Description

status

String

Yes

The result of this request. Valid values are "complete", "in_progress", and "failure".

error_code

String

Only on failure

The reason for the error response. See error codes.

error

String

Only on failure

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.

 

Error Codes:

Code

Datatype

Description

invalid_request

String

The request is missing a required parameter, or a parameter is an incorrect type

verification_failure

String

The request failed signature verification, or the "iat" timestamp is outside the valid time window

invalid_token

String

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

String

The transaction could not be found by the merchant_transaction_id or the processor_transaction_id (if supplied)

insufficient_funds

String

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

String

The payment was cancelled via a cancel payment request or timeout.

other

String

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.

 

 

 

Example Request:

Unencoded Header:

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

 

Unencoded Payload:

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

 

HTTP message:

POST /... HTTP/1.1

Host: example.com

Content-Type: application/x-www-form-urlencoded; charset=UTF-8

 

request=eyJpYXQiOjEzNDc0NDg0OTksImFsZyI6IlJTMjU2In0.eyJhY2Nlc3NfdG9rZW4iOiJ0aE4yNTBNUTVzY0ZsYWEtMUtjNjFQUDhncEF1c3VIZ3BKS29mbEF6RjVnIiwibWVyY2hhbnRfaWQiOiI1NGJmNGQ0Mi1iODVjLTQ4ZTItOGJkYS1hZDBjZjg3NmY0MTQifQ.RQS-CB3CQETzelafx3CKh-k8A6r0FT-J681Mxl2dY_fzyo7-WWwXxYGKy3ZOqi6bim4CCU8stJmpcFTb_GwcYzy6Fy7EZGYn92ct2QJBpVR58zCEyDxUj4GWrke44pC8OPKp3Ww_jAkj16SRrkV3mhxKLxbrzM5PYk2UN-F1e98

 

Example Response:

HTTP/1.1 200 OK

         {"status":"complete"}

 

 

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-----MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDjRMykIdoMaRZjza7IGEh+PXKiSuiGFn0CQBNVdLMvkP6ZHSQYCtUmOA+dBegJyPzm8omXxi2cJyVVyNNRubXHdBHn6BxrKGVgZGNnYWyW5/HgUN1AbNimIjF3sHsIfqiJQ6zPOovOxqSkWikgR9IKzc+8NoZseaDeGcW9J6yMmwIDAQAB

-----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.