Create payout page

Creates a payout page: the client enters the card number on it and receives the money.

Use it when you do not know the card of the recipient. If the card is saved, use Pay out to saved card.

Sign the request with the payout secret key: see Merchant API Overview.

Test cards for payouts: see «Cards for payout» in Merchant API Overview.

Payout flow

The page shows the client the payout amount, the commission and the amount to be credited.
The client enters the card number, the cardholder name, the phone number and the email: the phone number and the email are required.

Payout statuses

Statuses of a payout created by this method:

`pg_payment_status` in Get payout status	Meaning
`new`	The client has not submitted the page yet.
`process`	The payment system has not returned the result yet.
`success`	The payout is made.
`error`	The payout is declined.

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 with the payout secret key: the script name for the signature is the last part of the pg_post_link path.
Check the signature over all fields of the notification, including fields that are not described below.

Field	Description
`pg_status`	`ok` — the payout is made, `error` — the payout is declined.
`pg_payment_status`	`success` or `error`.
`pg_payment_id`	Payout ID.
`pg_order_id`	`pg_order_id` from the request.
`pg_merchant_id`	Merchant ID.
`pg_payment_amount`	Payout amount from the request.
`pg_to_pay`	Amount debited from the payout balance.
`pg_balance`	Payout balance after the payout; may be `0` or empty.
`pg_payment_date`	Payout date, format `YYYY-MM-DD hh:mm:ss`; empty for a declined payout.
`pg_card_hash`	Masked number of the recipient's card.
`pg_failure_code`	Decline code; only for a declined payout. See Error codes.
`pg_failure_description`	Decline text; only for a declined payout.
`pg_salt`	Random string.
`pg_sig`	Signature.

Successful payout:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_status>success</pg_payment_status>
    <pg_payment_id>4102</pg_payment_id>
    <pg_order_id>mp-dup-45684a</pg_order_id>
    <pg_balance>0</pg_balance>
    <pg_payment_amount>100</pg_payment_amount>
    <pg_to_pay>100</pg_to_pay>
    <pg_merchant_id>13991</pg_merchant_id>
    <pg_payment_date>2026-10-25 22:41:45</pg_payment_date>
    <pg_card_hash>4671-59XX-XXXX-8252</pg_card_hash>
    <pg_salt>ajdeWVuOaTfKygtW</pg_salt>
    <pg_sig>558577fd22bb9fdc6de7ccc8b605315f</pg_sig>
</response>

Declined payout:

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_payment_status>error</pg_payment_status>
    <pg_payment_id>4105</pg_payment_id>
    <pg_order_id>page_decline-dc7023</pg_order_id>
    <pg_balance>0</pg_balance>
    <pg_payment_amount>100</pg_payment_amount>
    <pg_to_pay>100</pg_to_pay>
    <pg_merchant_id>13991</pg_merchant_id>
    <pg_payment_date></pg_payment_date>
    <pg_card_hash>5325-34XX-XXXX-1311</pg_card_hash>
    <failure_code>10000</failure_code>
    <failure_description>Неизвестная ошибка системы.</failure_description>
    <pg_failure_description>Заявка аннулирована</pg_failure_description>
    <pg_failure_code>10000</pg_failure_code>
    <pg_salt>6mogmrA8IYqgvvLg</pg_salt>
    <pg_sig>9da34d40d83e0c7b7646c3fa9c684cf8</pg_sig>
</response>

Result

`pg_status`	Meaning	Next step
`ok`	The payout page is created.	Redirect the client to `pg_redirect_url`. Wait for the notification to `pg_post_link`, or request Get payout status.
`error`	The request is rejected. `pg_payment_id` is not returned.	See «Errors» below.

Errors

The HTTP status is always 200; the error is returned in pg_error_code and pg_error_description.

`pg_error_code`	When	What to do
`94031`	A parameter is missing or has an invalid value. `pg_error_description` names the parameter. The response is not signed.	Fix the request.
`11005`	`pg_amount` is missing, is not a number, or is outside the range 0.01–99999999. The response is not signed.	Fix the amount.
`1100`	The signature is missing or invalid, or `pg_merchant_id` is not found. The response is not signed.	Check the merchant ID and the signature with the payout secret key.
`8022`	`pg_payment_route = frame` is passed, but payouts in a frame are not enabled for the merchant.	Do not pass `pg_payment_route`, or contact Freedom Pay.
`99081`	A payout with this `pg_order_id` already exists: uniqueness of the order ID is enabled for the merchant.	Pass a new `pg_order_id`.
`1806`	The corporate card for payouts is not set up for the merchant.	Contact Freedom Pay.
`10000`	Payouts to cards are not enabled for the merchant.	Contact Freedom Pay.

Request example

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

application/xml

Bodyapplication/xml

Example

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_merchant_id>13991</pg_merchant_id>
    <pg_payment_id>4102</pg_payment_id>
    <pg_redirect_url>https://customer.freedompay.kz/payout.html?customer=01a17428-0000-7000-8000-000000000001</pg_redirect_url>
    <pg_salt>p1BfAS3TlDlBtg7z</pg_salt>
    <pg_sig>19c5f9124af555083b16cda71b5d9238</pg_sig>
</response>

Payout flow#

Payout statuses#

Notification to pg_post_link#

Result#

Errors#

Request example#