Введение

Документация и спецификация API (далее - Документация) разработана с целью информирования разработчиков партнеров о доступных методах интеграции и их параметрах.

В рамках документации используются следующие сокращения и определения:

МФС - мобильные финансовые сервисы, услуги AsiaPay по зачислению и списанию денежных средств с/на мобильные номера мобильных операторов связи

AsiaPay - платежная организация, оператор электронных денег, предоставляющая услуги МФС для партнеров

Aбонент - физическое лицо, заключившее с мобильным оператором связи договор на услуги связи, включающий услуги МФС

Партнер - юридическое лицо, заключивший с AsiaPay договор на услуги МФС

Обратная связь

Вопросы и предложения по документации можно направлять на электронный адрес [email protected], а также по реквизитам указанным в разделе контакты на официальном сайте 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

Получение ссылки на фрейм витрины

Запрос

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
email	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": "[email protected]",
    "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 переводит мерчанта в рабочий (боевой) режим.