Платежный виджет
Важно: При изучении данной документации просим учесть, что использование метода оплаты Apple Pay не будет возможно, так как политика токенизации платежей не позволяет отображать кнопку Apple Pay на странице, которая открыта с помощью виджета.
При регистрации вам будут выданы данные, которые нужно будет использовать при проведении платежа:
TerminalID | Идентификатор магазина |
ClientID | Идентификатор клиента |
ClientSecret | Секретный ключ |
Test merchant
url | https://test-epay.homebank.kz |
epay@halykbank.kz | |
password | XZG1E@Mm |
ClientID | test |
ClientSecret | yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG |
TerminalID | 67e34d63-102f-4bd1-898e-370781d0074d |
Test payment card
PAN | Expire Date | CVC | Status |
---|---|---|---|
4405639704015096 | 01/25 | 815 | unlock |
5522042705066736 | 01/25 | 525 | unlock |
377514500004820 | 01/25 | 4169 | lock |
4003032704547597 | 09/20 | 170 | lock |
5578342710750560 | 09/20 | 254 | lock |
Получение токена для проведения оплаты (для каждой операции необходимо получать и использовать оригинальный токен)
TEST URL POST https://testoauth.homebank.kz/epay2/oauth2/token PROD URL POST https://epay-oauth.homebank.kz/oauth2/token
Запрос
Body: form-data
grant_type: "client_credentials" scope: "webapi usermanagement email_send verification statement statistics payment" client_id: "ClientID" client_secret: "ClientSecret" invoiceID: "Номер заказа" secret_hash: "JDKCNDDGGDTPSKJD" amount: 100 currency: "KZT" terminal: "TerminalID"
Поле | Описание |
---|---|
grant_type | Тип авторизации, для проведения платежа используется тип client_credentials |
scope | ресурс |
client_id | Идентификатор коммерсанта, можно получить в кабинете, выдается при регистрации |
client_secret | Ключ доступа коммерсанта, можно получить в кабинете, выдается при регистрации |
invoiceID | Номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа,от 6 до 15 цифр. Если ваш номер заказа содержит более 6 символов, то дополнительно уникальность должна соблюдаться по последним 6ти символам |
secret_hash | дополнительное секретное значение(строка), сгенерированное системой интернет-магазина, которое будет возвращено на Postlink |
amount | Сумма заказа |
currency | Валюта |
terminal | Идентификатор точки продаж, можно получит в кабинете, выдаётся при регистрации |
Ответ:
{
"access_token":"DCEB8O_ZM5U7SO_T_U5EJQ",
"expires_in": 7200,
"refresh_token":"",
"scope":"webapi usermanagement email_send verification statement statistics payment",
"token_type":"Bearer"
}
Поле | Описание |
---|---|
access_token | Токен для проведения операции |
expires_in | Время истечения токена |
refresh_token | Не используется при данном типе авторизации |
scope | Ресурс, для проведения платежа используется ресурс payment |
token_type | Тип авторизации |
Вызов виджета
На странице нужно подключить JS-библиотеку и вызвать в ней метод halyk.showPaymentWidget().
URL: https://test-epay.homebank.kz/payform/payment-api.js
В метод
halyk.showPaymentWidget(createPaymentObject(auth, invoiceId, amount), callBk)
var createPaymentObject = function(auth, invoiceId, amount) { var paymentObject = { invoiceId: "000001", invoiceIdAlt: "000001", backLink: "https://example.kz/success.html", failureBackLink: "https://example.kz/failure.html", postLink: "https://example.kz/", failurePostLink: "https://example.kz/order/1123/fail", language: "RUS", description: "Оплата в интернет магазине", accountId: "testuser1", terminal: "TerminalID", amount: 100, name: "Arman Ali", currency: "KZT", data: "{\"statement\":{\"name\":\"Arman Ali\",\"invoiceID\":\"80000016\"}}", cardSave: true //Параметр должен передаваться как Boolean }; paymentObject.auth = auth; return paymentObject; }; halyk.showPaymentWidget(createPaymentObject(auth, invoiceId, amount), callBk);
Поле | Описание |
---|---|
invoiceId | Номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа, от 6 до 15 цифр. Если ваш номер заказа содержит более 6 символов, то дополнительно уникальность должна соблюдаться по последним 6ти символам |
invoiceIdAlt | Альтернативный номер заказа, генерируется коммерсантом, должен быть уникальный для каждого нового заказа, от 6 до 15 цифр |
backLink | Ссылка для возврата в магазин при удачном платеже |
failureBackLink | Ссылка для возврата в магазин при не удачном платеже |
postLink | Уведомление о платеже |
failurePostLink | Уведомление о неудачном платеже, если не заполнено, то информация будет отправлена на адрес указанный в postLink |
language | Язык rus/kaz/eng |
description | Описание заказа, допустимое количество символов 125 байтов |
accountId | Не обязательное поле для указание идентификатора клиента магазина |
terminal | Идентификатор магазина |
amount | Сумма заказа |
name | имя плательщика, только на латинице (не обязательно) |
currency | Валюта |
auth | Токен / передается полностью как объект, все данные полученные от epay по запросу токена |
callBk | Передается объект { success: true | false } |
data | Дополнительное поле транслируется в отчете при заполнении (необязательно) |
Метод halyk.showPaymentWidget() принимает вторым параметром коллбек, который вызовется по результатам отработки платежа.
Postlink
На указанный URL указанный в поле postLink будет отправлено сообщение.
В случае успеха:
{ "id": "ffffffff-0000-000f-f000-00f0000f000f", "dateTime": "2020-01-01T00:00:00.00000+06:00", "invoiceId": "10000000001", "invoiceIdAlt":"8564546", "amount": 100, "currency": "KZT", "terminal": "67e34d63-102f-4bd1-898e-370781d0074d", "accountId": "1", "description": "Оплата в интернет магазине", "language": "RU", "cardMask": "4444...4444", "cardType": "", "issuer": "Halyk bank", "reference": "001111111111", "secure": "yes", "tokenRecipient": "", "code": "ok", "reason": "", "reasonCode": 0, "name": "CARD HOLDER", "email": "ch@example.kz", "phone": "77777777777", "ip": "5.188.155.135", "ipCountry": "Kazakhstan", "ipCity": "Almaty", "ipRegion": "", "ipDistrict": "", "ipLongitude": 76.9293, "ipLatitude": 43.2638, "cardId": "e7e2587f-de26-4f41-ae1f-80c1fea31728" }
В случае неудачи:
{ "id": "ffffffff-0000-000f-f000-00f0000f000f", "dateTime": "2020-01-01T00:00:00.00000+06:00", "invoiceId": "10000000001", "invoiceIdAlt":"8564546", "amount": 100, "currency": "KZT", "terminal": "67e34d63-102f-4bd1-898e-370781d0074d", "accountId": "1", "description": "Оплата в интернет магазине", "language": "RU", "cardMask": "4444...4444", "cardType": "", "issuer": "Halyk bank", "reference": "", "secure": "yes", "tokenRecipient": "", "code": "error", "reason": "описание ошибки", "reasonCode": -498, "name": "CARD HOLDER", "email": "ch@example.kz", "phone": "77777777777", "ip": "5.188.155.135", "ipCountry": "Kazakhstan", "ipCity": "Almaty", "ipRegion": "", "ipDistrict": "", "ipLongitude": 76.9293, "ipLatitude": 43.2638 }