Save card for payouts

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

The card is saved for payouts only: pass its token pg_card_token in Pay out to card token. It cannot be used for payments.

The page asks only for the card number. No money is blocked on the card.

The result comes to pg_post_link in both cases: the card is saved or not. After a successful saving the client returns to pg_back_link.

Available after Freedom Pay enables it for the merchant: contact your account manager.

To see and delete saved cards, use Get saved cards and Delete saved card: payout cards have pg_is_full = 0 there.

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_bank`	Issuing bank.
`pg_country`	Country of the issuing bank.
`pg_status`	`success` — the card is saved, `error` — the card is not saved.
`pg_user_id`	`pg_user_id` from the request.
`pg_type`	`add_payout_card`.
`pg_card_token`	Card token for Pay out to card token. Only if `pg_status = success`.
`pg_card_id`	Card ID. Deprecated: use `pg_card_token`. Only if `pg_status = success`.
`pg_error_code, pg_error_description`	Error code and text. Only if `pg_status = error`.
`pg_salt`	Random string.
`pg_sig`	Signature.

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>789</pg_payment_id>
    <pg_order_id></pg_order_id>
    <pg_card_hash>4939-77XX-XXXX-4989</pg_card_hash>
    <pg_bank>UNKNOWN</pg_bank>
    <pg_country></pg_country>
    <pg_status>success</pg_status>
    <pg_user_id>loc-user-po</pg_user_id>
    <pg_type>add_payout_card</pg_type>
    <pg_card_token>e7867978-8062-4a88-9235-a453e39bcbd2</pg_card_token>
    <pg_card_id>108</pg_card_id>
    <pg_salt>LvljjGrT</pg_salt>
    <pg_sig>f9df4383080f0b1258e5a40db1fc3600</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.

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>1023122203682</pg_payment_id>
    <pg_merchant_id>13991</pg_merchant_id>
    <pg_order_id></pg_order_id>
    <pg_redirect_url>https://customer-regress.freedom-pay.dev/v1/merchant/13991/cardstoragepayout/view?pg_payment_id=01a16a31-7b0b-716d-9c5c-33721a2d53d5</pg_redirect_url>
    <pg_status>ok</pg_status>
    <pg_type>init</pg_type>
    <pg_salt>Ms996Nlg</pg_salt>
    <pg_sig>331bdb4fda4f368bc01fc936b1e91f23</pg_sig>
</response>

🟢200Error

🟠401Unauthorized

Save card for payouts

Card saving flow#

Notification to pg_post_link#

Result#

Errors#