Прием платежей
В этом разделе описана механика, при которой Firstpay списывает деньги в пользу мерчанта и впоследствии перечисляет их на соответствующий расчетный счет.
Метод осуществляется с формированием адреса платежной страницы и перенаправления клиента на нее. Прием работает в форматах widget и frame.
Прием платежей с помощью банковских карт и мобильной коммерции может проводиться в тестовом режиме. Другие способы будут доступны только в боевом режиме.
В этом разделе описана механика, при которой Firstpay списывает деньги в пользу мерчанта и впоследствии перечисляет их на соответствующий расчетный счет.
Метод осуществляется с формированием адреса платежной страницы и перенаправления клиента на нее. Прием работает в форматах widget и frame.
Прием платежей с помощью банковских карт и мобильной коммерции может проводиться в тестовом режиме. Другие способы будут доступны только в боевом режиме.
Параметры запроса:
Пример ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<pg_status>ok</pg_status>
<pg_payment_id>4567788</pg_payment_id>
<pg_redirect_url>https://api.firstpay.kz/pay.html?customer=498333170d6a895148c57c53ffb18287</pg_redirect_url>
<pg_redirect_url_type>need data</pg_redirect_url_type>
<pg_salt>bdwLavL9lg6It91b</pg_salt>
<pg_sig>709633e91387c56ac6fb7cb33d1e07d8</pg_sig>
</response>Запрос на result_url магазина. Результат платежа
URL запроса
POST {{result_url}}
URL запроса
POST {{result_url}}
Пример отрицательного ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<pg_status>rejected</pg_status>
<pg_description>Платеж отменен</pg_description>
<pg_salt>random string</pg_salt>
<pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>Пример положительного ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<pg_status>ok</pg_status>
<pg_description>Заказ оплачен</pg_description>
<pg_salt>random string</pg_salt>
<pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>После приема оплаты от клиента или при невозможности совершить платеж Firstpay вызывает Result URL магазина и передает на него методом Request Method информацию о результате платежа.
При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и Firstpay отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.
Result URL на стороне мерчанта должен быть общедоступным, без авторизации.
Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, Firstpay будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.
Если первая попытка вызова Result URL оказалась неуспешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет магазину отказаться от платежа.
Магазин должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.
Ответ на result_url от мерчанта
Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.
При получении данного запроса мерчант должен произвести необходимые действия для передачи товара или услуги покупателю, в случае если платеж был успешным. Если pg_can_reject равно 1 и мерчант не может принять платеж (например, бронь на билеты истекла), он обязан ответить со статусом rejected, и Firstpay отзовет платеж. В этом случае поле pg_description из ответа мерчанта показывается пользователю как причина отказа.
Result URL на стороне мерчанта должен быть общедоступным, без авторизации.
Если сервер мерчанта недоступен в момент вызова Result URL или ответ от сервера был не со статусом 200, Firstpay будет предпринимать повторные попытки его вызвать каждые полчаса в течение 2 часов, даже если время жизни счета pg_lifetime истечет.
Если первая попытка вызова Result URL оказалась неуспешной, то платеж не отменяется, и в последующих вызовах Result URL не позволяет магазину отказаться от платежа.
Магазин должен быть готов к тому, что Result URL будет вызван повторно для одного и того же платежа. Ответы на повторные вызовы должны совпадать с первоначальным ответом, даже если время жизни транзакции pg_lifetime истекло.
Ответ на result_url от мерчанта
Статус rejected может быть возвращен мерчантом только в случае, когда во входящем запросе от гейта был указан параметр pg_can_reject равный 1, в противном случае, вне зависимости от ответа мерчанта, платеж будет считаться совершенным. Если мерчант отказался от платежа (ответил rejected), покупатель перенаправляется на Failure URL, иначе – на Success URL.
- ok - платеж принят
- rejected - отказ от платежа случае если pg_can_reject равен 1
- error - ошибка в интерпретации данных
Возврат покупателя на сайт мерчанта
После завершения платежа в online платежной системе, покупатель перенаправляется на страницу мерчанта Success URL или Failure URL, в зависимости от результата платежа. Перенаправление происходит методом Success URL Method или Failure URL Method, указанным при инициализации платежа.
Если при GET запросе Success URL или Failure URL уже содержат параметры в query string, то дополнительные параметры pg_order_id, pg_payment_id и пользовательские переменные мерчанта дописываются в конец query string. мерчанта должен следить за тем, чтобы имена дополнительных параметров не совпадали с именами уже имеющимися параметров.
Необходимо четко понимать разницу между Result URL и Success URL.
Result URL вызывается напрямую с сервера Firstpay, в то время как Success URL вызывается браузером пользователя, когда Firstpay перенаправляет пользователя обратно на сайт магазина. Неправильно использовать Success URL как единственный способ узнать о завершении оплаты, потому что пользователь может по разным причинам (например, при разрыве связи) не дойти до Success URL после оплаты. Самый надежный способ узнать о завершении платежа – это реализовать Result URL, который Firstpay обязуется вызывать повторно каждые полчаса в течение 2 часов после оплаты, если первая попытка по любым причинам не удалась.
URL запроса
POST {{success_url}} или {{failure_url}}
Поля запроса
После завершения платежа в online платежной системе, покупатель перенаправляется на страницу мерчанта Success URL или Failure URL, в зависимости от результата платежа. Перенаправление происходит методом Success URL Method или Failure URL Method, указанным при инициализации платежа.
Если при GET запросе Success URL или Failure URL уже содержат параметры в query string, то дополнительные параметры pg_order_id, pg_payment_id и пользовательские переменные мерчанта дописываются в конец query string. мерчанта должен следить за тем, чтобы имена дополнительных параметров не совпадали с именами уже имеющимися параметров.
Необходимо четко понимать разницу между Result URL и Success URL.
Result URL вызывается напрямую с сервера Firstpay, в то время как Success URL вызывается браузером пользователя, когда Firstpay перенаправляет пользователя обратно на сайт магазина. Неправильно использовать Success URL как единственный способ узнать о завершении оплаты, потому что пользователь может по разным причинам (например, при разрыве связи) не дойти до Success URL после оплаты. Самый надежный способ узнать о завершении платежа – это реализовать Result URL, который Firstpay обязуется вызывать повторно каждые полчаса в течение 2 часов после оплаты, если первая попытка по любым причинам не удалась.
URL запроса
POST {{success_url}} или {{failure_url}}
Поля запроса
Балансом мобильного
Firstpay предлагает возможность оплачивать заказ/услугу с баланса мобильного телефона, если мобильный оператор плательщика поддерживает данную возможность. Проведение платежа осуществляется проведением двух операций. В начале формируеться платеж по методу «POST https://api.firstpay.kz/init_payment.php» после необходимо произвести запрос метода «POST https://api.firstpay.kz/mfs/pay » чтобы адресовать платеж по мобильной коммерции. Доступные мобильные операторы:
Tele2
Altel
Beeline
Activ
Kcell
URL запроса
POST https://api.firstpay.kz/init_payment.php
Поля запроса:
Firstpay предлагает возможность оплачивать заказ/услугу с баланса мобильного телефона, если мобильный оператор плательщика поддерживает данную возможность. Проведение платежа осуществляется проведением двух операций. В начале формируеться платеж по методу «POST https://api.firstpay.kz/init_payment.php» после необходимо произвести запрос метода «POST https://api.firstpay.kz/mfs/pay » чтобы адресовать платеж по мобильной коммерции. Доступные мобильные операторы:
Tele2
Altel
Beeline
Activ
Kcell
URL запроса
POST https://api.firstpay.kz/init_payment.php
Поля запроса:
Параметры ответа
Параметры ответа:
Проведение запроса мобильной коммерцией
URL запроса
POST https://api.firstpay.kz/mfs/pay
Поля запроса:
URL запроса
POST https://api.firstpay.kz/mfs/pay
Поля запроса:
После отправления запроса в ответе придет статус платежа и его данные, при возникновении ошибки платеж примет статус error и ему будет присвоен код ошибки и описание в соответствии причины данной ошибки.
Статус платежа
Метод для получения статуса платежа по его ID. В ответ на данный запрос возвращается информация статуса платежа.
URL запроса
POST https://api.firstpay.kz/get_status2.php
Поля запроса:
Статус платежа
Метод для получения статуса платежа по его ID. В ответ на данный запрос возвращается информация статуса платежа.
URL запроса
POST https://api.firstpay.kz/get_status2.php
Поля запроса:
Параметры ответа:
Пример успешного ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<pg_status>ok</pg_status>
<pg_payment_id>511194</pg_payment_id>
<pg_transaction_status>ok</pg_transaction_status>
<pg_can_reject>0</pg_can_reject>
<pg_captured>1</pg_captured>
<pg_create_date>2021-08-26 11:52:25</pg_create_date>
<pg_salt>41F5ZyqcOabTG5u7</pg_salt>
<pg_sig>34484775bd62986753429d6af57e94eb</pg_sig>
</response>Пример не успешного ответа (В ошибке ):
<?xml version="1.0" encoding="utf-8"?>
<response>
<pg_status>ok</pg_status>
<pg_payment_id>511180</pg_payment_id>
<pg_transaction_status>failed</pg_transaction_status>
<pg_can_reject>0</pg_can_reject>
<pg_captured>0</pg_captured>
<pg_create_date>2021-08-26 11:53:12</pg_create_date>
<pg_failure_code>5</pg_failure_code>
<pg_failure_description>Transaction declined</pg_failure_description>
<pg_salt>VeJEycvwsTn74VEA</pg_salt>
<pg_sig>aa65c7786f5cba0cd9e6a452bfbcc7a2</pg_sig>
</response>Пример ответа (платеж не найден):
<?xml version="1.0" encoding="utf-8"?>
<response>
<pg_status>error</pg_status>
<pg_error_code>340</pg_error_code>
<pg_error_description>Транзакция не найдена</pg_error_description>
</response>API-метод для вызова обменных курсов
Данный метод позволяет мерчанта самостоятельного ознакомления с текущим обменным курсом без обращения к менеджеру. По запросу возвращаются все значения из списка, за исключением тех, которые соответствуют значению «от куда» (KZT:KTZ = 1). После отправления запроса последует ответ со статусом запроса (success/error). Получение ответа с ошибкой так же сопровождается описанием и кодом ошибки, список ошибок закреплен в конце.
Request URL
POST https://api.firstpay.kz/get_rates.php
Поля запроса:
Данный метод позволяет мерчанта самостоятельного ознакомления с текущим обменным курсом без обращения к менеджеру. По запросу возвращаются все значения из списка, за исключением тех, которые соответствуют значению «от куда» (KZT:KTZ = 1). После отправления запроса последует ответ со статусом запроса (success/error). Получение ответа с ошибкой так же сопровождается описанием и кодом ошибки, список ошибок закреплен в конце.
Request URL
POST https://api.firstpay.kz/get_rates.php
Поля запроса:
Успешный ответ со списком обменных курсов:
Code 200
Body:
<response>
<item>
<pg_currency_from>RUB</pg_currency_from>
<pg_currency_to>KZT</pg_currency_to>
<rate>5</rate>
</item>
<item>
<pg_currency_from>KZT</pg_currency_from>
<pg_currency_to>RUB</pg_currency_to>
<rate>0.25</rate>
</item>
<pg_datetime>2026-07-09T07:59:00+00:00</pg_datetime>
</response>Не успешный ответ, недействительная подпись:
Code 401
Body:
<response>
<pg_status>error</pg_status>
<pg_error_code>1100</pg_error_code>
<pg_error_description>Invalid request signature</pg_error_description>
</response>Не успешный ответ, ошибка:
Code 500
Body:
<response>
<pg_status>error</pg_status>
<pg_error_code>9999</pg_error_code>
<pg_error_description>Unexpected error</pg_error_description>
</response>Прием по сохраненной карте
Данный метод позволяет осуществить прием платежа предварительно сохранив ее. Для этого необходимо сохранить карту используя метод для сохранения карты «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/cardstorage/add», после отправки данных клиентом в ответ на данный запрос в ответе придет токен карты клиента в системе firstpay. После получения токена карты клиента необходимо произвести инициализацию оплаты с использованием соответствующих данных токена карты и его владельца отправив запрос «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/card/init» . После инициализации платежа использовать полученый ID платежа в следующем методе «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/card/pay» .
Request URL
POST https://api.firstpay.kz/v1/merchant/(merchant_id)/cardstorage/add
Поля запроса:
Данный метод позволяет осуществить прием платежа предварительно сохранив ее. Для этого необходимо сохранить карту используя метод для сохранения карты «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/cardstorage/add», после отправки данных клиентом в ответ на данный запрос в ответе придет токен карты клиента в системе firstpay. После получения токена карты клиента необходимо произвести инициализацию оплаты с использованием соответствующих данных токена карты и его владельца отправив запрос «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/card/init» . После инициализации платежа использовать полученый ID платежа в следующем методе «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/card/pay» .
Request URL
POST https://api.firstpay.kz/v1/merchant/(merchant_id)/cardstorage/add
Поля запроса:
Параметры ответа
Пример ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<pg_payment_id>12345</pg_payment_id>
<pg_merchant_id>1234</pg_merchant_id>
<pg_order_id/>
<pg_redirect_url>https://api.paybox.money/v1/merchant/1234/cardstorage/view?pg_payment_id=ee4f2b59ad667949a1143353543</pg_redirect_url>
<pg_status>ok</pg_status>
<pg_type>init</pg_type>
<pg_salt>4vXEfz6S</pg_salt>
<pg_sig>3f3bb687c0d4b8c8331eb797e1d20a75</pg_sig>
</response>Безакцептные списания
Данный метод позволяет осуществлять безакцепные списание, то есть не требующие подтверждения клиента, для осуществления механизмов по типу подписок, ежемесячных платежей. Для проведения безакцептных платежей необходимо иметь токен карты клиента. Предварительно заполучив токен карты клиента, используя метод сохранения карты клиента «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/cardstorage/add». после отправки данных клиентом в ответ на данный запрос в ответе придет токен карты клиента в системе firstpay. После получения токена карты клиента необходимо произвести инициализацию оплаты с использованием соответствующих данных токена карты и его владельца отправив запрос «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/card/init» . После инициализации платежа использовать полученый ID платежа в следующем методе «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/card/direct » .
Request URL
POST https://api.firstpay.kz/v1/merchant/(merchant_id)/cardstorage/add
Поля запроса:
Данный метод позволяет осуществлять безакцепные списание, то есть не требующие подтверждения клиента, для осуществления механизмов по типу подписок, ежемесячных платежей. Для проведения безакцептных платежей необходимо иметь токен карты клиента. Предварительно заполучив токен карты клиента, используя метод сохранения карты клиента «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/cardstorage/add». после отправки данных клиентом в ответ на данный запрос в ответе придет токен карты клиента в системе firstpay. После получения токена карты клиента необходимо произвести инициализацию оплаты с использованием соответствующих данных токена карты и его владельца отправив запрос «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/card/init» . После инициализации платежа использовать полученый ID платежа в следующем методе «POST https://api.firstpay.kz/v1/merchant/(merchant_id)/card/direct » .
Request URL
POST https://api.firstpay.kz/v1/merchant/(merchant_id)/cardstorage/add
Поля запроса:
Параметры ответа
Пример ответа:
<?xml version="1.0" encoding="utf-8"?>
<response>
<pg_payment_id>12345</pg_payment_id>
<pg_merchant_id>1234</pg_merchant_id>
<pg_order_id/>
<pg_redirect_url>https://api.paybox.money/v1/merchant/1234/cardstorage/view?pg_payment_id=ee4f2b59ad667949a1143353543</pg_redirect_url>
<pg_status>ok</pg_status>
<pg_type>init</pg_type>
<pg_salt>4vXEfz6S</pg_salt>
<pg_sig>3f3bb687c0d4b8c8331eb797e1d20a75</pg_sig>
</response>Прием платежей g2g
В этом разделе описана механика, при которой Firstpay списывает деньги в пользу мерчанта и впоследствии перечисляет их на соответствующий расчетный счет.
Примечание, данный метод позволяет хранить и обрабатывать карточные данные на стороне мерчанта при наличии документа PCI DSS.
Request URL
«POST https://api.firstpay.kz/g2g/payment »
Параметры запроса:
В этом разделе описана механика, при которой Firstpay списывает деньги в пользу мерчанта и впоследствии перечисляет их на соответствующий расчетный счет.
Примечание, данный метод позволяет хранить и обрабатывать карточные данные на стороне мерчанта при наличии документа PCI DSS.
Request URL
«POST https://api.firstpay.kz/g2g/payment »
Параметры запроса: