HTTP-интерфейс шлюза в тестовом контуре доступен по URL:
HTTP-интерфейс шлюза в тестовом контуре доступен по URL:
https://telcellmoney.am/proto_test2/invoices
HTTP-интерфейс шлюза в боевом контуре доступен по URL:
https://telcellmoney.am/invoices
Необходимые реквизиты для формирования запросов (идентификатор магазина, ключ магазина) будут предоставлены после обращения к сотрудникам Telcell.
Редирект клиента для оплаты счёта выполняется на URL:
https://telcellmoney.am/payments/invoice/?invoice=id_выставленного_счёта&return_url=url_магазина_для_возврата_клиента_после_оплаты
Запросы к API выполняются методом POST. Значения текстовых полей кодируются base64. Все значения передаются urlencoded.
bill:issuer=идентификатор магазина
buyer=идентификатор покупателя
currency=код валюты счёта
sum=сумма счёта (целая часть отделяется от дробной символом «.»)
description=назначение платежа
issuer_id=код заказа в системе магазина
valid_days=срок действия счёта в днях
valid_time=время до которого действителен счёт
info=дополнительная информация от магазина
checksum=хеш-подпись
В качестве идентификатора покупателя (buyer) передается полный код ean13.
Параметр valid_time имеет приоритет относительно параметра valid_days, но если будет указан некорректно (срок действия счета уже прошел либо формат некорректен), данный параметр не используется. Корректный формат: YYYYMMDDhhmmss.
Хеш подпись (checksum) формируется по алгоритму md5 от строки:
ключ_магазина+issuer+buyer+currency+sum+description+valid_days+issuer_id
Если передано поле info, то хеш подпись формируется:
ключ_магазина+issuer+buyer+currency+sum+description+valid_days+issuer_id+info
В ответе будет содержаться id выставленного счёта в системе или сообщение о возникшей ошибке. Возможные варианты сообщений об ошибке содержатся в приложении B.
После получения id выставленного счёта существует опциональная возможность перенаправить клиента на страницу оплаты по адресу
https://telcellmoney.am/payments/invoice/?invoice=id_выставленного_счёта&return_url=url_магазина_для_возврата_клиента_после_оплаты
В случае изменения статуса выставленного магазином счёта, система выполняет на URL магазина HTTP POST запрос, содержащий информацию о новом статусе.
Поля запроса:
invoice=id счёта
issuer_id=код заказа в системе магазина
payment_id=id операции
buyer=email или телефон покупателя
currency= код валюты счёта
sum=сумма счёта (целая часть отделяется от дробной символом «.»)
time=время события в формате yyyy-MM-dd HH:mm:ss (timestamp)
status=новый статус счёта
checksum=хеш-подпись
Хеш подпись (checksum) формируется по алгоритму md5 от строки:
ключ_магазина+invoice_id+issuer_id+payment_id+buyer+currency+sum+time+status
Возможные значения поля status содержатся в приложении A.
Для получения статуса любого из выставленных магазином счетов, магазин может выполнить HTTP POST запрос с параметрами:
check_bill:issuer=идентификатор магазина
invoice=id счёта
issuer_id=код заказа в системе магазина
checksum=хеш-подпись
Хеш подпись (checksum) формируется по алгоритму md5 от строки:
ключ_магазина+issuer+invoice+issuer_id
В запросе может отсутствовать один из идентификаторов счёта (invoice или issuer_id). В случае наличия в запросе двух этих полей одновременно, приоритет отдаётся полю invoice
invoice | идентификатор магазина |
status | статус счёта |
sum | сумма счёта |
currency | код валюты счёта |
buyeremail | или телефон покупателя |
description | назначение платежа |
issuer_id | код заказа в системе магазина |
issue_time | время создания счёта |
valid_time | время действия счёта |
received_time | время получения клиентом счёта |
paid_time | время оплаты счёта |
checksum | хеш-подпись |
checksum2 | хеш-подпись 2 |
Хеш подпись (checksum) формируется по алгоритму md5 от строки:
ключ_магазина+содержимое ответа
Хеш подпись 2 (checksum2) формируется по алгоритму md5 от строки:
ключ_системы+checksum
Возможные значения поля status содержатся в приложении A.
Все поля, содержащие время, имеют формат yyyy-MM-dd HH:mm:ss (timestamp)
Для отмены оплаченного счета из выставленных магазином счетов, магазин может выполнить HTTP POST запрос с параметрами:
cancel_bill:issuer=идентификатор магазина
invoice=id счёта
issuer_id=код заказа в системе магазина
checksum=хеш-подпись
Хеш подпись (checksum) формируется по алгоритму md5 от строки:
ключ_магазина+issuer+invoice+issuer_id
В запросе может отсутствовать один из идентификаторов счёта (invoice или issuer_id). В случае наличия в запросе двух этих полей одновременно, приоритет отдаётся полю invoice.
invoice | идентификатор магазина |
status | статус счёта |
sum | сумма счёта |
currency | код валюты счёта |
buyer | email или телефон покупателя |
description | назначение платежа |
issuer_id | код заказа в системе магазина |
issue_time | время создания счёта |
valid_time | время действия счёта |
received_time | время получения клиентом счёта |
paid_time | время оплаты счёта |
checksum | хеш-подпись |
checksum2 | хеш-подпись 2 |
Хеш подпись (checksum) формируется по алгоритму md5 от строки:
ключ_магазина+содержимое ответа
Хеш подпись 2 (checksum2) формируется по алгоритму md5 от строки:
ключ_системы+checksum
Возможные значения поля status содержатся в приложении A.
Все поля, содержащие время, имеют формат yyyy-MM-dd HH:mm:ss (timestamp)
Для отмены оплаченного счета из выставленных магазином счетов, магазин может выполнить HTTP POST запрос с параметрами:
clear_bill:issuer=идентификатор магазина
issuer_id=код заказа в системе магазина
checksum=хеш-подпись
Хеш подпись (checksum) формируется по алгоритму md5 от строки:
ключ_магазина+issuer+issuer_id
invoice=идентификатор магазина
status=статус счёта
sum=сумма счёта
currency=код валюты счёта
paid_date= время оплаты счёта
paid_value= оплачено
paid_total= всего оплачено
advice=DONT_SERVE;STOP_CHECKING
checksum=хеш-подпись
checksum2=хеш-подпись 2
Хеш подпись (checksum) формируется по алгоритму md5 от строки:
ключ_магазина+содержимое ответа
Хеш подпись 2 (checksum2) формируется по алгоритму md5 от строки:
ключ_системы+checksum
Возможные значения поля status содержатся в приложении A.
Все поля, содержащие время, имеют формат yyyy-MM-dd HH:mm:ss (timestamp)
Для выставления счета по QR коду необходимо сформировать запрос с параметрами:
bill:issuer=идентификатор магазина
currency=код валюты счёта (для AMD = 51)
sum=сумма счёта (целая часть отделяется от дробной символом «.»)
description=назначение платежа
issuer_id=код заказа в системе магазина
valid_time=время до которого действителен счёт YYYYMMDDhhmmss
checksum=хеш-подпись
Хеш подпись (checksum) формируется по алгоритму md5 от строки:
ключ_магазина+bill:issuer+currency+sum+description+valid_time+issuer_id
Значения текстовых полей кодируются base64. Все значения передаются urlencoded.
Пример содержимого QR кода:
description=VGVzdA%3D%3D&sum=3.0¤cy=51&issuer_id=MDAw&valid_time=20181211010000&bill:issuer=ccrs%40test.test&checksum=f2345fae5c951338ffaf9dc4b3cdd253
Для выставления счета без получателя по NFC тегу необходимо сформировать запрос с параметрами:
postpone_bill:issuer=идентификатор магазина
cash=данные nfc тега кассы, передаваемые в base64
currency=код валюты счёта (для AMD = 51)
sum=сумма счёта (целая часть отделяется от дробной символом «.»)
description=назначение платежа
issuer_id=код заказа в системе магазина
valid_time=время до которого действителен счёт YYYYMMDDhhmmss
checksum=хеш-подпись
Хеш подпись (checksum) формируется по алгоритму md5 от строки:
ключ_магазина+ postpone_bill:issuer+cash+currency+sum+description+valid_time+issuer_id
Значения текстовых полей кодируются base64. Все значения передаются urlencoded.
Пример запроса:
description=bmZjIHRlc3Qx&sum=1.00¤cy=51&issuer_id=MTA0&valid_days=1&postpone_bill:issuer=test%40test.test&cash=AmVuYWRkZGZm&checksum=9f797d929f8688d12c1d62ca208a814b
Пример исходных данных:
bill:issuer = "sas@test.test"
buyer = "3283005053463"
currency = 51
sum = 1.0
description = "Test"
issuer_id = "issuer0023"
valid_days = 1
Пример отправляемых данных:
bill:issuer = URLEncode("sas@test.test") = sas%40test.test
buyer = 3283005053463
currency = 51
sum = 1
description = URLEncode (Base64("Test")) = VGVzdA%3D%3D
issuer_id = URLEncode (Base64("issuer0023")) = aXNzdWVyMDAyMw%3D%3D
valid_days = 1
checksum = md5("kl3sDvf67*h&#TVFcD=Ghef987UnYDFhufD%&DFkJhjkBDv7!DS68LMdFnmWE&F*&Tdvc6gdjH23grfd7GbHkdJhgKd" + "sas@test.test" + "3283005053463" + "51" + "1.0" + "VGVzdA==" + "1" + "aXNzdWVyMDAyMw==") = 15dc50a6870bdfeecd670899aeb22c4e
Итоговое тело запроса:
description=VGVzdA%3D%3D&sum=1.0¤cy=51&issuer_id=aXNzdWVyMDAyMw%3D%3D&valid_days=1&bill:issuer=sas%40test.test&buyer=3283005053463&checksum=15dc50a6870bdfeecd670899aeb22c4e
NEW - счёт выставлен, но не оплачен.
PAID - счёт успешно оплачен.
REJECTED - счёт отклонён получателем.
EXPIRED - истекло время действия счёта.
CANCELLED - счёт отменён персоналом системы.
CANCELLED FOR REPEAT – счёт отменен для повторного выставления
E0001: parameters are invalid
представлен параметр, не опознаваемый системой, либо не хватает обязательных параметров, либо нулевая/отрицательная сумма счета.
E0002: issuer is invalid
Магазин, от имени которого осуществляется попытка выставления счета, не является зарегистрированным магазином системы (не имеет статус «магазин» либо не зарегистрирован в системе).
E0005: invalid access
Магазин, от имени которого выставляется счет, заблокирован, либо защитный код (checksum) передаваемых параметров не соответствует расчетному.
E0003: no such user
Пользователь системы, которому выставляется счет, не существует.
E0004: user is blocked
Пользователь системы, которому выставляется счет, заблокирован.
E0009: duplicate issuer_id
Попытка выставить счёт с уже использованным issuer_id.
E0006: failure
Внутренняя ошибка системы.
E0007: invoice not found
Счет не обнаружен.