Автоматический интерфейс Paymaster Direct

Общие сведения

Схема взаимодействия:

Техническая информация

Типы подписи:

Payloads(данные):

JWS:

Rest:

Авторизация

Запрос авторизации

Запрос на получение токена доступа

Запрос инициации платежа

Запрос проведения платежа

Запрос отзыва токена доступа

Приложение А

Приложение B

Общие сведения

Протокол Paymaster Direct предназначен для Компаний (Продавцов), чей бизнес предусматривает списания средств с плательщика без дополнительного подтверждения им каждой транзакции (безакцептные платежи, Direct Debit). Примерами может служить подписка на новостной контент, продление доменных или хостинговых услуг, покупка в один клик в играх и других средах, где нежелателен выход из процесса, мобильные приложения и так далее.

Разумеется, получение Продавцом возможности безакцептного списания невозможно без разрешения плательщика в выбранной им платежной системе. Это разрешение (долгосрочный акцепт, долгосрочное поручение) представляет собой данное им право потратить заданную сумму в заданный промежуток времени без прохождения платежных авторизационных процедур (разовых акцептов). После получения разрешения и до тех пор, пока оно будет действительным, списание производится на уровне межсерверного взаимодействия (без участия плательщика).

Продавец должен инициировать получение специальных разрешений на это у той платежной системы, которую хочет использовать его клиент-плательщик. Он передает плательщика на сайт Paymaster; тот, взаимодействуя с выбранной платежной системой, организует получение разрешений (акцепта) и сообщает Продавцу статус этой операции. После успешного завершения операции Продавец получает доступ к безакцептному списанию средств с плательщика.

Схема взаимодействия:

Техническая информация

Кодирование: Вся текстовая информация будет передаваться в кодировке UTF-8.

Передача данных: Все запросы будут отправляться через защищенные протоколы HTTPS с использованием ключа проверки клиента.

Продавец может использовать любой из 2 протоколов взаимодействия:

1. JWS
2. Rest

Тип протокола необходимо передавать в каждом запросе в http-заголовке "type" (или в get, или в post параметре). Если значение отсутствует, то по умолчанию считается, что используется JWS. Если в http-заголовке "resp-type" (или в get, или в post параметре) передавать значение "xml", то ответ будет в формате XML. Если значение отсутствует, то ответ будет в формате JWS.  В каждом типе протокола определяется значение "Подписываемого тела" запроса и способ передачи подписи.

Типы подписи:

Продавец может использовать 2 типа подписи запросов: RSA и Hash.

1. RSA - подпись "подписываемого тела" запроса в кодировке UTF8 RSA ключами с использованием хеша Sha-1 или Sha-256.
2. Hash - подпись строки вида "подписываемое тело;секретный ключ" (разделитель ";") в кодировке UTF8 с использованием хеша Sha-256.

        Cекретный ключ назначается продавцом в личном кабинете ("Настройки подписи Direct").  

Payloads(данные): 

Заголовок всех запросов всегда должен содержать обязательное поле "iat" (означающее "инициирован в") , содержащее целочисленное значение в секундах (1970-01-01T0:0:0Z в стандарте UTC). При каждом запросе данное поле должно содержать фактическое время отправки запроса.  

Поле "iat" может быть использовано PayMaster для предотвращения угроз повторного воспроизведения платежа с помощью сравнения времени занесенного в это поле и заданного временного интервала с фактическим.

JWS:

 Содержание запросов будет иметь вид сообщений в формате  JSON Web Signature (JWS).

Подписываемое тело запроса:

"HeaderEncoded.BodyEncoded" (разделитель "." - точка) - все параметры, кроме sign. HeaderEncoded - закодированный UrlSafeBase64Encoding заголовок сообщения, BodyEncoded - закодированное UrlSafeBase64Encoding тело запроса. Подпись идет через точку(.) после Body ("HeaderEncoded.BodyEncoded.SignEncoded") и кодируется UrlSafeBase64Encoding.

Заголовок должен содержать стандартное поле "alg", которое всегда должно приводиться к "RS256" ("alg":"RS256"). Для удобства выполнения данной спецификации PayMaster’ом данные запроса передаются по протоколу HTTPS в параметре "request".

Rest:

Подписываемое тело запроса:

В случае Get запроса - это "QueryString;iat", где:

QueryString - это строка параметров после знака вопроса в Url;

iat -  это поле "инициирован в";

В случае Post запроса - это "Body;iat;секретный ключ", где:

Body - это тело запроса;

iat -  это поле "инициирован в";

секретный ключ - назначается продавцом в личном кабинете ("Настройки подписи Direct").  

Запросы формируются и отправляются Get или Post (application/x-www-form-urlencoded) параметрами. Подпись передается в заголовке "sign" или в параметрах запроса и кодируется Base64Encoding.

Замечание для разработчиков на PHP: если $str - строка параметров, то хеш считается как

base64_encode(hash('sha256', $string, true)).

URLs: для всех типов запросов перечисленных ниже PayMaster присваивает уникальный URL и передает Продавцу. URL’ы для разных типов запросов не обязательно должны находиться на одном и том же хосте.

Авторизация

Авторизация проходит с использованием протокола OAuth 2.0 Authorization.

Авторизация выглядит следующим образом:

1.        Продавец перенаправляет пользователя на сайт Paymaster Direct. Пользователю будет предложено авторизоваться, если он еще не авторизован или не выдал Продавцу разрешение на использование его Веб-кошелька.

2.        После прохождения авторизации пользователь перенаправляется на redirect_uri, указанную продавцом при перенаправлении пользователя, с добавлением временного токена.

3.        Продавец генерирует токен-запрос в PayMaster, содержащий временный токен для получения постоянного токена.

Запрос авторизации

Запрос авторизации определяется протоколом OAuth. Запрос авторизации следует отправлять на https://paymaster.ru/direct/security/auth. Этот URL будет использоваться Продавцом для авторизации в учетной записи клиента в платежной системе. Запрос должен содержать следующие обязательные параметры (используется метод POST):

Параметры запроса:

Реакцией на успешное завершение процесса авторизации должно быть перенаправление пользователя на предоставленный redirect_uri. URL должен иметь следующие параметры:

Параметры ответа:

Если пользователь запрещает доступ к своей учетной записи или возникает ошибка, пользователь не должен быть перенаправлен на redirect_uri.

Пример перенаправления:

HTTP/1.1 302 Found

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

Запрос на получение токена доступа

Запрос определяется протоколом OAuth. Запрос следует отправлять на https://paymaster.ru/direct/security/token. Запрос передается Продавцом в PayMaster для обмена временного токена из исходного запроса на постоянный токен, который будет использоваться для будущих платежей.

HTTP Метод POST

Параметры запроса:

Параметры ответа:

Пример запроса:

Незакодированный заголовок:

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

Незакодированные данные запроса:

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

HTTP сообщение:

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

Пример ответа:

HTTP/1.1 200 OK

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

Запрос инициации платежа

Запрос инициации платежа следует отправлять на https://paymaster.ru/direct/payment/init. Этот запрос передается Продавцом в PayMaster для инициации платежа. Успешно выполненный запрос не гарантирует перевод средств Продавцу, он только указывает на то, что пользователь находится в платежной системе и готов оплатить всю сумму в полном объеме в момент отправки запроса. Если запрос, по какой- либо причине, не удался, то сообщение об ошибке отобразиться пользователю и данный платеж повторить будет невозможно.

HTTP Метод POST

Параметры запроса:

Параметры ответа:

Коды ошибок:

Пример запроса:

Незакодированный заголовок:

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

Незакодированный данные запроса:

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

HTTP сообщение:

POST /... HTTP/1.1

Host: example.com

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

request=eyJpYXQiOjEzNDc0NDgyMzQsImFsZyI6IlJTMjU2In0.eyJhY2Nlc3NfdG9rZW4iOiJ0aE4yNTBNUTVzY0ZsYWEtMUtjNjFQUDhncEF1c3VIZ3BKS29mbEF6RjVnIiwibWVyY2hhbnRfaWQiOiI1NGJmNGQ0Mi1iODVjLTQ4ZTItOGJkYS1hZDBjZjg3NmY0MTQifQ.CC1d1e2m8BkeVucVSn6I8oRulwQkTP2LxKyFt2jCMO3CIN1b9u3jpmLmONTNxF4N6NoPXtv6m1tU9ClLVaIj5PfqVLXEQx19lzh6Y-kYcHTKGAb7wmzPv03qLTFWRVXrMxYDCrHD5mT26iwaadhqkO18K4tnRvfyGpijCNrwtfc

Пример ответа:

HTTP/1.1 200 OK

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

Запрос проведения платежа

Запрос проведения платежа необходимо отправлять на https://paymaster.ru/direct/payment/complete. Запрос необходим для завершения платежа, который был инициирован запросом инициации платежа. Если запрос выполнен успешно, считается, что средства передаются от клиента Продавцу. Если запрос по какой-либо причине не выполнен и не помечен как повторный, то пользователь будет оповещен о незавершенном платеже и повторить данный платеж будет невозможно. Если запрос будет возвращен со статусом "in_progress" без кода возврата 200 или таймаута платежа, то запрос необходимо повторить позже (Рекомендуемое время повторной отправки запроса 15 секунд). Продавец должен быть в состоянии обработать этот запрос, используя только параметр merchant_transaction_id для идентификации данной транзакции.

Параметр processor_transaction_id используется только для удобства исполнителя. Запрос на проведение платежа, достигший конечного состояния (проведен или отказ), должен вернуть последний результат запроса на проведение платежа. Запросы, не достигшие состояния "проведен" или "отказ" в течение 120 часов с начала запуска платежа считаются отмененными и переходят в состояние "отказ".  

HTTP метод POST

Параметры запроса:

Параметры ответа:

Коды ошибок:

Пример запроса:

Незакодированный заголовок:

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

Незакодированные данные запроса:

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

HTTP сообщения:

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

Пример ответа:

HTTP/1.1 200 OK

{"status":"complete"}

Запрос отзыва токена доступа

 Запрос отзыва токена доступа необходимо отправлять на https://paymaster.ru/direct/Security/Revoke. Запрос передается Продавцом по запросу покупателя в PayMaster для отмены существующего доверия. После выполнения запроса токен доступа будет аннулирован.

HTTP Метод POST

Параметры запроса:

Параметры ответа:

Пример запроса:

Незакодированный заголовок:

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

Незакодированные данные запроса:

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

HTTP сообщения:

POST /... HTTP/1.1

Host: example.com

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

request=eyJpYXQiOjEzODQ5NDkzMjAsImFsZyI6IlJTMjU2In0.eyJjbGllbnRfaWQiOiIxIiwiYWNjZXNzX3Rva2VuIjoiN0otWUJPXzdjSTlBNWxiMVUyUGdMd29EeVp4blRKaGtNMm81WFdJcGpqRSJ9.Jx-HpyoTaE67_cp9SImKa5Q2z4IHcQoQB8DyoDC6rgzAtyA09FlYHHehRk-7357C4LHTKoE-HLz4jl6_pOPRymH1CdInHfdnkjoXUSaAlB-Ga7R6hUs1CsN4av_Hj5P-N416qW-mONxX8G-lP2KzELu_Ri2_YpQbqsKwU4t6kWY

Пример ответа:

HTTP/1.1 200 OK

{"status":"success"}

Приложение А

Пример RSA- секретного ключа (используется, например,  для подписания сообщения в этом документе):

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

Пример RSA-открытого ключа (может быть использована для проверки подписи сообщения в этом документе):

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

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxw6Wp7mDULZksgyOfvDJ

YTpbwdQeDXWTG0mq6Z6geDT2naYm6q3bL17oy2IbBhXqrh6CzufPoppb3H8v+2md

R484fO955HwCWekVqaWUw5MzYpaqKbBqBepENi9lxaOGEg4Tuy48ARsmZc7KBubn

EohA6BjDyx8AdwCLeKYNKhKSwzrlEKteCwWvqpXwszOck2zqK1VzDKZT8+G7g7aZ

H496sw16iBtId0QcI5sV/IAq58VjQqCsKj7khweiPaxtWpsawnmylazm0O8/8Mj5

d+GSLmO3hhT2ZoPpeSdvruC2RPLAYliWAl+NouqrAp2Di4yYFwKAX2nwvuZVFk5T

iQIDAQAB

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

Приложение B

Тестовые действия перед принятием окончательных настроек:

1. Протестируйте запрос с использованием токена с некорректным кодом. Проверьте сообщение об ошибке в ответе.
2. Протестируйте запрос с использованием токена с некорректым client_id. Проверьте сообщение об ошибке в ответе.        
3. Протестируйте запрос инициации платежа с токеном доступа не соответствующим тому, который использован на странице авторизации.
4. Протестируйте запрос инициации платежа с использованием конкретного параметра merchant_transaction_id. Сделать еще один запрос, использую то же значение параметра merchant_transaction_id и убедиться, что processor_transaction_id содержит тоже значение, что и при первом запросе.
5. Протестируйте запрос инициации платежа с отрицательным значением суммы. Получите сообщение об ошибке.
6. Протестируйте запрос проведения платежа без параметра processor_transaction_id. Убедитесь в том, что запрос прошел успешно.
7. Протестируйте запрос проведения платежа с параметрами merchant_transaction_id  и processor_transaction_id, относящимися к разным операциям. Получите сообщение об ошибке.