Skip to main content

Формат взаимодействия с API Pear

Особенности​

API в качестве основного протокола использует HTTP, а значит подходит для разработки на любом языке программирования, который умеет работать с HTTP-библиотеками (cURL и другими).

API endpoint: https://api.paypear.ru/v1/

API поддерживает POST, GET и DELETE-запросы. POST-запросы используют JSON-аргументы, GET и DELETE-запросы работают со строками запросов. API всегда возвращает ответ в формате JSON, независимо от типа запроса.

Аутентификация​

Для аутентификации запросов необходимо использовать HTTP Basic Auth. В заголовках запросов в качестве имени пользователя необходимо передать ID магазина из личного кабинета, в качестве пароля — ваш секретный ключ.

Секретный ключ отвечает за безопасность ваших данных. Храните его в защищенном месте и не публикуйте на сторонних ресурсах (например, в открытом GitHub репозитории).


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

curl https://api.paypear.ru/v1 \
   -u <ID магазина>:<Секретный ключ>

Узнать идентификатор и выпустить секретный ключ (а также перевыпустить и удалить неактуальный) можно в личном кабинете. Если у вас нет доступа к личному кабинету, попросите владельца магазина добавить вас как пользователя с ролью Разработчик

Идемпотентность​

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

Для обеспечения идемпотентности используется заголовок Idempotence-Key (или ключ идемпотентности). В заголовке Idempotence-Key можно передавать любое значение, уникальное для этой операции на вашей стороне. Длина не больше 64 символов. Рекомендуется использовать V4 UUID.

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

curl https://api.paypear.ru/v1/refunds \
  -X POST \
  -u <ID магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_id": "02b150d3-6302-4358-9be5-b3606718791f"
      }'

Если вы повторяете запрос с теми же данными и тем же ключом, API обрабатывает его как повторный. Если данные в запросе те же, а ключ идемпотентности отличается, запрос выполняется как новый.

Ключ идемпотентности нужно передавать для POST и DELETE-запросов. GET-запросы являются по умолчанию идемпотентными, так как не имеют нежелательных последствий.

API обеспечивает идемпотентность в течение 24 часов после первого запроса, потом повторный запрос будет обработан как новый.


Обработка запросов​

API обрабатывает полученный запрос немедленно и возвращает результат обработки («успех» или «неудача»). Ответ содержит код ответа HTTP, стандартные заголовки и при необходимости тело ответа в формате JSON. Подробнее о формате ответа

Если в течение 30 секунд невозможно дать точный ответ, например из-за неполадок на стороне эквайера, API вернет код ответа HTTP 500, а для запросов, связанных с платежами, также попытается отменить операцию.

HTTP 500 не говорит об успешности или неуспешности выполнения вашей операции. Поэтому при получении HTTP 500 вам необходимо сначала узнать результат обработки запроса и только после этого принимать любые решения, связанные с этой операцией.