Общая информация по API

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

Хотя возвращаемые параметры API Odero различаются в зависимости от того, была ли операция успешной и возвращается ли одно или несколько значений результата, они имеют общую структуру.

Ошибочные операции

Это формат вывода, используемый при возникновении ошибки в системе или структуре. Он содержит ячейку под названием error, которая содержит информацию только об ошибках.

Параметр Тип Всегда доступен Описание
errors Error Да Содержит информацию о произошедшей ошибке. См. для подробной информации об ошибках: Коды ошибок оплаты

Удачные операции

Ответы, возникающие в результате удачных операций, состоят из разных параметров в зависимости от того, является ли результат операции одиночным или множественным.

Одиночный ответ

Это формат возврата, используемый для транзакций или запросов, которые дают единичные результаты, например получение платежа, возврат платежа, создание покупателя, просмотр сведений о мерчанте. Он состоит из поля под названием data, которое содержит только результат операции.

Параметр Тип Всегда доступе Описание
data any Нет Результат выполненной операции или запроса. Эта функция и ее содержимое подробно описаны на странице документации, связанной с транзакцией или запросом.

Множественный ответ

Это формат ответа, возвращаемый операциями или запросами, которые могут дать несколько результатов, например как поиск или перечисление.

Параметр Тип Всегда доступе Описание
items any[] Да Представляет результаты операции или запроса. Характер и содержание результатов подробно описаны на странице документации транзакции или запроса.
totalSize long Нет Он возвращается в результате операций с нумерацией страниц, таких как поиск и перечисление. Управляет общим количеством результатов, полученных по запросу. При возврате ошибочных операций нет этого поля.
size long Нет Он возвращается в результате операций с нумерацией страниц, таких как поиск и перечисление. Указывает количество результатов, возвращаемых на страницу запроса. При возврате ошибочных операций нет этого поля.

Безрезультатные операции

Пустой ответ может быть возвращен в результате неэффективных операций, таких как удаление сохраненной карты.Хотя такие операции происходят крайне редко, рекомендуется исходить из того, что на операции удаления не будет получен ответ. С другой стороны, не рекомендуется проверять, является ли код состояния только 200 OK при проверке успешности запроса, поскольку эти ответы могут быть возвращены с HTTP-кодом204 No Content, который также указывает на успешные операции.

Enums

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

Валюты

Значение Описание
TRY Турецкая Лира
AZN Азербайджанский манат

ПРИМЕЧАНИЕ. Вам необходимо использовать валюты в зависимости от страны операций. Например, если вы являетесь азербайджанским мерчантом, вам необходимо отправлять запросы как AZN, а если вы находитесь в Турции, вы будете использовать TRY.

Типы карт

Значение Описание
CREDIT_CARD Кредитная карта
DEBIT_CARD Дебитовая карта
PREPAID_CARD Prepaid карта

Ассоциации карт

Значение Описание
VISA Visa
MASTER_CARD Master Card
AMEX American Express
TROY Troy

Типы субмерчантов

Значение Описание
PRIVATE_COMPANY Частная компания
LIMITED_OR_JOINT_STOCK_COMPANY ООО или ОАО/ЗАО

Типы платежей

Значение Описание
CARD_PAYMENT Платеж был полностью снят с карты
DEPOSIT_PAYMENT Оплата пополнения карты
WALLET_PAYMENT Платеж был полностью выведен из кошелька
CARD_AND_WALLET_PAYMENT Платеж, часть которая снимается с карты, а часть с кошелька
BANK_TRANSFER Денежный перевод/EFT платеж

Группы платеж

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

Значение Описание
PRODUCT Продукт
LISTING_OR_SUBSCRIPTION Реклама, услуга или подписка
SUBSCRIPTION Подписки/Повторяющиеся платежи

Статусы платежа

Значение Описание
FAILURE Неудачный платеж
SUCCESS Удачный платеж
INIT_THREEDS 3D Secure запущен
CALLBACK_THREEDS 3D Secure на этапе callback

MD Статус

Это цифровые значения, отправляемые банком в Odero API после проверки платежей, совершенных с помощью 3D Secure. Хотя банки и платежные организации иногда возвращают уникальные значения статуса MD, значения в таблице ниже можно считать стандартными.

Значение Описание
0 Подпись или код подтверждения 3D Secure недействительны.
1 Удачный код подтверждения
2 Владелец карты или банк не зарегистрирован в системе
3 Банковская карта не зарегистрирована в системе
4 Ошибка подтверждения, владелец карты решил зарегистрироваться в системе позже.
5 Ошибка подтверждения
6 Ошибка 3D Secure
7 Ошибка системы

Типы возврата

Значение Описание
CARD На карту
WALLET В кошелек

Статусы перевода денег

Значение Описание
WAITING_FOR_APPROVAL Ожидается подтверждение перевода денег
APPROVED Денежный перевод подтвержден
PAYOUT_STARTED Начался денежный перевод

Алгоритм Signature

Любой прямой запрос к API Odero должен быть аутентифицирован с использованием ключей доступа мерчанта. Доступ к ключевой информации для мерчантов можно получить через Панель мерчанта.

Если вы используете продукты OderoPay, вам просто нужно передать информацию о ключе доступа в качестве параметра объекту Odero. Если вы не используете их, потребуются следующие операции.

Используя аккаунт мерчанта вы должны отправлять следующие headers в каждом запросе, отправляемом в API Gateway, для проверки учетных данных

Header Описание
x-api-key Ключ доступа к API
x-rnd-key Специально созданное случайное значение string
x-auth-version Номер версии алгоритма аутентификации. Если вы не уверены дать какое-то значение, то вы можете указать V1.
x-signature Вышеуказанные параметры, являются конфедициальным паролем для входа и signature созданная с использованием конкретной информации в соответствии с поданным запросом.
См. для подробной информации. [Алгоритм вычисления Signature](#signature-calculation-algorithm)

Алгоритм вычисления Signature

Signature, это проверочное значение, используемое для проверки того, что запрос поступил из правильного источника. Поскольку это зависит от запроса, его необходимо посчитать и отправить вместе с запросом. Чтобы вычислить значение Signature:

Signature специфична для каждого request-a!

  1. Объедините концы следующих значений друг с другом
    • URL-адрес запроса (hostname, protocol və query string включительно)
    • Ключ доступа мерчанта к API (API Key)
    • Секретный ключ входа мерчанта в аккаунт (Secret Key)
    • Случайный string, созданный по желанию
    • Если возможно body
  2. Вычислить объединенный string SHA-256 hash
  3. Вычислить зашифрованное состояние Hash-in Base64

Примеры



Параметры

Имя Значение
URL https://api-gateway.oderopay.com.tr/onboarding/v1/sub-merchants/1
Request Body
API Key key-1
Secret Key FooBar123!
Random Key Xa15Fp11T

Алгоритм Signature

  • Full URL: https://api-gateway.oderopay.com.tr/onboarding/v1/sub-merchants/1
  • Query String:
  • API Key: key-1
  • Secret Key: FooBar123!
  • Random Key: Xa15Fp11T
  • Request Body:
  • Concatenated String: https://api-gateway.oderopay.com.tr/onboarding/v1/sub-merchants/1key-1FooBar123!Xa15Fp11T
  • Signature: L/F2ZAOH/AGXZPIULNHDGOFZ+D5JS1097UP6RH11VSO=

Получившиеся Headers

Имя Название
x-api-key key-1
x-rnd-key rGciw1df
x-auth-version V1
x-signature L/F2ZAOH/AGXZPIULNHDGOFZ+D5JS1097UP6RH11VSO=





Параметры

Имя Значение
URL https://api-gateway.oderopay.com.tr/onboarding/v1/buyers
Request Body {"email":"haluk.demir@example.com","name":"Haluk","surname":"Demir","gsmNumber":"905551111111","identityNumber":"11111111110","buyerExternalId":"0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
API Key key-1
Secret Key FooBar123!
Random Key Xa15Fp11T

Алгоритм Signature

  • Full URL: https://api-gateway.oderopay.com.tr/onboarding/v1/buyers
  • Query String:
  • API Key: key-1
  • Secret Key: FooBar123!
  • Random Key: Xa15Fp11T
  • Request Body: {"email":"haluk.demir@example.com","name":"Haluk","surname":"Demir","gsmNumber":"905551111111","identityNumber":"11111111110","buyerExternalId":"0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Concatenated String: https://api-gateway.oderopay.com.tr/onboarding/v1/buyerskey-1FooBar123!Xa15Fp11T{"email":"haluk.demir@example.com","name":"Haluk","surname":"Demir","gsmNumber":"905551111111","identityNumber":"11111111110","buyerExternalId":"0ac49f08-f2a9-4326-a4d8-f6c1b01596fb"}
  • Signature: IRWQTISFBKCSM/NGZZ9XGN9PCTBXC0YSUJIBZMUZ9VS=
Получившиеся Headers
Имя Значение
x-api-key key-1
x-rnd-key Xa15Fp11T
x-auth-version V1
x-signature IRWQTISFBKCSM/NGZZ9XGN9PCTBXC0YSUJIBZMUZ9VS=