Saving cards

Basic mechanics for saving cards. Further, the saved cards can be used both for payments and for payments

To use this request, you should contact your manager
Adding a card
Request
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}}'
# Signature example:
'add;http://site.kz/back;{{paybox_merchant_id}};{{post_link}};some random string;1234;{{secret_key}}'
Reply
<?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>
Next, you need to open the iframe on the payment page (URL iframe pg_redirect_url from the request), after which the user will open an interface for entering the following card data:

  • Card number
  • Name of the cardholder
  • Year/Month of expiration of the card
  • CVV/CVC After clicking on the "Add card" button, the presence of 3DSecure on the card will be checked.
If the card has 3DSecure, it will redirect to the card issuer's bank page, where the user will be prompted to enter the 3ds password. If the password is entered correctly, three things happen: a) the payment amount (from 1 to 100) is blocked on the user's card; b) the payment is canceled and the specified amount is immediately returned to the user's card; c) the card is added to the system.
If there is no 3DSecure, the money is blocked on the card, after which the user is given 20 minutes or 3 attempts to enter the following payment information:

  • Payment amounts
  • Payment confirmation code
Signature generation:
$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]);
Request URL

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

Headers
Request fields
Response parameters
Adding cards for payouts

Adding cards for payouts
Request
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}}'
# Signature example:
'add2;http://site.kz/back;{{paybox_merchant_id}};{{post_link}};some random string;1234;{{secret_key}}'
Response
<?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>
Next, you need to open the iframe on the payment page (URL iframe pg_redirect_url from the request), after which the user will see an interface for entering the following card data:

  • Card number
After the card details are entered and confirmed by the user, the card is stored in the internal storage. Cards saved using this method cannot be used for making payments, they can only be used for payouts.
Signature generation:
$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 request

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

Headers
Request fields
Response fields
Deleting a card

Remove card
Request
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}}'
# Signature example:
'remove;ef741cfc-f85e-41a0-84e6-2ba964912182;{{paybox_merchant_id}};some random string;1234;{{secret_key}}'
Reply
<?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>
We get pg_card_token from Post link request and pg_user_id to delete cards, we make the following request.
Signature generation:
$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]);
Request URL

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

Request fields
Response parameters
Getting a list of cards

Get list of cards
Request
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}}'
# Signature example:
'list;{{paybox_merchant_id}};some random string;1234;{{secret_key}}'
Reply
<?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>
        <pg_card_hhash>2163f971d73a8c928a7d739fb2732ee1</pg_card_hhash>
        <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>
        <pg_card_hhash>5d90a02298685b8e2787b68863c8ae2a</pg_card_hhash>
        <created_at>2019-08-22 12:45:41</created_at>
    </card>
    <pg_salt>0reqSARN</pg_salt>
    <pg_sig>4cdff2e2e7f54bd4f3cde31dcac9155c</pg_sig>
</response>
By the user pg_user_id we get a list of cards with the following request.
Signature generation:
$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]);
Request URL

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

Request fields
Response parameters
Successful save notification

Reply to post_link from merchant
<?xml version="1.0" encoding="UTF-8"?>
<pg_status>ok</pg_status>
If entered correctly, the payment is canceled and the blocked amount is instantly returned to the user's card, and the card itself is considered successfully added to the system.

If the input attempts are exceeded, or after the allotted time expires, the payment is canceled and the blocked amount is instantly returned to the user's card.

If the card is successfully added, the pg_xml parameter will contain the following XML:

In this case, pg_type will be equal to confirm.

Merchant server should respond with status 200

Post link on the merchant side must be public, without authorization.

Request URL

POST {{post_link}}

Header
Поля запроса