Платежный виджет

Важно: При изучении данной документации просим учесть, что использование метода оплаты Apple Pay не будет возможно, так как политика токенизации платежей не позволяет отображать кнопку Apple Pay на странице, которая открыта с помощью виджета.

При регистрации вам будут выданы данные, которые нужно будет использовать при проведении платежа:

TerminalIDИдентификатор магазина
ClientIDИдентификатор клиента
ClientSecretСекретный ключ

Test merchant

urlhttps://test-epay.homebank.kz
emailepay@halykbank.kz
passwordXZG1E@Mm
ClientIDtest
ClientSecretyF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG
TerminalID67e34d63-102f-4bd1-898e-370781d0074d

Test payment card

PANExpire DateCVCStatus
440563970401509601/25815unlock
552204270506673601/25525unlock
37751450000482001/254169lock
400303270454759709/20170lock
557834271075056009/20254lock

Получение токена для проведения оплаты (для каждой операции необходимо получать и использовать оригинальный токен)

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
}