Save card

Creates a page on which the client enters the card data, and returns its URL pg_redirect_url. Redirect the client to it.

To check the card, a small amount is blocked on it and released right away.

After the card is saved, the client returns to pg_back_link, and the card token pg_card_token comes to pg_post_link.

If recurring payments are enabled for the merchant, a recurring profile is created with the card: its ID pg_recurring_profile_id comes in the notification and is used in Create recurring payment.

Up to 10 saved cards per pg_user_id. To see and delete them, use Get saved cards and Delete saved card.

Test cards: see Merchant API Overview.

Card saving flow

Notification to pg_post_link

The notification is sent as POST with one form field pg_xml that contains the XML below.
It is signed: the script name for the signature is the last part of the pg_post_link path.

Field	Description
`pg_payment_id`	ID of the card saving operation.
`pg_order_id`	`pg_order_id` from the request.
`pg_card_hash`	Masked card number.
`pg_card_month`	Card expiry month.
`pg_card_year`	Card expiry year, 2 digits.
`pg_bank`	Issuing bank.
`pg_country`	Country of the issuing bank.
`pg_card_3ds`	`1` — the client passed 3DS, `0` — without 3DS.
`pg_status`	`success` — the card is saved.
`pg_card_id`	Card ID. Deprecated: use `pg_card_token`.
`pg_card_token`	Card token: pass it in Create payment.
`pg_user_id`	`pg_user_id` from the request.
`pg_recurring_profile_id`	Recurring profile ID: pass it in Create recurring payment. Empty if recurring payments are not enabled for the merchant.
`pg_type`	`approve`.
`brand_alias, bank_alias`	Card brand and bank. Only with `pg_extend_data = 1`.
`pg_card_holder`	Cardholder name. Only if enabled for the merchant.
`pg_salt`	Random string.
`pg_sig`	Signature.

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>1023122203686</pg_payment_id>
    <pg_order_id>ct2-add</pg_order_id>
    <pg_card_hash>4111-11XX-XXXX-1111</pg_card_hash>
    <pg_card_month>12</pg_card_month>
    <pg_card_year>30</pg_card_year>
    <pg_bank>UNKNOWN</pg_bank>
    <pg_country></pg_country>
    <pg_card_3ds>0</pg_card_3ds>
    <pg_status>success</pg_status>
    <pg_card_id>321</pg_card_id>
    <pg_card_token>a783d897-4167-46ba-85dc-2dbd8246fc48</pg_card_token>
    <pg_user_id>ct-user-2</pg_user_id>
    <pg_recurring_profile_id>62</pg_recurring_profile_id>
    <pg_type>approve</pg_type>
    <pg_salt>6QS78LPr</pg_salt>
    <pg_sig>53ed64cb375713d8e549e9f1e25ceec2</pg_sig>
</response>

Result

Response	Meaning	Next step
`pg_status = ok`	The card saving page is created.	Redirect the client to `pg_redirect_url`.
`pg_status = error`	The request is rejected.	See «Errors» below.

If the card is not saved (for example, the payment system declined the check), the client is redirected to the failure URL from the merchant settings with pg_failure_code and pg_failure_description, and no notification is sent.

Errors

The error is returned in pg_error_code and pg_error_description; the HTTP status depends on the error. Error responses are not signed.

HTTP	`pg_error_code`	When	What to do
`200`	`0`	A parameter is missing or invalid: `pg_error_description` names it.	Fix the request.
`401`	`1100`	The signature is missing or invalid.	Check the signature: see Merchant API Overview.
`200`	`1826`	The client already has 10 saved cards.	Delete a card with Delete saved card.

Request example

Required fields only. pg_sig is calculated with the secret key test_secret_key.
Line breaks in the body are added for readability: send the body as one line.

Responses

🟢200Success

application/xml

Bodyapplication/xml

Example

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>1023122203686</pg_payment_id>
    <pg_merchant_id>13991</pg_merchant_id>
    <pg_order_id>ct2-add</pg_order_id>
    <pg_redirect_url>https://customer-regress.freedom-pay.dev/v1/merchant/13991/cardstorage/view?pg_payment_id=01a173c7-1c65-7329-afe3-a332c79657e7</pg_redirect_url>
    <pg_status>ok</pg_status>
    <pg_type>init</pg_type>
    <pg_salt>NORipC31</pg_salt>
    <pg_sig>9a9967de268d1c145c869c3d189d2387</pg_sig>
</response>

🟢200Error

🟠401Unauthorized

Card saving flow#

Notification to pg_post_link#

Result#

Errors#