Спецификация по взаимодействию торговца с ПО Dispatcher
Оплата на платежной странице процессинга
Для оплаты на платежной странице процессинга необходимо выполнить редирект на страницу процессингово центра, с POST данными.
Production url: https://pay.concord.ua/api/
POST параметры:
| Параметр | Описание | Значение |
|---|---|---|
| operation | Тип операции | Purchase |
| merchant_id | ID мерчанта, выдается поцесcингом | |
| amount | Сумма операции. Пример 500.00 | |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,order_id,amount,currency_iso,description разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! | ||
| order_id | Уникальный номер операции на стороне торговца. Если операция дублируется - торговец получает ошибку. | |
| currency_iso | Валюта платежа. | UAH |
| description | Назначение платежа. Выводится на платежной странице, при вводе платежных реквизитов. Отображается в выписке по счету и реестрах | |
| add_params | Массив с дополнительными параметрами. Дополнительные параметры потом возвращаются мерчанту в callback вызове | |
| approve_url | URL для переадресации в случае, если платеж успешен | |
| decline_url | URL для переадресации в случае, если платеж не успешен | |
| cancel_url | URL для переадресации в случае, если пользователь отказался совершить оплату | |
| callback_url | URL на который прийдет информация о результате выполнения платежа | |
| redirect | true/false - по умолчанию true, если параметр стоит true, тогда клиент не будет получать переадресацию, а получит url платежной страницы | Не обязательный |
| auth_type | По умолчанию 1 - покупка, 2-Предавторизация | Не обязательный |
Callback вызов для отправки уведомления о статусе платежа
Данные отправляются по URL адресу который указан в параметрах платежа в поле
callback_url.
Данные отправляются на сервер торговца в формате JSON
Параметры:
| Название параметра | Описание | Значения |
|---|---|---|
| merchantAccount | ID мерчанта | |
| orderReference | ID операции в системе торговца | |
| amount | Сумма операции | |
| currency | Валюта операции | |
| phone | Номер телефона клиента(Если включен ввод телефона на платежной странице) | |
| createdDate | Дата платежа в формате YYYY-MM-DD HH:II:SS | |
| Пример: 2018-12-14 12:01:26 | ||
| cardPan | Маскированный PAN карты. | |
| Пример: 535277******0298 | ||
| cardType | Тип карты | Visa |
| MasterCard | ||
| fee | Комиссия за операцию | |
| transactionId | ID транзакции на стороне ПЦ | |
| type | Тип операции. На данный момент параметр не используется | |
| recToken | Токен для рекурентного платежа | |
| transactionStatus | Статус операции | Approved - Успешно |
| Declined - Отказ | ||
| reason | Текстовая причина отказа | |
| reasonCode | Код ошибки при отказе | |
| merchantSignature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,orderReference,amount,currency разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
Рекуррентные платежи RecPayment(оплата по токену)
Production url: https://pay.concord.ua/api/
Для совершения рекуррентного платежа необходимо отправить POST запрос со следующими параметрами:
| Название | Описание |
|---|---|
| operation | Необходимое значение для данной операции RecPayment |
| merchant_id | Идентификатор мерчанта |
| amount | Сумма операции. Пример 500.00 |
| recurring_token | Токен полученный от ПС |
| order_id | Уникальный номер заказа в системе торговца |
| description | Назначение платежа |
| currency_iso | Валюта. На данный момент только UAH |
| auth_type | 1 - покупка, 2 - предавторизация. Не обязательный. По умолчанию - 1 |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,order_id,amount,recurring_token,currency_iso,description разделенных “;” (точка с запятой) в кодировке UTF-8. | |
| Порядок параметров при конкатенации важен! |
В ответ приходят следующие параметры:
| Название | Параметры |
|---|---|
| status | APPROVED - успешно, |
| DECLINED - операция не успешна | |
| code | Код ответа |
Операция Verify
Для пополнения карты необходимо отправить переадресовать пользователя на страницу платежного шлюза методом POST со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| operation | тип операции “Verify” | String |
| merchant_id | идентификатор мерчанта | String |
| order_id | Это уникальный номер операции. Генерируется на стороне мерчанта. Он должен быть уникальным на протяжении всей работы. | Integer |
| approve_url | URL на который будет перенаправлен пользователь в случае успешной операции | String |
| decline_url | URL на который будет перенаправлен пользователь в случае не успешной операции | String |
| cancel_url | URL на который будет перенаправлен пользователь в случае отмены операции | String |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | String |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,order_id,amount,approve_url,decline_url,cancel_url разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
Операция Reverse
Для проверки статуса платежа или верификации карты необходимо отправить POST запрос на url https://pay.concord.ua/api/reverse со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| merchant_id | идентификатор мерчанта | String |
| order_id | Это уникальный номер операции которая была отправлена в запросе P2PCredit,P2PDebit или Verify | Integer |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | String |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров $merchant_id,$order_id разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
В ответ возвращается JSON со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| code | Код ответа. (Список кодов ответа см. ниже) | Integer |
| message | Текстовое сообщение с результатом запроса | String |
Операция Complete
Для проверки статуса платежа или верификации карты необходимо отправить POST запрос на url https://pay.concord.ua/api со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| merchant_id | идентификатор мерчанта | String |
| operation | Complete | String |
| order_id | Это уникальный номер операции которая была отправлена в запросе Purchase | Integer |
| amount | Сумма списания | float |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | String |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров $merchant_id,$order_id ,$amount разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
В ответ возвращается JSON со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| code | Код ответа. (Список кодов ответа см. ниже) | Integer |
| message | Текстовое сообщение с результатом запроса | String |
Операция Check
Для проверки статуса платежа или верификации карты необходимо отправить POST запрос на url https://pay.concord.ua/api/check со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| merchant_id | идентификатор мерчанта | String |
| order_id | Это уникальный номер операции которая была отправлена в запросе P2PCredit,P2PDebit или Verify | Integer |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | String |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров $merchant_id,$order_id разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
В ответ возвращается JSON со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| reasoneCode | Код ответа. (Список кодов ответа см. ниже) | Integer |
| reason | Описание ответа | String |
| merchantAccount | мерчант | String |
| amount | Сумма | String |
| phone | Номер телефона | String |
| createdDate | дата платежа | String |
| cardPan | Маскированный номер карты | String |
| cardType | Тип карты | String |
| transactionId | Идентификатор транзакции | BigInteger |
| message | Текстовое сообщение с результатом запроса | String |
| datetime | Дата создания операции на сервере | String |
| fee | Комиссия платежа | Double |
| transactionStatus | Статус операции(Справочник см ниже) | String |
Операция P2PCredit
Для пополнения карты необходимо отправить POST запрос со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| operation | тип операции “P2PCredit” | String |
| merchant_id | идентификатор мерчанта | String |
| order_id | Это уникальный номер операции. Генерируется на стороне мерчанта. Он должен быть уникальным на протяжении всей работы. | String |
| amount | Сумма операции, должна быть дробным числом, c двумя знаками после запятой. Пример: 100.50 | Double |
| card_number | Номер карты получателя. | String |
| token | Токен, можно использовать вместо карты получателя | String |
| currency_iso | Валюта операции. На данный момент доступна только “UAH” | String |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | String |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров $merchant_id,$order_id,$amount,card_number,currency_iso разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
В ответ возвращается JSON со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| code | Код ответа. (Список кодов ответа см. ниже Коды ответа P2PCredit) | Integer |
| message | Текстовое сообщение с результатом запроса | String |
| status | Статусы операции | String |
| APPROVED - перевод успешен | ||
| DECLINED - Перевод не успешен | ||
| ON-PAYMENT - Заявка на перевод в обработке, необходимо дополнительно запросить статус | ||
| transactionID | Идентификатор транзакции в платежной системе | Integer |
| approvalCode | Код авторизации | Integer |
Операция получения баланса (GetBalance)
Для пополнения карты необходимо отправить POST на url https://pay.concord.ua/api/balance запрос со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| operation | тип операции “GetBalance” | String |
| merchant_id | идентификатор мерчанта | String |
| date | Дата и время запроса в произвольном формате | String |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | String |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров $merchant_id,$data разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
В ответ возвращается JSON со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| mk_deposit | Лимит Mastercard | Float |
| visa_deposit | Лимит Visa | Float |
| mk_available | Доступный остаток Mastercard | Float |
| visa_available | Доступный остаток Visa | Float |
Операция P2PDebit
Для списания средств с карты необходимо переадресовать пользователя на страницу платежного шлюза методом POST со следующими параметрами:
| Имя параметра | Описание | Тип |
|---|---|---|
| operation | тип операции “P2PDebit” | String |
| merchant_id | идентификатор мерчанта | String |
| order_id | Это уникальный номер операции. Генерируется на стороне мерчанта. Он должен быть уникальным на протяжении всей работы. | Integer |
| amount | Сумма операции, должна быть дробным числом, c двумя знаками после запятой. Пример: 100.50 | Double |
| currency_iso | Валюта операции. На данный момент доступна только “UAH” | String |
| description | Назначение платежа | String |
| approve_url | URL на который будет перенаправлен пользователь в случае успешной операции | String |
| decline_url | URL на который будет перенаправлен пользователь в случае не успешной операции | String |
| cancel_url | URL на который будет перенаправлен пользователь в случае отмены операции | String |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | String |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,order_id,amount,currency_iso,description,approve_url,decline_url,cancel_url разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
Операция PurchaseOnMerchant
Для оплаты на платежной странице мерчанта необходимо отправить POST запрос со следующими данными данными.
Production url: https://pay.concord.ua/api/
POST параметры:
| Параметр | Описание | Значение |
| operation | Тип операции | PurchaseOnMerchant |
| merchant_id | ID мерчанта, выдается поцесcингом | |
| amount | Сумма операции. Пример 500.00 | |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,order_id,amount,currency_iso,description разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! | ||
| order_id | Уникальный номер операции на стороне торговца. Если операция дублируется - торговец получает ошибку. | |
| currency_iso | Валюта платежа. | UAH |
| description | Назначение платежа. Выводится на платежной странице, при вводе платежных реквизитов. Отображается в выписке по счету и реестрах | |
| add_params | Массив с дополнительными параметрами. Дополнительные параметры потом возвращаются мерчанту в callback вызове | |
| token | Токен для списания с карты без передачи реквизитов карты | |
| card_num | Номер карты | |
| card_exp_month | Срок действия карты MM | |
| card_exp_year | Срок действия карты YY | |
| card_cvv | CVV2 код, в случае операции без CVV необходимо указать -1 | |
| card_holder | Владелец карты. Не обязательное поле | |
| phone | Номер телефона клиента. Не обязательное поле | |
| payment_type | Тип платежа. | |
| Purchase - покупка | ||
| PreAuth - блокирование средств на карте | ||
| secure_type | Тип прохождения безопасности транзакции | |
| Может принимать следующие значения: | ||
| Auto | ||
| 3DS | ||
| Non3DS | ||
| callback_url | URL на который прийдет информация о результате выполнения платежа |
Ответ:
| Параметр | Описание | Значение |
| status | Статус платежа | справочник “Статусы платежа” |
| code | Код ответа | Справочник “Коды ответов” |
| order_id | Уникальный номер заказа в системе торговца | |
| amount | Сумма платежа | |
| fee | Комиссия | |
| currency | Валюта платежа | |
| token | Токен для последующих оплат. Токен вернется в случае, если платеж успешен | |
| d3_acs_url | URL acs сервера на который необходимо отправить пользователя для верификации | |
| d3_md | Уникальный идентификатор который необходимо передать на ACS сервер | |
| d3_pareq | Запрос который необходимо передать на ACS сервер | |
| transaction_key | Ключ транзакции, который необходимо использовать для подтверждения платежа | |
| transaction_id | Идентификатор транзакции | |
| signature |
Если в ответе code пришло значение 2001 необходимо провести проверку 3DS.
Для проверки 3ds необходимо методом POST отправить форму с параметрами d3_md, d3_pareq, term_url на d3_acs_url.
term_url - url на который вернется результат проверки 3DS.
<form name="MPIform" action='${d3_acs_url}' method="POST">
<input type="hidden" name="PaReq" value='${d3_pareq }'>
<input type="hidden" name="MD" value='${d3_md }'>
<input type="hidden" name="TermUrl" value='${term_url}'>
</form>
Получение токена для Masterpass
Production url: https://pay.concord.ua/api/mptoken
Для получения гостевого токена необходимо отправить POST запрос со следующими данными данными.
| Параметр | Описание |
|---|---|
| msisdn | Номер телефона для входа в кошелек Masterpass в формате 380XXXXXXXXX |
| client_id | Идентификатор клиента в системе MasterPass |
В ответ приходит объект в формате JSON со следующими параметрами:
| Параметр | Описание |
|---|---|
| res | Результат запроса 0 - все ок |
| msg | Сообщение об ошибке |
| token | Токен для передачи в mfs библиотеку |
| reference_no | Уникальный номер запроса |
Проведение платежа через Masterpass
Production url: https://pay.concord.ua/api
Для получения гостевого токена необходимо отправить POST запрос со следующими данными данными.
| Параметр | Описание | Значение |
|---|---|---|
| operation | Тип операции | PurchaseMasterpass |
| merchant_id | Идентификатор мерчанта | |
| amount | Сумма платежа в формате 1.00 | |
| order_id | ||
| currency_iso | Валюта | UAH |
| description | Описание плаатежа | |
| approve_url | URL для переадресации после успешного платежа (в случае подтверждения 3DS на странице ConcordPay) | |
| decline_url | URL для переадресации после не успешного платежа (в случае подтверждения 3DS на странице ConcordPay) | |
| cancel_url | URL для переадресации после отмены платежа (в случае подтверждения 3DS на странице ConcordPay) | |
| callback_url | URL на который будет отправлен callback о статусе платежа | |
| add_params[wallet] | Признак кошелька | masterpass |
| add_params[msisdn] | Номер телефона для входаа в кошелек Masterpass в формате 380XXXXXXXXX | |
| add_params[token] | Токен полученный с сервера MasterPass | |
| add_params[card_name] | Alias карты полученный с сервера MasterPass | |
| add_params[client_id] | Идентификатор мерчанта в системе MasterPass | |
| add_params[ret_ref_no] | Уникальный номер транзакции полученный с сервера MasterPass | |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,order_id,amount,currency_iso,description разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
В ответ приходит объект в формате JSON со следующими параметрами:
Если транзакция требует подтверждения 3DS:
| Параметр | Описание |
|---|---|
| code | Код ответа |
| status | Статус транзакции, если необходима проверка 3DS , в статусе , будет значение 3ds |
| d3AcsUrl | url для перенаправления клиента, для проверки 3ds |
| d3Md | Криптограмма для передачи на хост 3DS |
| d3Pareq | Запрос для передачи на хост 3DS |
| transaction_key | Ключ транзакции для подтверждения 3DS |
| TermUrl | Url для переадресации после вводе кода подтверждения на странице 3DS. По умолчанию url на страницу ConcordPay, для проверки 3DS можно указать свой URL, тогда после прохождения 3DS необходимо вызвать метод “Подтверждение 3DS верификации” |
Подтверждение 3DS верификации
Для оплаты на платежной странице мерчанта необходимо отправить POST запрос со следующими данными данными.
Production url: https://pay.concord.ua/api/
| Параметр | Описание | Значение |
|---|---|---|
| operation | Тип операции | Complete3DS |
| transaction_key | Ключ транзакции | |
| merchant_id | Идентификатор мерчанта | |
| d3ds_md | Идентификатор полученный после редиректа с сервера ACS | |
| d3ds_pares | Сообщение полученное после редиректа с сервера ACS | |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,transaction_key,d3ds_md,d3ds_pares разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! |
Ответ
| Параметр | Описание | Значение |
|---|---|---|
| status | Статус платежа | справочник “Статусы платежа” |
| code | Код ответа | Справочник “Коды ответов” |
| order_id | Уникальный номер заказа в системе торговца | |
| amount | Сумма платежа | |
| fee | Комиссия | |
| currency | Валюта платежа | |
| card_pan | Маскированный номер карты | |
| transaction_id | Идентификатор транзакции |
Оплата на платежной странице процессинга с расщеплением платежа
Для оплаты на платежной странице процессинга необходимо выполнить редирект на страницу процессингово центра, с POST данными.
Production url: https://pay.concord.ua/api/
POST параметры:
| Параметр | Описание | Значение |
| operation | Тип операции | Purchase |
| merchant_id | ID мерчанта, выдается поцесcингом | |
| amount | Сумма операции. Пример 500.00 | |
| signature | В целях подтверждения валидности данных должна быть сгенерирована и передана в запросе HMAC_MD5 контрольная подпись с использованием SecretKey торговца. | |
| Строка, подлежащая HMAC_MD5, генерируется путем конкатенации параметров merchant_id,order_id,amount,currency_iso,description разделенных “;” (точка с запятой) в кодировке UTF-8. | ||
| Порядок параметров при конкатенации важен! | ||
| order_id | Уникальный номер операции на стороне торговца. Если операция дублируется - торговец получает ошибку. | |
| currency_iso | Валюта платежа. | UAH |
| description | Назначение платежа. Выводится на платежной странице, при вводе платежных реквизитов. Отображается в выписке по счету и реестрах | |
| add_params | Массив с дополнительными параметрами. Дополнительные параметры потом возвращаются мерчанту в callback вызове | |
| split | Признак расщепления платежа | 0 - не расщеплять |
| 1 - расщеплять | ||
| split_rules | Массив с правилами расщепления который содержит в себе идентификаторы субмерчанта и суммы. | |
| Сумма расщеплений должна совпадать с суммой платежа. | ||
| Пример: | ||
| split_rules[0][sub_merchant_id]=test1&split_rules[0][amount]=100.00&split_rules[1][sub_merchant_id]=test2&split_rules[1][amount]=50.00&.......&split_rules[n][sub_merchant_id]=testn&split_rules[n][amount]=10.00 | ||
| approve_url | URL для переадресации в случае, если платеж успешен | |
| decline_url | URL для переадресации в случае, если платеж не успешен | |
| cancel_url | URL для переадресации в случае, если пользователь отказался совершить оплату | |
| callback_url | URL на который прийдет информация о результате выполнения платежа |