Сохранение карт

Базовая механика сохранения карт. Далее сохраненные карты можно использовать как для оплат, так и для выплат

Для использования данного запроса Вам следует обратиться к своему менеджеру
Добавление карты
Запрос
curl --location --request POST 'https://api.freedompay.kz/v1/merchant/{{paybox_merchant_id}}/cardstorage/add' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_user_id=1234' \
--form 'pg_post_link={{post_link}}' \
--form 'pg_back_link=http://site.kz/back' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'add;http://site.kz/back;{{paybox_merchant_id}};{{post_link}};some random string;1234;{{secret_key}}'
Ответ
<?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.freedompay.kz/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>
Далее необходимо открыть iframe на странице оплаты (URL iframe pg_redirect_url из запроса, после чего пользователю откроется интерфейс для ввода следующих карточных данных:

  • Номер карты
  • Имя держателя карты
  • Год/Месяц окончания действия карты
  • CVV/CVC После нажатия на кнопку "Добавить карту", будет произведена проверка наличия на карте 3DSecure.
Если на карте есть 3DSecure, произойдет перенаправление на страницу банка эмитента карты, где пользователю будет предложено ввести 3ds пароль. В случае правильного ввода пароля происходят три вещи: а) сумма платежа (от 1 до 100) блокируется на карте пользователя; б) платеж отменяется и указанная сумма моментально возвращается на карточку пользователя; в) карта добавляется в систему.

Если 3DSecure нет, деньги блокируются на карте, после чего пользователю дается 20 минут или 3 попытки для ввода следующей информации о платеже:

  • Суммы платежа
  • Кода подтверждения платеж
Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_user_id' => 1234,
    'pg_post_link' => 'http://site.kz/post',
    'pg_back_link' => 'http://site.kz/back',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'add');
array_push($request, $secret_key); 

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.kz/v1/merchant/{{paybox_merchant_id}}/cardstorage/add

Headers
Поля запроса
Параметры ответа
Добавление карты с 0 суммой


Данный способ добавления карт доступен только в Казахстане.
Запрос
curl --location --request POST 'https://api.freedompay.kz/v1/merchant/{{paybox_merchant_id}}/cardstorage/add2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_user_id=1234' \
--form 'pg_post_link={{post_link}}' \
--form 'pg_back_link=http://site.kz/back' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'add2;http://site.kz/back;{{paybox_merchant_id}};{{post_link}};some random string;1234;{{secret_key}}'
Ответ
<?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.freedompay.kz/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>
Далее необходимо открыть iframe на странице оплаты (URL iframe pg_redirect_url из запроса), после чего пользователю откроется интерфейс для ввода следующих карточных данных:
  • Номер карты
  • Имя держателя карты
  • Год/Месяц окончания действия карты
  • CVV/CVC После нажатия на кнопку "Добавить карту", будет произведена проверка наличия на карте 3DSecure.
Если на карте есть 3DSecure, произойдет перенаправление на страницу банка эмитента карты, где пользователю будет предложено ввести 3ds пароль. В случае правильного ввода пароля карта добавляется в систему

Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_user_id' => 1234,
    'pg_post_link' => 'http://site.kz/post',
    'pg_back_link' => 'http://site.kz/back',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'add2');
array_push($request, $secret_key); 

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.kz/v1/merchant/{{paybox_merchant_id}}/cardstorage/add2

Headers
Поля запроса
Параметры ответа
Добавление карт для выплат

Добавление карт для выплат
Запрос
curl --location --request POST 'https://api.freedompay.kz/v1/merchant/{{paybox_merchant_id}}/cardstoragepayout/add' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_user_id=1234' \
--form 'pg_post_link={{post_link}}' \
--form 'pg_back_link=http://site.kz/back' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'add2;http://site.kz/back;{{paybox_merchant_id}};{{post_link}};some random string;1234;{{secret_key}}'
Ответ
<?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.freedompay.kz/v1/merchant/1234/cardstoragepayout/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>
Далее необходимо открыть iframe на странице оплаты (URL iframe pg_redirect_url из запроса), после чего пользователю откроется интерфейс для ввода следующих карточных данных:
  • Номер карты
После ввода данных карты, и подтверждения пользователем, карта сохраняется во внутреннем хранилище. Карты сохраненные с помощью этого метода, нельзя использовать для проведения платежей, их можно использовать только для выплат.

Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_user_id' => 1234,
    'pg_post_link' => 'http://site.kz/post',
    'pg_back_link' => 'http://site.kz/back',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'add2');
array_push($request, $secret_key); 

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.kz/v1/merchant/{{paybox_merchant_id}}/cardstoragepayout/add

Headers
Поля запроса
Параметры ответа
Удаление карты

Удаление карты
Запрос
curl --location --request POST 'https://api.freedompay.kz/v1/merchant/{{paybox_merchant_id}}/cardstorage/remove' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_user_id=1234' \
--form 'pg_card_token=ef741cfc-f85e-41a0-84e6-2ba964912182' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'remove;ef741cfc-f85e-41a0-84e6-2ba964912182;{{paybox_merchant_id}};some random string;1234;{{secret_key}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <card>
        <pg_status>deleted</pg_status>
        <pg_merchant_id>1234</pg_merchant_id>
        <pg_card_id/>
        <pg_card_hash/>
        <deleted_at>2020-07-28 09:45:51</deleted_at>
    </card>
    <pg_salt>3wOIeVEc</pg_salt>
    <pg_sig>5b8c60b26ee1addc9956ebc8426353e6</pg_sig>
</response>
Получаем pg_card_token из Post link запроса и pg_user_id для удаления карт делаем следующий запрос.
Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_user_id' => 1234,
    'pg_card_token' => 'ef741cfc-f85e-41a0-84e6-2ba964912182',
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'remove');
array_push($request, $secret_key); 

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.kz/v1/merchant/{{paybox_merchant_id}}/cardstorage/remove

Поля запроса
Параметры ответа
Получение списка карт

Получение списка карт
Запрос
curl --location --request POST 'https://api.freedompay.kz/v1/merchant/{{paybox_merchant_id}}/cardstorage/list' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_user_id=1234' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}'
# Пример подписи:
'list;{{paybox_merchant_id}};some random string;1234;{{secret_key}}'
Ответ
<?xml version="1.0" encoding="utf-8"?>
<response>
    <card>
        <pg_status>approved</pg_status>
        <pg_merchant_id>1234</pg_merchant_id>
        <pg_card_id>56</pg_card_id>
        <pg_card_token>ef741cfc-f85e-41a0-84e6-2ba964912182</pg_card_token>
        <pg_recurring_profile_id>317</pg_recurring_profile_id>
        <pg_card_hash>5101-45XX-XXXX-7898</pg_card_hash>
        <created_at>2019-07-19 06:03:08</created_at>
    </card>
    <card>
        <pg_status>approved</pg_status>
        <pg_merchant_id>1234</pg_merchant_id>
        <pg_card_id>93</pg_card_id>
        <pg_card_token>ef741cfc-f85e-41a0-84e6-2ba964912182</pg_card_token>
        <pg_recurring_profile_id>331</pg_recurring_profile_id>
        <pg_card_hash>4003-03XX-XXXX-5378</pg_card_hash>
        <created_at>2019-08-22 12:45:41</created_at>
    </card>
    <pg_salt>0reqSARN</pg_salt>
    <pg_sig>4cdff2e2e7f54bd4f3cde31dcac9155c</pg_sig>
</response>
По пользователю pg_user_id получаем список карт со следующим запросом.
Генерация подписи:
$pg_merchant_id = {{paybox_merchant_id}};
$secret_key = {{paybox_merchant_secret}};

$request = [
    'pg_merchant_id'=> $pg_merchant_id,
    'pg_user_id' => 1234,
    'pg_salt' => 'some random string',
];

//generate a signature and add it to the array
ksort($request); //sort alphabetically
array_unshift($request, 'list');
array_push($request, $secret_key); 

$request['pg_sig'] = md5(implode(';', $request)); // signature

unset($request[0], $request[1]);
URL запроса

POST https://api.freedompay.kz/v1/merchant/{{paybox_merchant_id}}/cardstorage/list

Поля запроса
Параметры ответа
Уведомление о успешном сохранении

Ответ на post_link от мерчанта
<?xml version="1.0" encoding="UTF-8"?>
<pg_status>ok</pg_status>
В случае правильного ввода платеж отменяется и заблокированная сумма моментально возвращается на карточку пользователя, а сама карта считается успешно добавленной в систему.

В случае превышения попыток ввода, либо по истечению выделенного времени платеж отменяется и заблокированная сумма моментально возвращается на карточку пользователя.

В случае успешного добавления карты, в параметре pg_xml будет XML следующего вида:

При этом pg_type будет равен approve.

Сервер мерчанта должен ответить статусом 200
Post link на стороне мерчанта должен быть общедоступным, без авторизации.

URL запроса
POST {{post_link}}

Headers

Поля запроса