FORMAT: 1A HOST: https://polls.apiblueprint.org/

Geller API

Основные принципы взаимодействия с сервисом Geller

Взаимодействие по API осуществляется с помощью POST запросов в кодировке UTF-8 на URL: https://{Host}/<метод API> Сервис принимает json запросы, при отправке указывать заголовок "Content-Type: application/json". Все запросы к Geller подписываются секретным ключом партнера (выдается при подключении менеджером). Для каждого метода свой набор обязательных параметров, также могут передаваться дополнительные параметры, но в формировании подписи они не участвуют.

Все ответы сервиса Geller содержат параметры: result, message, data Если result равен “ok”, то поле data содержит определенные для каждого запроса параметры. Если result равен “error”, запрос был обработан с ошибкой, значение data - null, поле message содержит описание ошибки.

2. Ответ на API запрос

Приложение сервиса Geller в случае отправки корректного запроса должно вернуть тип ответа, в контексте HTTP статуса ответа: 200 - запрос обработан успешно; все возникшие ошибки обработаны корректно; В случае, если приложение сервиса geller вернуло ответ со статусом 200, данный ответ содержит JSON данные, которые имеют общую структуру для всех API запросов:

Параметр	Тип	Значение по ум.	Описание
result	str	«ok»	Результат обработки запроса, возможные значения: «ok», «error».
data	optional (object)	null	Полезная нагрузка, которую предоставляет API запрос, отличительная для каждого запроса.
message	str	«ok»	Вспомагательное сообщение.

В зависимости от запроса, полезная нагрузка так же имеет свою особую структуру.

3. Формирование подписи

Подпись формируется следующим образом: все обязательные параметры API запроса упорядочиваются в алфавитном порядке ключей, значения конкатенируются через знак двоеточие (“:”), в конце добавляется секретный ключ (без знака ":"), и от полученной строки генерируется md5 хеш и его HEX-представление передается в параметре запроса sign. Для каждого метода свой набор обязательных параметров, также могут передаваться дополнительные параметры, но в формировании подписи они не участвуют. Например, для партнера с секретным ключом «Secret_key», для запроса с параметрами:

        request data = 
                        ```json
                        { 
                          “partner_id”: 1,
                          “account”: “123456789101112”,
                          “service”: 100,
                          “amount”: 1.00,
                          “partner_payment_id”: 123456
                        }
                        ```

Строка подписи будет иметь вид: 123456789101112:1.00:1:123456:100 Secret_key После применения функции MD5: “sign”: “a93f0021cb2dd5dc1f8ea8a000f3879f”

Описание основных методов API

Создание платежа

Данный метод должен осуществляться перед каждым запросом на создания платежа. URL: https://{Host}invoice Method: POST Обязательные параметры запроса:"partner_id", "payway", "amount", "partner_invoice_id"

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

        request data= 
                        ```json
                        { 
                          'amount': 1.0,
                          'partner_invoice_id': 'i_12345',
                          'payway': 100,
                          'partner_id': 1,
                          'sign': '1a3B5c8D1a3B5c8D1a3B5c8D1a3B5c8D'
                        }
                        ```
                         

Описание параметров:

Параметр	Описание
payway	платежное направление на стороне сервиса
amount	сумма платежа
partner_invoice_id	идентификатор платежа на стороне сервиса
partner_id	идентификатор партнера в системе Geller, выдается при подключении
sign	подпись

В зависимости от требований провайдера, могут быть переданы дополнительные параметры. Дополнительные параметры для передачи по API сообщаются при подключении конкретного сервиса. В случае успешной обработки запроса, параметр response_data имеет следующие данные: Пример ответа

        response_data  = 
                        ```json
                        { 
                        "message":"Ok",
                        "data":{ 
                                "source":"https://example.card.com/pay/12345",
                        "data":{ 
                                "session_id":"1a2B3c4D1a2B3c4D1a2B3c4D1a2B3c4D"
                                },
                        "method":"GET",
                        "invoice_id":"12345"
                        },
                        "result":"ok"}
                        ```

Для корректного взаимодействия с нашим сервисом по API, необходимо придерживаться правилу и формировать HTML форму, где:

action = url,

method = method,

input, где name=key,

value=value из data.

Где,

Параметр	Описание
source	URL на который необходимо отправить data методом method
data	параметры для отправки методом из method на URL из source
method	метод оправки data на source, формат: POST, GET
invoice_id	идентификатор платежа
*result	результат

Если result равен “ok”, то поле data содержит определенные для каждого запроса параметры. Если result равен “error”, запрос был обработан с ошибкой, значение data - null, поле message содержит описание ошибки.

4.2 Изменение статуса инвойса

Данный метод используется для изменение статуса инвойса посредством отправки соответствующего запроса на ПС в которых это позволено в рамках протоколу). Используется для финализации захолдированных инвойсов. URL: ` https://{Host}/update_invoice ` Method: POST Обязательные параметры запроса: ("invoice_id", "partner_id", "sign", "now") Пример запроса:

        request data= 
                        ```json
                        { 
                            “sign” : ”1a3B5c8D1a3B5c8D1a3B5c8D1a3B5c8D”, 
                            “now” : “01.01.20 00:00:11”, 
                            “invoice_id” : “12345”, 
                            “partner_id” : “1”
                            “op_type ” : “charge”
                        }
                        ```
                         
                        

Описание параметров:

Параметр	Описание
now	время отправки запроса
invoice_id	идентификатор платежа на стороне сервиса Geller
partner_id	идентификатор партнера
sign	подпись
op_type	признак операции холдирования (charge - списание д/с, unhold - разблокировка д/с)

В случае успешной обработки запроса, параметр response_data имеет следующие данные:

        request data= 
                            ```json
                            {
                            "result":"ok",
                            "data":{
                                    "invoice_id":"i_12345",
                                    "partner_id":1,
                                    "geller_invoice_id":12345,
                                    "amount":53.49,
                                    "paysystem_data":{
                                        "ps_payer_account":"123456XXXXXX7890"
                                        },
                                    "paysystem_comission":"None",
                                    "paysystem_processed":"2020-01-01 00:00:120",
                                    "paysystem_invoice_id":"12345;",
                                    "extra_data":{
                                    "session_id":"fk5Fdbmoor50d9FlZ132qWaD8"
                                        },
                                    "status":"<InvoiceStatus.Paid":2>
                                    },
                            "message":"OK"
                            }
                            ```

Где:

invoice_id - идентификатор платежа на стороне партнера;
partner_id - идентификатор партнера;
geller_invoice_id - идентификатор платежа на стороне сервиса;
amount - сумма платежа;
ps_payer_account - реквизиты плательщика которые возвращает ПС
paysystem_comission - размер комиссии которую возвращает ПС
paysystem_processed - дата проведения платежа в ПС
paysystem_invoice_id - идентификатор платежа в ПС
status - статус операции
extra_data - это json поле, могут содержать дополнительную информацию
paysystem_data - это json поле, могут содержать дополнительную информацию

Callback

Данный метод используется для отправки колбека на партнера URL: (запрашивается менеджером у партнера при подключении) Method: POST Обязательные параметры запроса:"partner_id", "invoice_id", "status", "geller_invoice_id", "amount" * Также сервис дополнительно отправит в колбеке все дополнительные параметры которые были получены при запросе на создание платежа. Пример запроса:

        request_data = 
                        ```json
                        { 
                          'status' : 9,
                          'sign' : '1a3B5c8D1a3B5c8D1a3B5c8D1a3B5c8D',
                          'geller_invoice_id' : 12345678,
                          'partner_id' : 1,
                          'invoice_id' : 'i_12345',
                          'amount' : 1.00,
                        }
                        ```

Где:

Параметр	Описание
status	Статус операции( детальное описание статусов см. ниже )
sign	подпись
geller_invoice_id	идентификатор платежа на стороне сервиса Geller
partner_id	идентификатор партнера
invoice_id	идентификатор платежа на стороне партнера
amount	сумма платежа

Описание статусов

Status code	Описание
2	Статус операции(Paid)
3	Статус операции(Rejected)
9	Статус операции(Hold)

##Group Протокол взаимодействия Host2Host

Взаимодействие по прооколу Host2Host позволяет производить процесс сбора карточных данных на стороне ресурса, в случае наличия сертификата PCI DSS. Взаимодействие между ресурсом с сервисом Piastrix осуществляется с помощью запросов по API.

Для создания платежа методом Host2Host необходимо отправить запрос Создания платежа. В ответе на запрос о создании счета возвращается ID session_id, который необходимо использовать для передачи карточных данных.
Отправить запрос H2H Data для получения токена. В ответе на запрос возвращается токен form_token и URL payform_url, которые необходимо использовать для передачи карточных данных.
После ответа на запрос H2H Data, необходимо сформировать и подтвердить HTML форму Pay Form на payform_url методом POST с данными карты плательщика

###Запрос H2H Data [/h2hdata]

Test URL: https://test-core.first-icard.com/h2h_data

Production URL: https://h2h-core.piastrix.com/h2h_data

Метод: POST

Обязательные параметры: session_id

С помощью запроса H2H Data необходимо передать session_id. В ответе вернется токен form_token и URL payform_url, которые необходимо использовать для передачи карточных данных.

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

   <li> &#123;
    <li>   "session_id":26d90ef012e34b44aa9d74a3556e15a6 </li>
    &#125; </li>

Где:

Параметр	Описание	Формат
session_id	ID полученнвый в ответе на запрос Invoice create	string

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

   <li> &#123;
    <li>"data":</li>
    <li>`{`</li>
    <li>"form_token":"uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8", </li>
    <li>"payform_url":https://card.piastrix24.com/payform/ </li>
    <li>`},`</li>
    <li>"error_code":0,</li>
    <li>"message":"success",</li>
    <li>"result":true</li>
    &#125; </li>

Где:

Параметр	Описание	Формат
form_token	Токен для передачи карточных данных	string
payform_url	URL для редиректа пользователя с карточными данными	string

Group Запрос H2H Data [POST]

Request (application/json)

  ```json
  {
      "session_id":"26d90ef012e34b44aa9d74a3556e15a6"
  }
  ```

Response 200 ()

  ```json
  {
    "data":
    {
    "form_token":"uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8", 
    "payform_url":"https://card.piastrix24.com/payform",
    },
    "error_code": 0, 
    "message": "Ok", 
    "result": true 
  }      
  ```

###Формирование HTML формы Payform [/Payform]

Метод: POST

Обязательные параметры: session_id,card_number,card_holder,expiry_month,expiry_year,cvv,payform_url,form_token.

Параметр session_id береться из ответа запроса Invoice create .

После подтверждения HTML формы пользователь будет перенаправлен на страницу 3ds верификации.
После прохождения 3ds пользователь будет возвращен на соответствующие success или failed URL, которые передаются в запросе Invoice create .
Параллельно, вам будет отправлен callback. Если платеж неуспешен, то в callback вернется причина отказа, в случае ели она была передана шлюзом.

Пример Формы:

Параметр	Описание	Формат
`expiry_year`	год окончания действия карты	`22`
`card_holder`	TEST TEST	`https://piastrix.com/failed/`
`card_number`	номер карты пользователяа	`4111111111111111`
`expiry_month`	месяц окончания действия срока карты	`12`
`cvv`	трёхзначный код проверки подлинности карты	`123`
`session_id`	уникальный идентификатор операции оплаты	`26d90ef012e34b44aa9d74a3556e15a6`
`form_token`	токен для передачи карточных даннх	`0e61dd5935054d7e99d3da0cef411758`
`action`	URL для редиректа пользователя с карточными данными	`https://card.first-icard.com/en/payform`

###Отправить запрос PayForm [POST]

Request (application/json)

{'expiry_year': '**', 'cvv': '***', 'expiry_month': '**', 'card_number': '****************', 'card_holder': '************', 'sign': 'bcc0f7c61d0ef0f7063b1aef59989a0b7c0ac3daa8f5ae3fca85c28c436fb28a', 'session_id': '033695c6ba634e0c94533085c5c372ca'}",

Response 200 ()

{
https://first-icard.com/
}

Основные принципы взаимодействия с сервисом Geller​

2. Ответ на API запрос

3. Формирование подписи

Описание основных методов API​

Создание платежа​

4.2 Изменение статуса инвойса

Callback​

Group Запрос H2H Data [POST]​

Основные принципы взаимодействия с сервисом Geller

Описание основных методов API

Создание платежа

Callback

Group Запрос H2H Data [POST]