Метод аутентификации запросов OAuth

OAuth HMAC-SHA1

Для формирования запроса с аутентификацией OAuth HMAC-SHA1 необходимо:

Сформировать подпись,
Сформировать заголовки,
Сформировать запрос.

Формирование подписи OAuth HMAC-SHA1

Для подготовки подписи необходимо выполнить следующие действия:

Собрать все параметры тела запроса и все параметры OAuth, включенные в тело запроса (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version):

Значение oauth_consumer_key - логин торговца, предоставленный Платежным Шлюзом, например merchantlogin.

Значение oauth_nonce - однократно используемая, сгенерированная случайным образом строка nonce, например y3qlvMPky7g.

Значение oauth_signature_method - HMAC-SHA1.

Значение oauth_timestamp - текущая временная метка в секундах, например 1669966913.

Значение oauth_version - 1.0.

Параметр oauth_signature в тело запроса не включен, он включен только в заголовок OAuth.
Применить процентное кодирование (percent-encode) к значениям каждого собранного на 1 этапе параметра. Справочная информация содержится в RFC 3986. Незарезервированные символы могут быть закодированы, но не должны кодироваться. Зарезервированные символы должны быть закодированы, например: % кодируется в %25, / кодируется в %2F, = кодируется в %3D.
Сортировать все собранные на этапе 1 параметры в лексикографическом порядке по названиям параметров.
Соединить с помощью конкатенации отсортированные параметры и их значения с помощью символов & и =:

object1=valueOfObject1&object2=valueOfObject2...

Пример строки соединенных параметров:
```
client-order-id=1234567890&oauth_consumer_key=merchantlogin&oauth_nonce=y3qlvMPky7g&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1669966913&oauth_version=1.0&sending-card-ref-id=7654321
```

Percent-encode each element (POST, URL, concatenated parameters) and construct Signature Base String with POST&URL&parameters structure (as documented in OAuth A.5.1.). | Signature Base String Example:

POST&https%3A%2F%2Fgate.payneteasy.com%2Fpaynet%2Fapi%2Fv2%2Fpan-eligibility%2Fsend%2FENDPOINTID&client-order-id%3D1234567890%26oauth_consumer_key%3Dmerchantlogin%26oauth_nonce%3Dy3qlvMPky7g%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1669966913%26oauth_version%3D1.0%26sending-card-ref-id%3D7654321

Sign the Signature Base String with HMAC-SHA1. The signing key is the concatenation of consumer secret (Merchant control key) + & + token secret (empty string).

Пример ключа HMAC-SHA1:
```
11111111-1111-1111-1111-111111111111&
```

Encode the signed string to Base64 to get signature for API.

Пример формирования подписи HMAC-SHA1 на Java:

package com.Payneteasy;

import org.apache.commons.codec.binary.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

public class HMAC_SHA1 {
   private static final String HMAC_SHA1_ALGORITHM = "HmacSHA1";

   public static String calculateHMAC(String data, String key) throws NoSuchAlgorithmException, InvalidKeyException {
      SecretKeySpec signingKey = new SecretKeySpec(key.getBytes(), HMAC_SHA1_ALGORITHM);
      Mac mac = Mac.getInstance(HMAC_SHA1_ALGORITHM);
      mac.init(signingKey);
      return Base64.encodeBase64String(mac.doFinal(data.getBytes()));
   }
}

Пример подписи:

d/IPlITUmPcniwjA7Vckjr6WQeE=

Формирование заголовков OAuth HMAC-SHA1

Запрос с аутентификацией OAuth HMAC-SHA1 должен иметь следующие заголовки:

content-type=application/x-www-form-urlencoded
Authorization: OAuth

Заголовок Authorization: OAuth должен содержать те же параметры и значения OAuth, которые добавлены в тело запроса и строку для подписи (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version). Также необходимо добавить подпись в качестве значения параметра oauth_signature в заголовок. Все значения параметров в заголовке Authorization: OAuth должны передаваться в кавычках (в соответствии с OAuth 5.4.1.) со структурой parameter=”value”, быть разделены обязательными запятыми (,) и необязательными пробелами. Параметр OAuth realm не является обязательным.

Пример заголовка Authorization (разделен построчно для удобства отображения):

Authorization: OAuth
oauth_consumer_key="merchantlogin",
oauth_nonce="y3qlvMPky7g",
oauth_signature="d/IPlITUmPcniwjA7Vckjr6WQeE=",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp="1669966913",
oauth_version="1.0"

Формирование запроса OAuth HMAC-SHA1

Необходимо использовать заголовки из предыдущей секции,
Включить параметры в тело запроса,
Применить процентное кодирование и отправить запрос.

Example of Request:

Request method:      POST
Request URI: https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/send/1111
Headers: Authorization=OAuth realm="",oauth_version="1.0",oauth_consumer_key="merchantlogin",oauth_timestamp="1669966913",oauth_nonce="y3qlvMPky7g",oauth_signature_method="HMAC-SHA1",oauth_signature="d%2FIPlITUmPcniwjA7Vckjr6WQeE%3D"
         Accept=*/*
         Content-Type=application/x-www-form-urlencoded; charset=ISO-8859-1
Body: client-order-id=1234567890&oauth_consumer_key=merchantlogin&oauth_nonce=y3qlvMPky7g&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1669966913&oauth_version=1.0&sending-card-ref-id=7654321

Example of CURL Request:

curl -H '
   Authorization: oauth_version="1.0",
   oauth_consumer_key="merchantlogin",
   oauth_timestamp="1669966913",
   oauth_nonce="y3qlvMPky7g",
   oauth_signature_method="HMAC-SHA1",
   oauth_signature="d%2FIPlITUmPcniwjA7Vckjr6WQeE%3D"
' --data '
   client-order-id=1234567890
   &oauth_consumer_key=merchantlogin
   &oauth_nonce=y3qlvMPky7g
   &oauth_signature_method=HMAC-SHA1
   &oauth_timestamp=1669966913
   &oauth_version=1.0
   &sending-card-ref-id=7654321
' 'https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/send/ENDPOINTID'

OAuth RSA-SHA256

Для формирования запроса с аутентификацией OAuth RSA-SHA256 необходимо:

Сгенерировать пару из публичного и приватного ключаr,
Сформировать подпись,
Сформировать заголовки,
Сформировать запрос.

Генерация ключей

Для отправки запросов с аутентификацией RSA-SHA256, необходимо сгенерировать пару из публичного и приватного ключа:

ПРИВАТНЫЙ ключ для подписания запросов. Этот ключ должен быть защищён от несанкционированного доступа.
ПУБЛИЧНЫЙ ключ для проверки, что запрос был подписан соответствующим приватным ключом. Этот ключ необходимо передать службе поддержки.

Для генерации ключей необходимо скачать последнюю версию утилиты openssl и запустить следующие команды:

openssl genpkey -algorithm RSA -out private_key_pkcs_8.pem -pkeyopt rsa_keygen_bits:4096
openssl rsa -pubout -in private_key_pkcs_8.pem -out public_key.pem

Необходимо использовать разные пары ключей для тестовой и производственной среды во избежание их компрометации.

Для использования инструментов формирования запросов и отладки в документации необходимо использовать ключ в контейнере PKCS#1 (незашифрованный приватный ключ RSA в текстовом формате PKCS#1 PEM). Такой ключ можно получить с помощью следующей команды:

openssl rsa -in private_key_pkcs_8.pem -out private_key_pkcs_1.pem

Для версий OpenSSL v3+ (проверено на v3.0.5) необходима другая команда:

openssl rsa -traditional -in private_key_pkcs_8.pem -out private_key_pkcs_1.pem

Получившийся приватный ключ PKCS#1 RSA будет начинаться со строки —–BEGIN RSA PRIVATE KEY—–. Для производственной среды подходит любой формат ключа, поддерживаемый программным комплексом Присоединяющейся стороны. Для инструментов формирования запросов и отладки в документации подходят только ключи с длиной до 4096. Пример приватного ключа PKCS#1 RSA:

Формирование подписи OAuth RSA-SHA256

Для подготовки подписи необходимо выполнить следующие действия:

Собрать все параметры тела запроса и все параметры OAuth, включенные в тело запроса (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version):

Значение oauth_consumer_key - логин торговца, предоставленный Платежным Шлюзом, например merchantlogin.

Значение oauth_nonce - однократно используемая, сгенерированная случайным образом строка nonce, например y3qlvMPky7g.

Значение oauth_signature_method - RSA-SHA256.

Значение oauth_timestamp - текущая временная метка в секундах, например 1669966913.

Значение oauth_version - 1.0.

Параметр oauth_signature в тело запроса не включен, он включен только в заголовок OAuth.
Применить процентное кодирование (percent-encode) к значениям каждого собранного на 1 этапе параметра. Справочная информация содержится в RFC 3986. Незарезервированные символы могут быть закодированы, но не должны кодироваться. Зарезервированные символы должны быть закодированы, например: % кодируется в %25, / кодируется в %2F, = кодируется в %3D.
Сортировать все собранные на этапе 1 параметры в лексикографическом порядке по названиям параметров.
Соединить с помощью конкатенации отсортированные параметры и их значения с помощью символов & и =:

object1=valueOfObject1&object2=valueOfObject2...

Percent-encode each element (POST, URL, concatenated parameters) and construct Signature Base String with POST&URL&parameters structure (as documented in OAuth A.5.1.). | Signature Base String Example:

POST&https%3A%2F%2Fgate.payneteasy.com%2Fpaynet%2Fapi%2Fv4%2Ftransfer%2FENDPOINTID&amount%3D10.42%26card_printed_name%3DJohn%2520Doe%26card_recurring_payment_id%3D42322%26client_orderid%3D1%26credit_card_number%3D4210708776705721%26currency%3DUSD%26cvv2%3D123%26deposit2card%3Dfalse%26destination-card-no%3D4232618181101636%26destination_card_recurring_payment_id%3D61622%26expire_month%3D12%26expire_year%3D2099%26ipaddress%3D1.1.1.1.1%26oauth_consumer_key%3Dpaydroid%26oauth_nonce%3DhoFlZri9c17X1Tvb7yD2fsMEQUIWBQ3m%26oauth_signature_method%3DRSA-SHA256%26oauth_timestamp%3D1669720957%26oauth_version%3D1.0%26order_desc%3DYour%2520order%2520description%26redirect_url%3Dhttp%253A%252F%252Fwww.example.com

Sign the Signature Base String with RSA-SHA256 using the private key obtained in previous section.

Base64 encode the signed string to get signature for API.

Пример подписи, закодированной в Base64:

K0hLc7GYh65UDTNvJvJbqoD95T7ekVEwIx+AxLBe2rNndPVzCAZMTi58J5pJlXZA1qOrgzUj/uL764NofP6qrqBXHX9Fpg+PdoMBey7zY9nMOmtdpHhkwyqA0n8e8oh68x+8RtC1+gmaIsIJDVurpCm2CdaViC2ny90GWPrrSin9CFwDmIKBtOJ7dxNnuFQJkvLxwK9JE9gRfQssG4vOrXrn2f5DvENFvFW3fL7meiN3mKuBFyEHIv2cibWopoUTQrxAgCfTHvRuU5nRIct9oWgCYLYzROOPyAIjtyDFKcTnUql9+tD2+p2rMDDU7HqJUGy764rb4ShuvuiuEvzIaNwg3JAxho9fqcKJz5LXt4efX1i8oFt33ztYSgZRojsoW4HCzuhZcQQmRexpmtCGYKqH3Q2BsG2jIkQAxL9BOUOzXNoeXoVQIf3+47cJ0KujEHuDXROblq3o9Uos5K+Mu9Carjs8jHMiBHo4aS4IAgXVY3mEuohCuRhL9/Y9buuyvdKSNsao7qHwD/6bb9Sj2MFFhYP6gHf+p1NipH05224aX9hMZty8Ovb3+ps/wNWYC8NVfft5bh8ETowaHQ5TUOPFdvU+5IkHOnnfbvz1/+jDeErd0Pdq4xH6c5/gZVQY9j6DFpazsw8d3karwXoBduv7I3mh7L3CSjTweABaRMw=

Формирование заголовков OAuth RSA-SHA256

Запрос с аутентификацией OAuth RSA-SHA256 должен иметь следующие заголовки:

content-type=application/x-www-form-urlencoded
Authorization: OAuth

Заголовок Authorization: OAuth должен содержать те же параметры и значения OAuth, которые добавлены в тело запроса и строку для подписи (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version). Также необходимо добавить подпись в качестве значения параметра oauth_signature в заголовок. Все значения параметров в заголовке Authorization: OAuth должны передаваться в кавычках (в соответствии с OAuth 5.4.1.) со структурой parameter=”value”, быть разделены обязательными запятыми (,) и необязательными пробелами. Параметр OAuth realm не является обязательным.

Пример заголовка Authorization (разделен построчно для удобства отображения):

Authorization: OAuth
oauth_consumer_key="paydroid",
oauth_nonce="hoFlZri9c17X1Tvb7yD2fsMEQUIWBQ3m",
oauth_signature="K0hLc7GYh65UDTNvJvJbqoD95T7ekVEwIx%2BAxLBe2rNndPVzCAZMTi58J5pJlXZA1qOrgzUj%2FuL764NofP6qrqBXHX9Fpg%2BPdoMBey7zY9nMOmtdpHhkwyqA0n8e8oh68x%2B8RtC1%2BgmaIsIJDVurpCm2CdaViC2ny90GWPrrSin9CFwDmIKBtOJ7dxNnuFQJkvLxwK9JE9gRfQssG4vOrXrn2f5DvENFvFW3fL7meiN3mKuBFyEHIv2cibWopoUTQrxAgCfTHvRuU5nRIct9oWgCYLYzROOPyAIjtyDFKcTnUql9%2BtD2%2Bp2rMDDU7HqJUGy764rb4ShuvuiuEvzIaNwg3JAxho9fqcKJz5LXt4efX1i8oFt33ztYSgZRojsoW4HCzuhZcQQmRexpmtCGYKqH3Q2BsG2jIkQAxL9BOUOzXNoeXoVQIf3%2B47cJ0KujEHuDXROblq3o9Uos5K%2BMu9Carjs8jHMiBHo4aS4IAgXVY3mEuohCuRhL9%2FY9buuyvdKSNsao7qHwD%2F6bb9Sj2MFFhYP6gHf%2Bp1NipH05224aX9hMZty8Ovb3%2Bps%2FwNWYC8NVfft5bh8ETowaHQ5TUOPFdvU%2B5IkHOnnfbvz1%2F%2BjDeErd0Pdq4xH6c5%2FgZVQY9j6DFpazsw8d3karwXoBduv7I3mh7L3CSjTweABaRMw%3D",
oauth_signature_method="RSA-SHA256",
oauth_timestamp="1669720957",
oauth_version="1.0"

Формирование запроса OAuth RSA-SHA256

Чтобы сформировать запрос:

Необходимо использовать заголовки из предыдущей секции,
Включить параметры в тело запроса,
Применить процентное кодирование и отправить запрос.

Example of Request:

Request method: POST
Request URI: https://gate.payneteasy.com/paynet/api/v4/transfer/4473
Headers: Authorization= OAuth oauth_nonce="C12mCYiI4RDeVTvyZDHS3f0vUbBNrK9G", oauth_signature="S4ahUgep8EV3RTIPdcpO%2FzEwB8V1XwFcGi5zhrYKySPVVA2PAY7AxezPcOCMhMwZQfcf8VOH8O9v5zZ%2BmYV2Qsq4kjPe1zEJIjjdjhI%2B2MX9VW8dWn9DyoTD2lkOYUwGsCteXU6mwGtNergN5KwGTJgqYPfzWFLllSAhGwuOd%2FgHYVRnA6jd4FvywRaRiSsnzgsasGJjWCGzX%2F1B8L78H%2FqD1W7dNJHjC2JbonUiHVT4aOs74qpqYE9zcb5rK8PH1l2ems3ArXhqFaSF85%2BYzJ%2BkSeDswqeIZ1y3NS8XPrmaLeymLNqKpOfAl9Ng47AmIjSYEw3s5fQ7Xi9t4j7Y6fQA4RnIzIdmH4oeMiyzn7dpA87wqnXm5AIm6Den2TJaDg90UoCMXuGHkqfL8GGUSjaWleTOHlk%2FO4dBGDRw4LP1aEaJktQRmT5xwyoaQfz%2Bh2MR7zDpRbVZDpUto1iYlQl5UlgojOHaLLjW1gqggbvrtVXUBT73KcIboWW00VUcbVUX5Yb%2FSu7hUZO2fNAh4LYrsVcXRJxCZuwhXCiqvbR3EziEFDGVEZnKUDLCodzHbVA9hbpxHGa7TvSLFEANCPDFtapMF9eo%2F1yOt5Tkxag4g5yNes93lrVabsTqckiFIfKR2R3CcwJ6MQtMfo8ticJcKxfo2v%2BTkC0bEaRkBGk%3D", oauth_consumer_key="ny_qa_merchant", oauth_signature_method="RSA-SHA256", oauth_timestamp="1669892964", oauth_version="1.0"
         Accept=*/*
         Content-Type=application/x-www-form-urlencoded; charset=ISO-8859-1
Body: cvv2=123&ipaddress=1.1.1.1&amount=15.42&credit_card_number=4210708776705721&client_orderid=1&deposit2card=false&destination-card-no=4232618181101636&expire_month=12&order_desc=Your%20order%20description&card_printed_name=Vasia%20Pupkin&currency=RUB&expire_year=2099&redirect_url=http%3A%2F%2Fwww.example.com

Example of CURL Request:

curl -H '
   Authorization: OAuth oauth_consumer_key="paydroid",
   oauth_nonce="JOARJWjXJgfRUVqig8HIs0ouFWKfK4N5",
   oauth_signature="k5Z0XCVdDvb5h873XG6TDMO854PsuueSnSby4h0%2F3j4TKraY6ebjoFfDmndI09%2FQp6uEbCgKregNY5N0ccIVIay49l6v7jMdIFEfqU7E5eu%2BIJcoqG7kMFcdCu29hweYx7p4ZSk%2FUtdGlN3wyUUybCAx73XYoO0tkZteAleyzQlzdpzQ99vPS8FN2WMbNdzU3H2PLf0XOZy4DbAPleZGfu3GWxXe9erGsvzBJozs3WFxiPFeULfzWWsNc1h1P7cnzNbZqXkI%2BV3qiG3jc7tDqGRZP%2BLZFw3nihNlW%2F2Nlp%2FId6QG8kPNOEx2GxAuQa8kufv%2BbpohU8UftZG1SnNfoa4nDVgNbWoSbTXbgXxwHE0ZlccwT6q%2BHbTmgggvIdGN9JuuLUL8fDSCxqu3R7YMvcwArzrkd1XEFUFvYWxHc3QpfbBu0GyLkL7pnmz%2BFPTH48COZ7yXbK6nQDFSIy8lmaEJsnnjMYyMMVgjNkDNzqwNxOQuwprTZ7KzHqWrTj0zHTOHl44q1pJhIqMwxWDPMsziExYbAzxuOkdQFZi%2BK%2Bu3M7tvG5Foy7Vwj%2BDSPMPAhj7j2AmUG4HzaJcpiBWMq0CkGWRjvneOk3NiwkEwOxq5tJOFjsroditUqJQSX1PTqf%2FtuiqaE2Gt5EYl19ZzyXbxtMjGZwL%2BzF1cT6ftTi4%3D",
   oauth_signature_method="RSA-SHA256",
   oauth_timestamp="1669892687",
   oauth_version="1.0"
' --data '
   amount=10.42
   &card_printed_name=John%20Doe
   &card_recurring_payment_id=42322
   &client_orderid=1
   &credit_card_number=4210708776705721
   &currency=USD
   &cvv2=123
   &deposit2card=false
   &destination-card-no=4232618181101636
   &destination_card_recurring_payment_id=61622
   &expire_month=12
   &expire_year=2099
   &ipaddress=1.1.1.1.1
   &order_desc=Your%20order%20description
   &redirect_url=http%3A%2F%2Fwww.example.com
' 'https://gate.payneteasy.com/paynet/api/v4/transfer/ENDPOINTID'