Введение
Введение
Документация и спецификация API (далее - Документация) разработана с целью информирования разработчиков партнеров о доступных методах интеграции и их параметрах.
В рамках документации используются следующие сокращения и определения:
МФС - мобильные финансовые сервисы, услуги AsiaPay по зачислению и списанию денежных средств с/на мобильные номера мобильных операторов связи
AsiaPay - платежная организация, оператор электронных денег, предоставляющая услуги МФС для партнеров
Aбонент - физическое лицо, заключившее с мобильным оператором связи договор на услуги связи, включающий услуги МФС
Партнер - юридическое лицо, заключивший с AsiaPay договор на услуги МФС
Обратная связь
Вопросы и предложения по документации можно направлять на электронный адрес support@asiapay.kz, а также по реквизитам указанным в разделе контакты на официальном сайте asiapay.kz
Этапы имплементации
Заключение партнерского договора
Регистрация партнера и получение доступов в личный кабинет
Разработка - внедрение API на стороне Партнера
Тестирование - внутреннее функциональное, регрессионное и нагрузочное тестирование;
Запуск - релиз разработанного и протестированного решения;
Post-check - финальный ретест доступной функциональности в боевой среде.
Общие сведения по подключению
Следование правильной последовательности API вызовов является важнейшим условием корректности работы интеграционного уровня!
result_url партнера будет вызываться методом HTTP/POST. В случае ошибки, будет передан так же код и описание ошибки. Примеры уведомлений указаны для каждого метода отдельно
Для проведения операций пополнения и списания, на балансе Партнера необходим положительный баланс, не менее суммы операций.
Подключение
Все запросы к API должны быть авторизованы, иначе в ответ будет получена ошибка 403. Авторизация проходит методом HTTP Basic, в заголовке запроса Authorization передается логин и пароль. Данные авторизации предоставляются отдельно от документа.
Данные для подключения:
| Наименования | Значение |
|---|---|
| Тестовый URL | https://apitest.asiapay.kz |
| Боевой URL | https://api.asiapay.kz |
| Порт | 443 |
| Авторизация | HTTP Basic |
| Формат запроса | application/json |
| Формат ответа | application/json |
| Кодировка | UTF-8 |
Оплата с баланса мобильного
В этом разделе описана механика, когда Asiapay.kz списывает деньги с баланса абонента.
Мерчант может использовать этот раздел для прямого подключения со своим сервисом.
V2
Инициализация платежа
POST https://api.asiapay.kz/v2/payment/init
POST https://apitest.asiapay.kz/v2/payment/init
*Инициализация платежа *
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/init' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"phone": "77071234567",
"order_id": "123123abc",
"amount": 10,
"type": "pay",
"description": "Тестовое пополнение 1234",
"terminal_code": "code",
"source": "online",
"language": "ru",
"result_url": "",
"testmode": 2
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2020-01-01 09:00:00",
"payment": {
"id": 123456,
"status": "process",
"amount": 10,
"commission_amount": 110,
"testmode": 2
},
"confirm_inputs": [
{
"name": "Смс код",
"value": "otp"
}
]
}
Метод используется для создания платежа, но не проведения его. При инициализации платежа мерчант должен передать тип платежа в поле type.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| phone | integer | Да | Номер мобильного телефонатолько цифры, формат - 7ххххххххххдлина 11 77079093028 |
| amount | number | Да | Сумма заказа 1000.55 в тенге |
| description | string | Да | Описание заказа. Максимум 255 |
| type | string | Да | Тип платежа: pay, refill |
| terminal_code | string | Нет | Код терминала. |
| source | string | Нет | Канал поступления платежа. Максимум 50 символов. |
| order_id | string | Нет | Номер заказа в системе Партнера |
| language | string | Нет | Язык сообщений. Возможные значения ru, kz, en |
| testmode | integer | Нет | Признак тестового заказа. 0 - боевой, иначе тестовый (см. приложение) |
| result_url | string | Нет | URL для отправки сообщения о выполнении операции. Методом POST (пункт 4.12) |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.amount | float | Сумма платежа |
| payment.commission_amount | float | Сумма комиссии |
| payment.testmode | integer | Признак тестового заказа. 0 - боевой, иначе тестовый (см. приложение) |
| confirm_inputs | array | Массив содержит список объектов с полями, которые требуется отправить в подтверждении платежа (пункт 4.6) |
| confirm_inputs.name | string | Название поля для отображения пользователю |
| confirm_inputs.value | string | Название поля для отправки в методе подтверждения |
Путь прохождения инициализации
Отправка OTP кода
POST https://api.asiapay.kz/v2/payment/otp/resend
POST https://apitest.asiapay.kz/v2/payment/otp/resend
Отправка OTP кода
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/otp/resend' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 123456
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2020-01-01 09:00:00"
}
Метод используется для отправки OTP кода.
Варианты использования:
- Повторный запрос OTP, если истек срок действия предыдущего OTP.
- В случае инициализации платежа через метод
payment/init, если получили в ответе информацию о требуемом подтверждении платежа.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
Подтверждение платежа
POST https://api.asiapay.kz/v2/payment/confirm
POST https://apitest.asiapay.kz/v2/payment/confirm
Подтверждение платежа
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/confirm' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 123456,
"confirm_inputs": {
"otp": "123456"
}
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2020-01-01 09:00:00",
"payment": {
"id": 123456,
"status": "success",
"receipt_url": "https://paycheck.asiapay.kz/?77071234567&12345",
"amount": 1000,
"commission_amount": 110,
"testmode": 2
}
}
Метод используется в том случае, если при вызовах payment/pay и payment/refill была запрошена подтверждающая информация или платеж был создан через метод payment/init.
В случаем если платеж был создан через метод payment/init и не были запрошены данные для подтверждения, ключ confirm_inputs передавать не нужно.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
| confirm_inputs | object | Нет | Объект содержит поля, которые требуется передать для подтверждения платежа. Должен содержать как минимум один ключ и значение. Передается только в том случае, если были запрошены поля подтверждения |
| otp | string | Нет | OTP код, если был запрошен |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.receipt_url | string | Ссылка страницу просмотра и скачивания чека |
| payment.amount | float | Сумма платежа |
| payment.commission_amount | float | Сумма комиссии |
| payment.testmode | integer | Признак тестового заказа. 0 - боевой, иначе тестовый (см. приложение) |
Получение статуса
POST https://api.asiapay.kz/v2/payment/status
POST https://apitest.asiapay.kz/v2/payment/status
Получение статуса
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/status' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 123456
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2020-01-01 09:00:00",
"payment": {
"id": 123456,
"first_payment_id": 123455,
"type": "refill",
"status": "error",
"order_id": "2132-5162-123543",
"description": "Тестовый заказ #1",
"amount": 1000,
"commission_amount": 110,
"failure_code": 404,
"failure_description": "Client error",
"testmode": 1,
"created_at": "2020-08-27 09:00:28",
"completed_at": "2020-08-27 09:00:28"
}
}
Метод позволяет получить текущий статус платежа.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.first_payment_id | integer | ID первого платежа (используется в возвратных платежей) |
| payment.type | string | Тип платежа из таблицы 1 |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.order_id | string | ID платежа в системе Партнера |
| payment.description | string | Описание платежа |
| payment.amount | float | Сумма платежа |
| payment.commission_amount | float | Сумма комиссии |
| payment.failure_code | integer | Код ошибки из Приложения 1 |
| payment.failure_description | string | Описание ошибки |
| payment.testmode | integer | Признак тестового платежа 1 - тестовый, 0 -боевой |
| payment.created_at | string | Дата создания платежа. Формат "Y-m-d H:i:s" часовой пояс Asia/Almaty |
| payment.compeleted_at | string | Дата проведения платежа. Формат "Y-m-d H:i:s" часовой пояс Asia/Almaty |
Возврат платежа после оплаты
POST https://api.asiapay.kz/v2/payment/refund
POST https://apitest.asiapay.kz/v2/payment/refund
Возврат платежа после оплаты
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/refund' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 123456,
"reason": "Тестовый возврат",
"amount": 10
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2020-01-01 09:00:00",
"payment": {
"id": 654321,
"status": "success",
"testmode": 2
}
}
Возврат платежа после оплаты (ошибка)
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/refund' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 123456,
"reason": "Тестовый возврат",
"amount": 10
}'
Ответ
{
"status": "error",
"code": 2021,
"dt": "2020-01-01 09:00:00",
"message": "Ошибка при получение ответа от биллинга"
}
Метод может быть использован для возврата средств клиенту на баланс в том случае, если платеж в Успехе у мерчанта, то есть до этого он был полностью проведен. Все операторы поддерживают частичный возврат. (Kcell/Activ, Beeline, Tele2/Altel)
Примечание:
При частичном возврате (части от суммы платежа) комиссия, начисленная сверху не возвращается. Только при возврате полной суммы платежа, верхняя комиссия автоматически вернется. У оператора Beeline возврат можно сделать только 1 раз (или полный или частичный). У операторов Tele2/Altel И Kcell/Activ частичный возврат можно инициировать несколько раз до возврата полной суммы платежа.
К примеру, платеж был на 1000тг с верхней комиссией 300тг. Сделали возврат 500тг (Абоненту вернулось только 500тг). Далее делаем еще 1 возврат на 500тг и абоненту также возвращается верхняя комиссия (Т.е. абоненту вернется 800тг)
В случае получения ошибки с кодом 2010, 2021 повторите запрос позднее.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
| reason | string | Да | Причина отмены |
| amount | number | Нет | Сумма возврата в тенге. По умолчанию сумма заказа |
| result_url | string | Нет | URL для отправки сообщения о выполнении операции. Методом POST (пункт 4.12) |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID возвратного платежа |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.testmode | integer | Признак тестового заказа. 0 - боевой, иначе тестовый (см. приложение) |
| message | string | Описание в случае ошибки |
Отмена платежа до оплаты
POST https://api.asiapay.kz/v2/payment/cancel
POST https://apitest.asiapay.kz/v2/payment/cancel
Отмена платежа до оплаты
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/cancel' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 123456,
"reason": "Ошибка приема денег"
}'
Ответ
{
"status": "ok",
"dt": "2020-01-01 09:00:00",
"code": 1000
}
Ошибка при попытке отмены
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/cancel' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 123456,
"reason": "Ошибка приема денег"
}'
Ответ
{
"status": "error",
"code": 2010,
"dt": "2020-01-01 09:00:00",
"message": "Нет ответа от Биллинга оператора"
}
Метод используется для отмены платежа, услуга по которому еще не была оказана.
Примечание
В случае получения ошибки с кодом 2010, 2021 повторите запрос позднее.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
| reason | string | Да | Причина отмены |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| message | string | Описание в случае ошибки |
Получение чека
POST https://api.asiapay.kz/v2/payment/receipt
POST https://apitest.asiapay.kz/v2/payment/receipt
Получение чека
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/receipt' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": "12345678",
"language": "ru"
}'
Ответ
{
"code": 1000,
"dt": "2021-12-27 11:03:32",
"receipt": {
"payment": {
"abonent": "7700 100 20 30",
"agent": "ТОО \"Мобайл С\"",
"bill_amount": "1234.00",
"check_number": 1234,
"commission_amount": "0.00",
"completed_at": "27.12.2021 16:56",
"em_operator": "ТОО «AsiaPay»",
"issuer": "АО «Народный банк Казахстана»",
"issuer_bin": "940140000385",
"operation_id": 12345678,
"operation_outer_id": "b960d044-9c08-4f27-bd4a-fb0ef8a84734",
"recipient": "7700 100 20 30",
"service": "ООО Фортуна",
"support_service_phone": "+7 (727) 344 11 62",
"total_amount": "1234.00",
"transaction_description": "Услуги сервиса",
"transaction_type": "forward",
"transaction_type_human": "Оплата услуг"
},
"url": "https://paycheck.asiapay.kz/?77001002030?12345678"
},
"status": "ok"
}
Метод используется для получения полей для генерации чека на стороне мерчанта. Так же содержит ссылку на чек на сайте Asiapay.kz.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
| language | string | Нет | Язык ответа. Возможные значения ru, kz, en |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| receipt.payment | object | Объект содержит поля для формирования чека |
| receipt.payment.service | string | Название услуги |
| receipt.payment.agent | string | Название магазина |
| receipt.payment.transaction_description | string | Реквизит платежа |
| receipt.payment.transaction_type | string | Тип платежа |
| receipt.payment.transaction_type_human | string | Описание типа платежа |
| receipt.payment.operation_id | integer | № операции |
| receipt.payment.operation_outer_id | integer | № внешней операции |
| receipt.payment.check_number | integer | Номер чека |
| receipt.payment.abonent | string | Плательщик |
| receipt.payment.bill_amount | string | Сумма |
| receipt.payment.commission_amount | string | Комиссия |
| receipt.payment.total_amount | string | Итого |
| receipt.payment.completed_at | string | Дата/Время завершения операции |
| receipt.payment.issuer | string | Эмитент |
| receipt.payment.issuer_bin | string | БИН Эмитента |
| receipt.payment.em_operator | string | Оператор ЭД |
| receipt.payment.support_service_phone | string | Телефон техподдержки |
| receipt.url | string | Ссылка страницу просмотра и скачивания чека |
Получение чека без авторизации
POST https://api.asiapay.kz/v2/payment/receipt_by_phone
POST https://apitest.asiapay.kz/v2/payment/receipt_by_phone
Получение чека без авторизации
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/receipt_by_phone' \
--data-raw '{
"id": "12345678",
"phone": "77771234567",
"language": "ru"
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2020-01-01 09:00:00",
"receipt": {
"payment": {
"service": "Tele2",
"transaction_description": "Сервис 3",
"operation_id": 12345678,
"check_number": 12345678,
"abonent": "77071234567",
"bill_amount": "10.00",
"commission_amount": "0.00",
"total_amount": "10.00",
"completed_at": "2021-03-18 11:12:03",
"issuer": "АО «Народный банк Казахстана»",
"issuer_bin": "123123123123",
"em_operator": "ТОО «PAYBOX.money»"
},
"url": "https://paycheck.asiapay.kz/?77071234567&12345678"
}
}
Метод используется для получения полей для генерации чека на стороне мерчанта. Так же содержит ссылку на чек на сайте Asiapay.kz. Метод не требует авторизации.
Метод не требует авторизации
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
| phone | integer | Да | Номер телефона абонента. 11 цифр |
| language | string | Нет | Язык ответа. Возможные значения ru, kz, en |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| receipt.payment | object | Объект содержит поля для формирования чека |
| receipt.payment.service | string | Название услуги |
| receipt.payment.transactionDescription | string | Реквизит платежа |
| receipt.payment.operationId | integer | № операции |
| receipt.payment.checkNumber | integer | Номер чека |
| receipt.payment.abonent | string | Плательщик |
| receipt.payment.billAmount | string | Сумма |
| receipt.payment.commissionAmount | string | Комиссия |
| receipt.payment.totalAmount | string | Итого |
| receipt.payment.completedAt | string | Дата/Время завершения операции |
| receipt.payment.issuer | string | Эмитент |
| receipt.payment.issuer_bin | string | БИН Эмитента |
| receipt.payment.em_operator | string | Оператор ЭД |
| receipt.url | string | Ссылка страницу просмотра и скачивания чека |
Запрос текущего баланса Партнера
POST https://api.asiapay.kz/v2/balance
POST https://apitest.asiapay.kz/v2/balance
*Запрос текущего баланса Партнера *
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/balance' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ='
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2023-05-10 11:44:13",
"balance": 10000.58
}
Запрос текущего баланса Партнера (баланс не установлен)
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/balance' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ='
Ответ
{
"status": "error",
"code": 2008,
"dt": "2023-05-10 11:47:54",
"message": "Баланс аккаунта не установлен"
}
Метод может быть использован для просмотра текущего баланса в системе МФС у текущего аккаунта.
Тело запроса пустое.
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| balance | number | Cумма остатка на момент запроса |
Выплаты на баланс
В этом разделе описана механика, когда Asiapay.kz производит выплату на баланс абонента.
Мерчант может использовать этот раздел для прямого подключения со своим сервисом.
V2
Инициализация выплаты
POST https://api.asiapay.kz/v2/payment/init
POST https://apitest.asiapay.kz/v2/payment/init
*Инициализация платежа *
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/init' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"phone": "77071234567",
"order_id": "123123abc",
"amount": 10,
"type": "refill",
"description": "Тестовая выплата 1234",
"terminal_code": "code",
"source": "online",
"language": "ru",
"result_url": "",
"testmode": 0
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2020-01-01 09:00:00",
"payment": {
"id": 123456,
"status": "process",
"amount": 10,
"commission_amount": 110,
"testmode": 2
},
"confirm_inputs": [
{
"name": "Смс код",
"value": "otp"
}
]
}
Метод используется для создания выплаты, но не проведения её. При инициализации выплаты мерчант должен передать тип refill в поле type.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| phone | integer | Да | Номер мобильного телефонатолько цифры, формат - 7ххххххххххдлина 11 77079093028 |
| amount | number | Да | Сумма заказа 1000.55 в тенге |
| description | string | Да | Описание заказа. Максимум 255 |
| type | string | Да | Тип: refill |
| terminal_code | string | Нет | Код терминала. |
| source | string | Нет | Канал поступления платежа. Максимум 50 символов. |
| order_id | string | Нет | Номер заказа в системе Партнера |
| language | string | Нет | Язык сообщений. Возможные значения ru, kz, en |
| testmode | integer | Нет | Признак тестового заказа. 0 - боевой, иначе тестовый (см. приложение) |
| result_url | string | Нет | URL для отправки сообщения о выполнении операции. Методом POST (пункт 4.12) |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.amount | float | Сумма платежа |
| payment.commission_amount | float | Сумма комиссии |
| payment.testmode | integer | Признак тестового заказа. 0 - боевой, иначе тестовый (см. приложение) |
| confirm_inputs | array | Массив содержит список объектов с полями, которые требуется отправить в подтверждении платежа (пункт 4.6) |
| confirm_inputs.name | string | Название поля для отображения пользователю |
| confirm_inputs.value | string | Название поля для отправки в методе подтверждения |
Путь прохождения инициализации
Отправка OTP кода
POST https://api.asiapay.kz/v2/payment/otp/resend
POST https://apitest.asiapay.kz/v2/payment/otp/resend
Отправка OTP кода
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/otp/resend' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 123456
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2020-01-01 09:00:00"
}
Метод используется для отправки OTP кода.
Варианты использования:
- Повторный запрос OTP, если истек срок действия предыдущего OTP.
- В случае инициализации платежа через метод
payment/init, если получили в ответе информацию о требуемом подтверждении платежа.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
Подтверждение выплаты
POST https://api.asiapay.kz/v2/payment/confirm
POST https://apitest.asiapay.kz/v2/payment/confirm
Подтверждение платежа
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/confirm' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 123456,
"confirm_inputs": {
"otp": "123456"
}
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2020-01-01 09:00:00",
"payment": {
"id": 123456,
"status": "success",
"receipt_url": "https://paycheck.asiapay.kz/?77071234567&12345",
"amount": 1000,
"commission_amount": 110,
"testmode": 2
}
}
В случаем если на payment/init не были запрошены данные для подтверждения, ключ confirm_inputs передавать не нужно.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
| confirm_inputs | object | Нет | Объект содержит поля, которые требуется передать для подтверждения платежа. Должен содержать как минимум один ключ и значение. Передается только в том случае, если были запрошены поля подтверждения |
| otp | string | Нет | OTP код, если был запрошен |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.receipt_url | string | Ссылка страницу просмотра и скачивания чека |
| payment.amount | float | Сумма платежа |
| payment.commission_amount | float | Сумма комиссии |
| payment.testmode | integer | Признак тестового заказа. 0 - боевой, иначе тестовый (см. приложение) |
Получение статуса
POST https://api.asiapay.kz/v2/payment/status
POST https://apitest.asiapay.kz/v2/payment/status
Получение статуса
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/payment/status' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 123456
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2020-01-01 09:00:00",
"payment": {
"id": 123456,
"first_payment_id": 123455,
"type": "refill",
"status": "error",
"order_id": "2132-5162-123543",
"description": "Тестовый заказ #1",
"amount": 1000,
"commission_amount": 110,
"failure_code": 404,
"failure_description": "Client error",
"testmode": 1,
"created_at": "2020-08-27 09:00:28",
"completed_at": "2020-08-27 09:00:28"
}
}
Метод позволяет получить текущий статус платежа.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.first_payment_id | integer | ID первого платежа (используется в возвратных платежей) |
| payment.type | string | Тип платежа из таблицы 1 |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.order_id | string | ID платежа в системе Партнера |
| payment.description | string | Описание платежа |
| payment.amount | float | Сумма платежа |
| payment.commission_amount | float | Сумма комиссии |
| payment.failure_code | integer | Код ошибки из Приложения 1 |
| payment.failure_description | string | Описание ошибки |
| payment.testmode | integer | Признак тестового платежа 1 - тестовый, 0 -боевой |
| payment.created_at | string | Дата создания платежа. Формат "Y-m-d H:i:s" часовой пояс Asia/Almaty |
| payment.compeleted_at | string | Дата проведения платежа. Формат "Y-m-d H:i:s" часовой пояс Asia/Almaty |
Запрос текущего баланса Партнера
POST https://api.asiapay.kz/v2/balance
POST https://apitest.asiapay.kz/v2/balance
*Запрос текущего баланса Партнера *
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/balance' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ='
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2023-05-10 11:44:13",
"balance": 10000.58
}
Запрос текущего баланса Партнера (баланс не установлен)
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/balance' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ='
Ответ
{
"status": "error",
"code": 2008,
"dt": "2023-05-10 11:47:54",
"message": "Баланс аккаунта не установлен"
}
Метод может быть использован для просмотра текущего баланса в системе МФС у текущего аккаунта.
Тело запроса пустое.
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| balance | number | Cумма остатка на момент запроса |
Оплата услуг
Витрины услуг позволяют оплачивать различные услуги с баланса абонента.
V3
Получение каталога
POST https://api.asiapay.kz/v3/services/catalog
POST https://apitest.asiapay.kz/v3/services/catalog
Получение каталога
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/catalog' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "букмекер",
"language": "ru"
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2021-08-18 14:32:30",
"catalogs": [
{
"id": 1,
"parent_id": null,
"name": "Ставки на спорт"
},
{
"id": 2,
"parent_id": null,
"name": "Букмекерские конторы"
}
],
"services": [
{
"id": 1,
"catalogs": [
1,
2
],
"name": "Ставки онлайн",
"description": "Ставки на все виды спортивных мероприятий",
"icon": "https://api.asiapay.kz/path/to/image.png"
}
]
}
Метод возвращает все доступные для отображения клиенту категории и сервисы.
Если в запросе передать дополнительный параметр name (например: "ставки" или "букмекер"), то только подходящие под этот параметр услуги будут переданы в ответе.
Поиск производится как по названию услуг, так и по алиасам (псевдонимам) услуг витрины для текущего мерчанта.
Таким образом, если для текущего мерчанта для услуги "Цветы и букеты" был задан алиас "Праздник", то данная услуга будет возвращена в ответе при передаче name = (цветы|букет|праздник).
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| language | string | Нет | Язык (en, kz, ru) |
| name | string | Нет | Строка для поиска по названию услуги или по алиасу для текущего мерчанта |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| catalogs | array | Массив с категориями каталога |
| catalogs.*.id | integer | ID категории в каталоге |
| catalogs.*.parent_id | integer | ID родительской категории в каталоге |
| catalogs.*.name | string | Название категории |
| services | array | Массив доступных сервисов |
| services.*.id | integer | ID сервиса |
| services.*.catalogs | array | Массив ID категорий, к которым относится сервис |
| services.*.name | string | Название сервиса |
| services.*.description | string | Описание сервиса |
| services.*.icon | string | Путь до изображения для отображения в каталоге |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Получение информации о сервисе
POST https://api.asiapay.kz/v3/services/info
POST https://apitest.asiapay.kz/v3/services/info
Получение информации о сервисе
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/info' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_id": 1,
"language": "ru"
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2021-08-19 12:55:51",
"service": {
"id": 1,
"catalogs": [
{
"id": 1,
"name": "Ставки на спорт"
},
{
"id": 2,
"name": "Букмекерские конторы"
}
],
"name": "Ставки онлайн",
"description": "Ставки на все виды спортивных мероприятий",
"icon": "https://api.asiapay.kz/path/to/image.png",
"inputs": [
{
"field": "identity",
"name": "Логин",
"label": "Ваша учётная запись",
"type": "digits",
"mask": "\\d+"
}
],
"limits": {
"min": 1000,
"max": 50000
},
"commissions": [
{
"operator": "tele2",
"fixed": "50.0000",
"percent": "2.0000",
"min": "0.0000"
}
]
}
}
Получение информации о сервисе
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/info' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_id": 75,
"language": "ru",
"amount": 1000,
"phone": "77781234567"
}'
Ответ
{
"code": 1000,
"dt": "2023-04-26 09:24:14",
"service": {
"catalogs": [
{
"id": 7,
"name": "Объявления"
}
],
"commissions": [
{
"amount": 20,
"calc": "percent",
"fixed": 0,
"min": 10,
"operator": "activ",
"percent": 2
}
],
"description": "",
"icon": "https://static.asiapay.kz/storage/services/logos/75/cZeSe7m7Uz0RAnFAat879pHaMG7K25tAfdLfHNGx.svg",
"id": 75,
"inputs": [
{
"field": "identity",
"label": "",
"mask": "",
"name": "Пополнение аккаунта:",
"type": null
}
],
"limits": {
"max": 50000,
"min": 10
},
"name": "Крыша",
"promotions": [
{
"max": 100,
"operator": "activ",
"percent": 1,
"type": "bonus",
"value": 10
}
]
},
"status": "ok"
}
Метод возвращает информацию о сервисе, включая комиссии, лимиты и поля, которые требуется заполнить.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| service_id | integer | Да | ID сервиса |
| language | string | Нет | Язык (en, kz, ru) |
| amount | number | Нет | Сумма платежа |
| phone | string | Нет | Номер телефона абонента |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| service | object | Объект, содержащий информацию о сервисе |
| service.id | integer | ID сервиса |
| service.catalogs | array | Массив категорий, к которым относится сервис |
| service.catalogs.*.id | integer | ID категории |
| service.catalogs.*.name | string | Название категории |
| service.name | string | Название сервиса |
| service.description | string | Описание сервиса |
| service.icon | string | Путь до изображения для отображения в каталоге |
| service.inputs | array | Массив объектов, содержащих данные о полях, которые требуется заполнить клиенту |
| service.inputs.*.field | string | Имя поля для отправки при проведении платежа |
| service.inputs.*.name | string | Название поля для отображения пользователю |
| service.inputs.*.label | string | Описание поля для отображения пользователю |
| service.inputs.*.type | string | Тип поля для заполнения (phone, email, digits или null) |
| service.inputs.*.mask | string | Применяемая маска для валидации (null, phone, money, otp или регулярное выражение) |
| service.limits | object | Объект, содержащий информацию о лимитах на одну операцию |
| service.limits.min | integer | Минимальная сумма |
| service.limits.max | integer | Максимальная сумма |
| service.commissions | array | Массив объектов, содержащих информацию о комиссиях в зависимости от мобильного оператора |
| service.commissions.*.operator | string | Код мобильного оператора (tele2, altel, kcell, activ, beeline) |
| service.commissions.*.fixed | number | Фиксированная комиссия |
| service.commissions.*.percent | number | Комиссия в процентах |
| service.commissions.*.min | number | Минимальная комиссия |
| service.commissions.*.amount | number | Сумма комиссии |
| service.promotions | array | Массив объектов, содержащих информацию о бонусах/кэшбеках в зависимости от мобильного оператора |
| service.promotions.*.operator | string | Код мобильного оператора (tele2, altel, kcell, activ, beeline) |
| service.promotions.*.type | string | Тип (bonus, cashback) |
| service.promotions.*.percent | number | Процент бонуса/кэшбека |
| service.promotions.*.max | number | Максимальная сумма бонуса/кэшбека |
| service.promotions.*.value | number | Сумма бонуса/кэшбека |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Валидация данных платежа
POST https://api.asiapay.kz/v3/services/validate_payment
POST https://apitest.asiapay.kz/v3/services/validate_payment
Валидация данных платежа - запрос с ошибкой
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/validate_payment' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_id": 1,
"inputs": {
"another-field": "1234567890"
},
"phone": "77070000000",
"language": "ru"
}'
Ответ
{
"status": "error",
"code": 603,
"errors": {
"inputs.identity": [
"Поле inputs.identity обязательно для заполнения."
],
"amount": [
"Поле amount обязательно для заполнения."
]
}
}
Валидация данных платежа - успешный запрос
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/validate_payment' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_id": 1,
"inputs": {
"identity": "1234567890"
},
"phone": "77070000000",
"amount": 1000,
"language": "ru"
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2021-08-19 12:51:59",
"commissions": [
{
"operator": "tele2",
"fixed": "50.0000",
"percent": "2.0000",
"min": "0.0000"
}
]
}
Метод позволяет проверить валидность данных, которые ввел пользователь для оплаты услуг сервиса. Например номер телефона или логин в сервисе.
Рекомендуется вызывать этот метод всегда перед отправкой проведения платежа.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| service_id | integer | Да | ID сервиса |
| inputs | object | Да | Объект содержит все поля field, которые были перечислены в информации о сервисе |
| phone | string | Да | Номер телефона абонента |
| amount | integer | Да | Сумма платежа |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| commission | array | Информация о комиссии для текущего номера телефона по оператору |
| commission.operator | string | Код мобильного оператора (tele2, altel, kcell, activ, beeline) |
| commission.fixed | integer | Фиксированная комиссия |
| commission.percent | integer | Комиссия в процентах |
| commission.min | integer | Минимальная комиссия |
| errors | object | Информация об ошибках, в случае их возникновения |
| errors.* | array | Массив ошибок по указанному в ключе полю |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Проведение платежа
POST https://api.asiapay.kz/v3/services/pay
POST https://apitest.asiapay.kz/v3/services/pay
Проведение платежа - требуется подтверждение
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/pay' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_id": 1,
"inputs": {
"identity": "1234567890"
},
"phone": "77070000000",
"amount": 1000,
"source": "online",
"language": "ru"
}'
Ответ
{
"status": "need_approve",
"code": 1000,
"dt": "2021-08-19 13:24:35",
"payment": {
"id": 3181,
"status": "approve",
"amount": "1000.0000",
"commission_amount": "0.0000"
},
"confirm_inputs": {
"name": "SMS code",
"value": "otp"
}
}
Проведение платежа - успешный запрос
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/pay' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_id": 1,
"inputs": {
"identity": "1234567890"
},
"phone": "77070000000",
"amount": 1000,
"source": "online",
"language": "ru"
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2021-08-19 13:28:08",
"payment": {
"id": 3184,
"status": "complete",
"amount": "1000.0000",
"commission_amount": "0.0000",
"receipt_url": "https://paycheck.asiapay.kz/?77070000000&3184"
}
}
Проведение платежа - запрос с ошибкой
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/pay' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_id": 1,
"inputs": {
"identity": "1234567890"
},
"phone": "77090000000",
"amount": 1000,
"source": "online",
"language": "ru"
}'
Ответ
{
"status": "error",
"code": 603,
"errors": {
"phone": [
"Невозможно совершить перевод с данного номера телефона. Пожалуйста, попробуйте позже."
]
}
}
Проведение платежа может быть осуществлено как в один, так и в два этапа. Это зависит от настроек терминала для текущего мерчанта.
Если после первого запроса вы получили статус need_approve, требуется запросить у клиента заполнения полей, указанных в блоке confirm_inputs и вызвать метод подтверждения платежа используя эти поля.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| service_id | integer | Да | ID сервиса |
| amount | integer | Да | Сумма платежа |
| phone | string | Да | Номер телефона абонента |
| inputs | object | Да | Объект содержит все поля field, которые были перечислены в информации о сервисе |
| source | string | Нет | Канал поступления платежа. Максимум 50 символов. |
| language | string | Нет | Язык сообщений. Возможные значения ru, kz, en |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment | object | Объект содержит информацию о платеже |
| payment.id | integer | ID платежа в системе МФС |
| payment.amount | integer | Сумма |
| payment.commission_amount | float | Сумма комиссии, которая была применена к платежу |
| payment.status | string | Статус платежа из таблицы 3 |
| payment.receipt_url | string | Ссылка на страницу просмотра чека |
| confirm_inputs | array | Массив содержит список полей для подтверждения платежа клиентов |
| confirm_inputs.name | string | Название поля для отображения клиенту |
| confirm_inputs.value | string | Название поля для отправки методом подтверждения платежа |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Проведение платежа картой
POST https://api.asiapay.kz/v3/services/pay-card
POST https://apitest.asiapay.kz/v3/services/pay-card
Проведение платежа картой
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/pay-card' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_id": 1,
"inputs": {
"identity": "1234567890"
},
"amount": 100,
"order_id": "983439f7-48cb-4322-b335-ca6571e726df",
"user_id": "3a8f4a4f-30d2-4b6e-92d2-e33bd9308740",
"source": "online",
"result_url": "https://site.com/callback-url",
"success_url": "https://site.com/success.html",
"failure_url": "https://site.com/failure.html"
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2023-06-08 14:10:19",
"payment": {
"id": 6777,
"amount": 100,
"commission_amount": 0,
"url": "https://customer.paybox.money/v1/merchant/550027/card/payment?pg_payment_id=bd1e8b6a391e28451c3243d017243d90"
}
}
Проведение платежа картой (ошибка)
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/pay-card' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"service_id": 1,
"inputs": {
"identity": "1234567890"
},
"amount": 100,
"order_id": "983439f7-48cb-4322-b335-ca6571e726df",
"user_id": "3a8f4a4f-30d2-4b6e-92d2-e33bd9308740",
"source": "online",
"result_url": "https://site.com/callback-url",
"success_url": "https://site.com/success.html",
"failure_url": "https://site.com/failure.html"
}'
Ответ
{
"status": "error",
"code": 2021,
"dt": "2023-06-08 14:57:42",
"message": "Ошибка при получение ответа от биллинга"
}
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| service_id | integer | Да | ID сервиса |
| amount | integer | Да | Сумма платежа |
| inputs | object | Да | Объект содержит все поля field, которые были перечислены в информации о сервисе |
| inputs.identity | string | Да | Логин, учетная запись в системе сервиса |
| order_id | string | Нет | Идентификатор платежа в системе Партнера. Рекомендуется поддерживать уникальность этого поля. Максимум 50 символов. |
| user_id | string | Нет | ID пользователя в системе Партнера. Максимум 50 символов. |
| source | string | Нет | Канал поступления платежа. Максимум 50 символов. |
| result_url | string | Нет | URL Партнера для уведомления о результате оплаты. См Прочее/Post back. Максимум 100 символов. |
| success_url | string | Нет | URL Партнера, на который перенаправляется пользователь после успешной оплаты. Максимум 100 символов. |
| failure_url | string | Нет | URL Партнера, на который перенаправляется пользователь после не успешной оплаты. Максимум 100 символов. |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment | object | Объект содержит информацию о платеже |
| payment.id | integer | ID платежа в системе МФС |
| payment.amount | number | Сумма |
| payment.commission_amount | number | Сумма комиссии, которая была применена к платежу |
| payment.url | string | URL для перенаправления пользователя на фрейм оплаты |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Подтверждение платежа
POST https://api.asiapay.kz/v3/services/confirm
POST https://apitest.asiapay.kz/v3/services/confirm
Подтверждение платежа - запрос с ошибкой
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/confirm' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": 3196,
"confirm_inputs": {
"otp": "123456"
},
"language": "ru"
}'
Ответ
{
"status": "error",
"code": 603,
"errors": {
"confirm_inputs.otp": [
"Неверный проверочный код"
]
}
}
Подтверждение платежа - успешный запрос
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/confirm' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": 3196,
"confirm_inputs": {
"otp": "123456"
},
"language": "ru"
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2021-08-19 14:15:29",
"payment": {
"id": 3196,
"status": "complete",
"amount": "1000.0000",
"commission_amount": "0.0000",
"receipt_url": "https://paycheck.asiapay.kz/?77070000000&3196"
}
}
Метод используется в том случае, если при вызове services/pay была запрошена подтверждающая информация.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
| confirm_inputs | object | Нет | Объект содержит поля, которые требуется передать для подтверждения платежа. Должен содержать как минимум один ключ и значение. Передается только в том случае, если были запрошены поля подтверждения |
| otp | string | Да | OTP код, если был запрошен |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.amount | float | Сумма платежа |
| payment.commission_amount | float | Сумма комиссии |
| payment.receipt_url | string | Ссылка страницу просмотра и скачивания чека |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Повторная отправка OTP
POST https://api.asiapay.kz/v3/services/otp
POST https://apitest.asiapay.kz/v3/services/otp
Повторная отправка OTP
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/otp/resend' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": 3199,
"language": "ru"
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2021-08-19 14:20:06"
}
Метод используется для повторной отправки OTP кода.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Проверка статуса платежа
POST https://api.asiapay.kz/v3/services/status
POST https://apitest.asiapay.kz/v3/services/status
Проверка статуса платежа
Запрос
curl --location --request POST 'https://api.asiapay.kz/v3/services/status' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": 3202,
"language": "ru"
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2021-08-19 14:21:34",
"payment": {
"id": 3202,
"status": "success",
"amount": "1000.0000",
"commission_amount": "0.0000",
"failure_code": null,
"failure_description": null,
"testmode": 0,
"created_at": "2021-08-19 14:21:03",
"compeleted_at": "2021-08-19 14:21:21"
}
}
Метод позволяет получить текущий статус платежа.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.amount | float | Сумма платежа |
| payment.commission_amount | float | Сумма комиссии |
| payment.failure_code | integer | Код ошибки из Приложения 1 |
| payment.failure_description | string | Описание ошибки |
| payment.testmode | integer | Признак тестового платежа 1 - тестовый, 0 -боевой |
| payment.created_at | string | Дата создания платежа. Формат "Y-m-d H:i:s" часовой пояс Asia/Almaty |
| payment.compeleted_at | string | Дата проведения платежа. Формат "Y-m-d H:i:s" часовой пояс Asia/Almaty |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Получение ссылки на фрейм витрины
POST https://money.asiapay.kz/api/v1/token/generate
POST https://money.asiapay.kz/api/v1/token/generate
Получение ссылки на фрейм витрины
Запрос
curl --location --request POST 'https://money.asiapay.kz/api/v1/token/generate' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic e3tzbHVnfX06e3tzZWNyZXRfa2V5fX0=' \
--data-raw '{
"lifetime": 86400,
"testmode": 0,
"language": "ru",
"gtm": "GTM-ABC1D23",
"source": "shop.example.com"
}'
Ответ
{
"url": "https://money.asiapay.kz/frame?token={TOKEN}",
"token": "{TOKEN}",
"expire_at": "2022-07-29 11:40:22"
}
Метод позволяет получить ссылку на iframe витрины услуг.
Далее мерчант на своей стороне интегрирует данный iframe на свою страницу.
Авторизация происходит по Basic Auth.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| lifetime | integer | Нет | Время жизни в секундах, либо 0 |
| testmode | integer | Нет | Тестовый режим * |
| language | string | Нет | Язык (en, kz, ru) |
| gtm | string | Нет | Идентификатор Google Tag Manager для аналитики |
| source | string | Нет | Источник (до 50 символов) |
* Стоит обратить внимание, что тестовый режим работает аналогично тестовым режимам в других методах: боевой мерчант может проводить как боевые, так и тестовые платежи, но тестовый мерчант может проводить только тестовые платежи.
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| url | string | Ссылка на iframe |
| token | string | Токен для фрейма |
| expire_at | datetime | Дата и время истечения срока действия фрейма в UTC |
// Пример реализации подстраивания под высоту фрейма
window.addEventListener("message", (event) => {
if (
event.data.action === "update_frame_height" &&
event.data.status === "success"
) {
const height = JSON.parse(event.data.data);
const footerHeight = this.$refs.footer.$el.clientHeight;
const headerHeight = this.$refs.header.$el.clientHeight;
const minHeight = `calc(100vh - ${headerHeight}px - ${footerHeight}px)`;
this.$refs.iframe.style.minHeight = minHeight;
this.$refs.iframe.style.height = height.docHeight + "px";
}
})
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Переводы
V2
SIM to SIM
Превалидация платежа
POST https://api.asiapay.kz/v2/transfer/info
POST https://apitest.asiapay.kz/v2/transfer/info
Предвалидация платежа
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/info' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"phone": "77071234567",
"recipient": "77077654321",
"order_id": "123456",
"amount": 2000,
"description": "Перевод с баланса на баланс",
"source": "online",
"testmode": 0,
"language": "ru"
}'
Ответ
{
"operator": "beeline",
"operator_for_pay": null,
"commission": {
"calc": "percent",
"percent": "2.0000",
"minimum": "0.0000",
"fixed": "50.0000",
"amount": 40,
"text": "Комиссия 2%",
"total": 2040
},
"min_amount": 1,
"max_amount": 50000,
"status": "ok",
"code": 1000,
"dt": "2021-09-27 11:26:54"
}
Метод позволяет проверить корректость заполненных данных, а также получить информацию о комиссии по переводу.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| phone | integer | Да | Номер мобильного телефона только цифры, формат - 7хххххххххх длина 11 |
| amount | integer | Да | Сумма платежа |
| recipient | string | Да | При переводе на "sim" |
| description | string | Да | Описание заказа. Максимум 255 |
| order_id | string | Нет | Номер заказа в системе Партнера |
| source | string | Нет | Источник поступления платежа. Должен быть указан один из трех вариантов: online, terminal, app |
| testmode | boolean | Нет | Признак тестового заказа. 1 - тестовый, иначе боевой |
| language | string | Нет | Язык сообщений. Возможные значения: ru, kz, en. |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| operator | string | Код мобильного оператора указанного номера телефона получателя |
| operator_for_pay | string | null |
| min_amount | float | Минимальная сумма |
| max_amount | float | Максимальная сумма |
| commission | array | Информация о комиссии |
| commission.calc | integer | Расчёт комиссии (фиксированный или процент) |
| commission.percent | float | Процент комиссии |
| commission.minimum | float | Минимальная комиссия |
| commission.fixed | float | Фиксированная комиссия |
| commission.amount | float | Сумма комиссии |
| commission.text | string | Описание комиссии в текстовом виде (Комиссия 2%) |
| commission.total | float | Сумма к списанию с комиссией (2000 + 40 = 2040) |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Инициализация платежа
POST https://api.asiapay.kz/v2/transfer/init
POST https://apitest.asiapay.kz/v2/transfer/init
Инициализация платежа
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/init' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"phone": "77071234567",
"order_id": "123456",
"amount": 10000,
"recipient": "77077654321",
"description": "Тестовая выплата на SIM",
"source": "online",
"testmode": 1,
"language": "ru"
}'
Ответ
{
"payment": {
"id": 3231,
"status": "process",
"amount": 10000,
"commission_amount": 0
},
"confirm_inputs": [
{
"name": "Смс код",
"value": "otp"
}
],
"status": "ok",
"code": 1000,
"dt": "2021-08-23 10:39:57"
}
Метод позволяет инициировать платеж. Возвращает данные о комиссии и информацию о подтверждении платежа.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| phone | integer | Да | Номер мобильного телефонатолько цифры, формат - 7хххххххххх длина 11 |
| amount | integer | Да | Сумма для перевода, доступная на балансе |
| recipient | string | Да | Необходимо указать номер телефона для пополнения |
| description | string | Да | Описание заказа. Максимум 255 |
| order_id | string | Нет | Номер заказа в системе Партнера |
| source | string | Нет | Источник поступления платежа. Должен быть указан один из трех вариантов: online, terminal, app |
| testmode | boolean | Нет | Признак тестового заказа. 1 - тестовый, иначе боевой |
| language | string | Нет | Язык сообщений. Возможные значения: ru, kz, en. |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.amount | integer | Сумма выплаты |
| payment.commission_amount | float | Сумма комисии |
| confirm_inputs | array | Массив содержит список объектов с полями, которые требуется отправить в подтверждении платежа (пункт 4.6) |
| confirm_inputs.name | string | Название поля для отображения пользователю |
| confirm_inputs.value | string | Название поля для отправки в методе подтверждения |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Подтверждение выплаты
POST https://api.asiapay.kz/v2/transfer/confirm
POST https://apitest.asiapay.kz/v2/transfer/confirm
Подтверждение выплаты
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/confirm' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 3223,
"language": "ru",
"confirm_inputs": {
"otp": "299605"
}
}'
Ответ
{
"payment": {
"id": 3224,
"first_payment_id": 3223,
"type": "trans_sim2sim",
"status": "process",
"amount": 2000,
"commission_amount": 0
},
"status": "ok",
"code": 1000,
"dt": "2021-08-20 11:21:10"
}
Метод подтверждения платежа. В случае если при инициализации были запрошены поля для подтверждения, требуется заполнить параметр confirm_inputs.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
| confirm_inputs | object | Нет | Объект содержит поля, которые требуется передать для подтверждения платежа. Должен содержать как минимум один ключ и значение. |
| confirm_inputs.otp | string | Нет | OTP код, если был запрошен |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.receipt_url | string | Ссылка страницу просмотра и скачивания чека |
| payment.amount | float | Сумма выплаты |
| payment.commission_amount | float | Сумма комиссии |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Отправка OTP кода
POST https://api.asiapay.kz/v2/transfer/otp/resend
POST https://apitest.asiapay.kz/v2/transfer/otp/resend
Отправка OTP кода
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/otp/resend' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 3223,
"language": "ru"
}'
Ответ
{
"status": "ok",
"code": 1000,
"dt": "2021-08-20 11:10:50"
}
Метод должен быть вызван в том случае, если при инициализации вернулся ответ с запросом подтверждения через OTP или если предыдущий OTP код устарел.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Получение статуса
POST https://api.asiapay.kz/v2/transfer/status
POST https://apitest.asiapay.kz/v2/transfer/status
Подтверждение выплаты
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/status' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWVyY2hhbnQ6cGFzc3dvcmQ=' \
--data-raw '{
"id": 3223,
"language": "ru"
}'
Ответ
{
"payment": {
"id": 3224,
"first_payment_id": 3223,
"type": "trans_sim2sim",
"status": "complete",
"order_id": "123456",
"description": "Тестовый перевод sim to sim",
"amount": 2000,
"testmode": 1,
"created_at": "2021-08-20 11:20:17",
"compeleted_at": "2021-08-20 11:23:24",
"receipt_url": "https://paycheck.asiapay.kz/?77071234567&3223"
},
"status": "ok",
"code": 1000,
"dt": "2021-08-20 11:21:52"
}
Метод позволяет проверить статус платежа.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения операции из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | ID платежа |
| payment.first_payment_id | integer | ID первого платежа (используется в возвратных платежей) |
| payment.type | string | Тип платежа из таблицы 4 |
| payment.status | string | Статус платежа из Таблицы 3 |
| payment.order_id | string | ID платежа в системе Партнера |
| payment.description | string | Описание платежа |
| payment.amount | float | Сумма платежа |
| payment.commission_amount | float | Сумма комиссии |
| payment.failure_code | integer | Код ошибки из Приложения 1 |
| payment.failure_description | string | Описание ошибки |
| payment.testomode | integer | Признак тестового платежа 1 - тестовый, 0 -боевой |
| payment.created_at | string | Дата создания платежа. Формат "Y-m-d H:i:s" часовой пояс Asia/Almaty |
| payment.completed_at | string | Дата проведения платежа. Формат "Y-m-d H:i:s" часовой пояс Asia/Almaty |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
CARD to SIM (JS SDK)
Перевод средств с карты на баланс мобильного номера телефона осуществляется путём вызова соответствующего фрейма для заполнения данных карты плательщика с передачей номера телефона получателя и суммы для пополнения.
После успешного списания средств с карты плательщика происходит пополнение баланса телефона.
О результате перевода средств система уведомляет мерчанта путём вызова соответствующего URL (success, failure).
Предвалидация данных
POST https://api.asiapay.kz/v2/transfer/card2sim2/info
POST https://apitest.asiapay.kz/v2/transfer/card2sim2/info
Предвалидация данных - успех
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/card2sim2/info' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"phone": "77071234567",
"amount": 100,
"language": "ru"
}'
Ответ
{
"code": 1000,
"commission": {
"amount": 5,
"calc": 0,
"fixed": 0,
"minimum": 0,
"percent": 5,
"text": "Комиссия 5% от суммы",
"total": 105
},
"dt": "2023-02-27 05:58:07",
"max_amount": 50000,
"min_amount": 0,
"operator": "activ",
"status": "ok"
}
Предвалидация данных - ошибка
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/card2sim2/info' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"phone": "77071234567",
"amount": 100,
"language": "ru"
}'
Ответ
{
"dt": "2023-02-27 05:58:46",
"errors": {
"phone": [
"Пополнение данного номера невозможно: не найден терминал для списания"
]
},
"message": "Пополнение данного номера невозможно: не найден терминал для списания"
}
Перед проведением перевода с карты на SIM необходимо отправить данные на предварительную валидацию данных. В случае, если данному мерчанту доступен перевод с карты на баланс указанного номера телефона, в ответе на запрос придёт информация о комиссии.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| phone | integer | Да | Номер мобильного телефона, только цифры, формат - 7хххххххххх длина 11 |
| amount | integer | Да | Сумма перевода в KZT |
| language | string | Нет | Язык сообщений. Возможные значения: ru, kz, en. |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| operator | string | Код мобильного оператора указанного номера телефона |
| min_amount | float | Минимальная сумма |
| max_amount | float | Максимальная сумма |
| commission | array | Информация о комиссии |
| commission.calc | integer | Расчёт комиссии (фиксированный или процент) |
| commission.percent | float | Процент комиссии |
| commission.minimum | float | Минимальная комиссия |
| commission.fixed | float | Фиксированная комиссия |
| commission.amount | float | Сумма комиссии |
| commission.text | string | Описание комиссии в текстовом виде (Комиссия 2%) |
| commission.total | float | Сумма списания с комиссией (2000 + 40 = 2040) |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Инициализация платежа
POST https://api.asiapay.kz/v2/transfer/card2sim2/init
POST https://apitest.asiapay.kz/v2/transfer/card2sim2/init
Инициализация платежа
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/card2sim2/init' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"phone": "77770123456",
"amount": 100,
"language": "ru"
}'
Ответ
{
"amount": 100,
"code": 1000,
"dt": "2022-08-22 06:18:35",
"order_id": "f785b6d5-009f-4a93-9ea4-5c1c1ee8e92e",
"phone": "77770123456",
"sdk": {
"key": "2peMFY34TOqXkHHARidYZqwNqRFVXC0R",
"token": "Ei1bo4Q3H6MljDM2QLLYRhvWhk9bgj5h"
},
"status": "ok",
"transaction_id": 1000
}
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| phone | string | Да | Номер мобильного телефона, только цифры, формат - 7хххххххххх длина 11 |
| amount | integer | Да | Сумма перевода в KZT |
| string | Нет | Email, опционально | |
| tel | string | Да | Номер телефона для получения чека, опционально |
| language | string | Нет | Язык сообщений. Возможные значения: ru, kz, en. |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| amount | integer | Сумма перевода |
| order_id | string | Идентификатор заказа |
| phone | string | Номер телефона |
| transaction_id | integer | Идентификатор транзакции |
| sdk | object | Данные для JS SDK (см. документацию https://docs.paybox.money/ru/docs/sdk/js) |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Подтверждение платежа
POST https://api.asiapay.kz/v2/transfer/card2sim2/confirm
POST https://apitest.asiapay.kz/v2/transfer/card2sim2/confirm
Подтверждение платежа
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/card2sim2/confirm' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"transaction_id": 1000,
"order_id": "f785b6d5-009f-4a93-9ea4-5c1c1ee8e92e",
"payment_id": "2000"
}'
Ответ
{
"payment": {
"id": 5000,
"amount": 2000,
"commission_amount": 0,
"testmode": 2
},
"status": "ok",
"code": 1000,
"dt": "2021-09-07 13:45:55"
}
Параметры запроса
Все указанные параметры обязательны
| Параметр | Тип | Описание |
|---|---|---|
| transaction_id | integer | Идентификатор транзакции |
| order_id | string | Номер заказа |
| payment_id | string | Идентификатор на стороне PB |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| url | string | Ссылка на фрейм для вызова для ввода данных карты |
| payment.id | integer | ID платежа |
| payment.testmode | integer | Признак тестового платежа |
| payment.amount | float | Сумма выплаты |
| payment.commission_amount | float | Сумма комиссии |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
SIM to CARD
Перевод средств с баланса мобильного номера телефона на карту осуществляется путём вызова соответствующего фрейма для заполнения данных карты получателя с передачей номера телефона плательщика и суммы для пополнения.
После успешного списания средств с баланса телефона плательщика происходит пополнение карты.
О результате перевода средств система уведомляет мерчанта путём вызова соответствующего URL (success, failure).
Предвалидация данных
POST https://api.asiapay.kz/v2/transfer/sim2cardV2/info
POST https://apitest.asiapay.kz/v2/transfer/sim2cardV2/info
Предвалидация данных - успех
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/sim2cardV2/info' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"phone": "77071234567",
"amount": 1000,
"language": "ru"
}'
Ответ
{
"code": 1000,
"commission": {
"amount": 500,
"calc": 0,
"fixed": 0,
"minimum": 500,
"percent": 4,
"text": "Комиссия 4% от суммы, минимум 500",
"total": 1500
},
"dt": "2023-02-27 05:54:34",
"operator": "tele2",
"status": "ok"
}
Предвалидация данных - ошибка
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/sim2card/info' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"phone": "77601234567",
"amount": 1000,
"email": "example@domain.com",
"order_id": "12356789-xyz",
"description": "Оплата с баланса телефона на карту",
"back_link": "https://my.site/payment/12356789-xyz/back",
"success_callback": "https://api.my.site/payment/12356789-xyz/success",
"failure_callback": "https://api.my.site/payment/12356789-xyz/failure",
"testmode": "0",
"language": "ru"
}'
Ответ
{
"dt": "2023-02-27 05:55:03",
"errors": {
"phone": [
"Операция доступна для абонентов Tele2, Altel"
]
},
"message": "Операция доступна для абонентов Tele2, Altel"
}
Перед проведением перевода с SIM на карту необходимо отправить данные на предварительную валидацию данных. В случае, если данному мерчанту доступен перевод с баланса указанного номера телефона на карту, в ответе на запрос придёт информация о комиссии.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| phone | integer | Да | Номер мобильного телефона, только цифры, формат - 7хххххххххх длина 11 |
| amount | integer | Да | Сумма перевода в KZT |
| language | string | Нет | Язык сообщений. Возможные значения: ru, kz, en. |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| operator | string | Код мобильного оператора указанного номера телефона |
| commission | array | Информация о комиссии |
| commission.calc | integer | Расчёт комиссии (фиксированный или процент) |
| commission.percent | float | Процент комиссии |
| commission.minimum | float | Минимальная комиссия |
| commission.fixed | float | Фиксированная комиссия |
| commission.amount | float | Сумма комиссии |
| commission.text | string | Описание комиссии в текстовом виде (Комиссия 2%) |
| commission.total | float | Сумма списания с комиссией (2000 + 40 = 2040) |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Иницализация выплаты
POST https://api.asiapay.kz/v2/transfer/sim2cardV2/init
POST https://apitest.asiapay.kz/v2/transfer/sim2cardV2/init
Иницализация выплаты
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/sim2cardV2/init' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"phone": "77071234567",
"amount": 1000,
"card_number": "4111111111111111",
"language": "ru"
}'
Ответ
{
"code": 1000,
"confirm_inputs": [
{
"name": "Смс код",
"value": "otp"
}
],
"dt": "2023-02-27 06:04:22",
"id": 196682161,
"status": "ok"
}
Инициализация платежа с баланса номера телефона на карту осуществляется с теми же данными, которые отправляются на предварительную валидацию + номер карты (card_number).
Использование данного метода доступно для систем, прошедших PCI DSS.
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| status | string | Статус выполнения запроса из Таблицы 2 |
| code | integer | Код ответа из Приложения 1 |
| dt | datetime | Дата и время обработки запроса |
| id | integer | Идентификатор платежа на списание с баланса |
| confirm_inputs | array | Массив содержит список объектов с полями, которые требуется отправить в подтверждении платежа (пункт 4.6) |
| confirm_inputs.name | string | Название поля для отображения пользователю |
| confirm_inputs.value | string | Название поля для отправки в методе подтверждения |
После инициализации платежа необходимо вызвать метод отправки OTP-кода (соответствующий метод описан в документации к группе "Переводы / V2 / С SIM").
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Подтверждение платежа
POST https://api.asiapay.kz/v2/transfer/sim2cardV2/confirm
POST https://apitest.asiapay.kz/v2/transfer/sim2cardV2/confirm
Получение ссылки на фрейм
Запрос
curl --location --request POST 'https://api.asiapay.kz/v2/transfer/sim2card/confirm' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
"id": 196683186,
"confirm_inputs": {
"otp": "826081"
},
"language": "ru"
}'
Ответ
{
"dt": "2023-02-27 06:10:16",
"response": {
"message": "Перевод обрабатывается",
"payment": {
"id": 196683296
},
"status": "ok"
}
}
Подтверждение перевода требует ввода OTP-кода. В случае успешного ввода система возвращает ссылку на фрейм для ввода номера карты.
Параметры запроса
| Параметр | Тип / требования | Обязательный | Описание / пример |
|---|---|---|---|
| id | integer | Да | ID платежа в системе МФС |
| confirm_inputs | object | Нет | Объект содержит поля, которые требуется передать для подтверждения платежа. Должен содержать как минимум один ключ и значение. |
| confirm_inputs.otp | string | Нет | OTP код, если был запрошен |
Параметры ответа
| Параметр | Тип | Описание |
|---|---|---|
| response.status | string | Статус выполнения запроса из Таблицы 2 |
| message | string | Сообщение |
| dt | datetime | Дата и время обработки запроса |
| payment.id | integer | Идентификатор платежа |
Headers
| Content-Type | Value |
|---|---|
| Accept | application/json |
Headers
| Content-Type | Value |
|---|---|
| Content-Type | application/json |
Прочее
Post back
URL указанный в параметре result_url будет вызван после проведения платежа или в случае ошибки методом POST, если этот параметр указан. Запрос инициирует МФС. Ожидается получение от сервиса пустого тела ответа и HTTP код 200.
Параметры запроса
| Параметр | Тип / требования | Описание / пример |
|---|---|---|
| order_id | string | ID заказа мерчанта |
| payment_id | integer | ID платежа в системе МФС |
| dt | datetime | Дата и время обработки запроса |
| status | string | Статус платежа, таблица 3 |
| code | integer | Код ответа из Приложения 1 |
| message | string | Описание ответа из Приложения 1 (Поле присутствует только при статусе error) |
Приложение 1. Коды ошибок
Таблица содержит все коды ошибок.
| Код | Описание |
|---|---|
| 601 | Неверный проверочный код |
| 602 | Абонент не может оплатить |
| 603 | (Динамическое описание) |
| 604 | Слишком много попыток проверки |
| 605 | Слишком много попыток отправки sms |
| 607 | Дневной лимит платежей в размере 100 МРП исчерпан |
| 608 | Неверный статус транзакции для OTP-верификации |
| 609 | Срок действия кода подтверждения истек |
| 610 | Вы превысили суточный лимит в размере 50МРП. Попробуйте позднее. |
| 611 | Минимальная сумма платежа 1000тг |
| 801 | Провайдер платежей не установлен |
| 802 | Магазин недоступен |
| 803 | Комиссии не найдены |
| 803 | Платежная система не установлена |
| 808 | Мерчант не найден. Требуется создать транзакцию повторно |
| 809 | Аккаунт не найден в системе поставщика |
| 1000 | Нет ошибок |
| 2000 | Терминал не найден |
| 2001 | Магазин заблокирован |
| 2002 | Аккаунт заблокирован |
| 2003 | Платежная система не найдена |
| 2004 | Действие не разрешено |
| 2005 | Транзакция не подтверждена |
| 2006 | Неверный статус платежа |
| 2007 | Аккаунт платежной системы не установлен |
| 2008 | Баланс аккаунта не установлен |
| 2009 | Платежная система не установлена |
| 2010 | Ошибка обработки запроса. Попробуйте позднее |
| 2011 | Транзакция уже существует |
| 2012 | Транзакция не найдена |
| 2013 | Неверный тип транзакции |
| 2014 | Источник платежа не найден |
| 2015 | Оператор не найден |
| 2016 | Тип платежной системы не найден |
| 2017 | Время жизни платежа превышено |
| 2018 | Непредвиденная ошибка транзакции. Обновите страницу и попробуйте еще раз. |
| 2019 | Недостаточно баланса |
| 2020 | Этой суммы недостаточно |
| 2021 | Ошибка при получение ответа от биллинга |
| 2022 | Транзакция не завершена |
| 2023 | Платеж уже существует |
| 2030 | Сервис недоступен. Обратитесь к оператору связи |
| 3000 | Непредвиденная ошибка приложения |
| 3001 | Ошибка SMS шлюза |
| 3002 | Критическая ошибка приложения со стороны провайдера |
| 3003 | Некритическая ошибка приложения со стороны провайдера |
| 3004 | Платеж отклонен биллинговой системой. Просим обратиться к провайдеру связи |
| 3005 | Ошибка перевода. Попробуйте повторить позднее. |
| 3006 | Номер абонента не соответствует условиям предоставления сервиса. |
| 3007 | Номер абонента-отправителя не соответствует условиям предоставления сервиса. |
| 3008 | Номер абонента-отправителя введен неверно |
| 3009 | Номер абонента-получателя введен неверно |
| 3010 | Сумма введена неверно |
| 3011 | Не достаточно средств. При совершении мобильного перевода на балансе должно оставаться не менее 100тг |
| 3012 | Недостаточно средств для совершения операции |
| 3013 | Имеется непогашенная задолженность по услуге "Доверительный платеж" |
| 3014 | Ограничение оператора: Абонент потратил менее 500 тенге |
| 9999 | Общая ошибка системы |
Приложение 2. Таблицы
Таблица 1. Типы платежей
| Поле | Описание |
|---|---|
| refill | Пополнение баланса абонента |
| pay | Списание с баланса абонента |
| revoke | Отмена платежа |
| refund | Возврат платежа |
| transfer | Перевод между балансами абонентов |
Таблица 2. Статусы ответа
| Поле | Описание |
|---|---|
| need_approve | Необходимо подтверждение |
| error | Ошибка |
| success | Успешно завершен |
Таблица 3. Статусы платежей
| Поле | Описание |
|---|---|
| new | Новый заказ |
| process | В обработке |
| error | Ошибка проведения заказа |
| success | Успешно завершен |
Таблица 4. Типы выплат
| Поле | Описание |
|---|
Тестовые номера телефонов
Механика мобильной коммерции подразумевает тестирование в рамках ряда операторов.
Ниже предоставлены номера и соответствующие им OTP-коды для проведения тестов.
Список номеров:
| Оператор | Номер телефона | OTP код |
|---|---|---|
| Кселл | 77017777777 | 111111 |
| Актив | 77027777777 | 111111 |
| Теле2 | 77037777777 | 111111 |
| Алтел | 77047777777 | 111111 |
Режим тестирования
В процессе тестирования вам может потребоваться эмуляция работы сервиса. Для этого вы можете воспользоваться передачей флага testmode со следующими значениями:
| testmode | Описание |
|---|---|
| 0 | Боевой режим |
| 1 | Тестовый режим, статус ответа может быть случайном (success / error со случайной ошибкой); |
| 2 | Тестовый режим, статус ответа всегда success; |
| 3 | Тестовый режим, статус ответа всегда error; |
| 4 | Тестовый режим, статус ответа всегда error, серверные ошибки (HTTP codes 500-504); |
Все новые мерчанты первоначально находятся в тестовом режиме, затем после завершения тестирования и отправки мерчантом в Asiapay официального письма на электронную почту менеджера о подключении Боевого режима, администрация Asiapay переводит мерчанта в рабочий (боевой) режим.