Payout notify

Freedom Pay sends the final result of a payout to pg_post_link of the payout request.

Sent once the payout is final: successful or failed.

Signed with the payout secret key (not the payment one): check the signature before you act on the notification.

Common rules for all callbacks: see Callbacks Overview.

Payout notification flow

The notification is a POST request (application/x-www-form-urlencoded) with one field pg_xml: an XML document with the root response.

Fields of the XML

Field	Description	Payout methods
`pg_status`	Result: `ok` the payout is successful, `error` the payout failed.	all
`pg_payment_status`	Status of the payout: `success` or `error`. The same value as in Get payout status.	all
`pg_payment_id`	Payout ID in Freedom Pay.	all
`pg_order_id`	Payout ID in the merchant system: `pg_order_id` of the payout request.	all
`pg_merchant_id`	Merchant ID.	all except IBAN
`pg_payment_amount`	Payout amount.	all except IBAN
`pg_to_pay`	Amount written off the merchant balance: the payout amount, plus the commission if the merchant pays it.	payout page
`pg_balance`	Balance of the merchant after the payout.	all except IBAN
`pg_payment_date`	Date and time of the payout, format `YYYY-MM-DD hh:mm:ss`. Empty if the payout failed.	all except IBAN
`pg_card_hash`	Masked card number of the recipient.	payout page, payout to a saved card
`pg_card_id`, `pg_card_token`	ID and token of the saved card.	payout to a saved card
`pg_type`	`iban2iban`.	payout by IBAN
`pg_failure_code`, `pg_failure_description`	Error code and description. Sent if the payout failed.	all
`pg_salt`, `pg_sig`	Random string and the signature with the payout secret key.	all

Check pg_sig over all the fields of the XML by the rules in Merchant API Overview, with the payout secret key; the script name is the last segment of the path of pg_post_link.

The XML may have other fields: ignore the ones you do not know, but keep them in the signature check.

Result

Your answer	Meaning	Next step
HTTP `200`, or the body `<pg_status>ok</pg_status>`	The notification is delivered.	Nothing else is needed.
Anything else, or no answer within 30 seconds	The notification is not delivered.	Freedom Pay repeats it after about 4 minutes, at most 3 attempts in total.

The same notification can come more than once: process it by pg_payment_id only once.

If the notification does not come, request Get payout status.

Request example

The value of pg_xml for a successful payout from the payout page:

<?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>

The value of pg_xml for a failed 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_card_hash>5325-34XX-XXXX-1311</pg_card_hash>
    <pg_failure_description>Заявка аннулирована</pg_failure_description>
    <pg_failure_code>10000</pg_failure_code>
    <pg_salt>6mogmrA8IYqgvvLg</pg_salt>
    <pg_sig>d52c0a682bc478b4d25cc65d6dfe5bc7</pg_sig>
</response>

Payout notification flow#

Fields of the XML#

Result#

Request example#

Request

Responses

Payout notification flow

Fields of the XML

Result

Request example