Overview

Callbacks are requests from Freedom Pay to your server: they report the result of a payment or a payout, or ask whether an order can be paid.

You pass the URLs in the payment request (pg_result_url, pg_check_url, pg_success_url, pg_failure_url) or set them in the merchant settings: a URL from the request takes priority.

For payouts, pass pg_post_link in every payout request.

All callbacks are signed by the same rules as the requests: see «Signature» in Merchant API Overview.

Callbacks

Callback	URL	When	Signed with	Delivered when	Retries
Result notify	`pg_result_url`	The payment is final: successful or failed.	payment secret key	HTTP `2xx`	after 15 min, then twice every 30 min
Check request	`pg_check_url`	Before the money is charged, only if Freedom Pay enabled the check.	payment secret key	—	no
Redirect back	`pg_success_url`, `pg_failure_url`	The browser of the client returns to your site after the payment.	payment secret key, depends on the payment page	—	no
Payout notify	`pg_post_link`	The payout is final: successful or failed.	payout secret key	HTTP `200` or `<pg_status>ok</pg_status>`	about every 4 min, 3 attempts in total
Card saving notification	`pg_post_link` of Save card, Save card without a charge, Save card for payouts	The card is saved (for payouts: saved or not).	payment secret key	—	no: sent once

Notifications in JSON with a JWS signature are described on their own pages:

Invoice recurring profiles: Notify.

Installment applications: Application status notification, not available yet.

Method and format

Result notify and Check request use the method pg_request_method of the payment request, or the method from the merchant settings, POST by default:

POST: the fields in the body, application/x-www-form-urlencoded.

GET: the fields in the query string.

XML: POST with one field pg_xml, an XML document with the root request.

Payout notify is always POST with one field pg_xml, an XML document with the root response.

Redirect back is a redirect of the browser of the client: GET or a form submitted by the browser.

Freedom Pay waits for the answer for 30 seconds.

Signature check

The signature is pg_sig, the random string is pg_salt: see «Signature» in Merchant API Overview.

The script name is the last segment of the path of your URL: https://merchant.example.com/payment/result → result. A URL ending with / gives an empty script name.

Take all the fields that you received, except pg_sig, including your own parameters and the parameters of the query string of your URL.

Callbacks may get new fields: do not reject a callback because of a field that you do not know.

Rules for your server

The URLs must be public: without authorization, reachable from the internet.

Check the signature, then the order: pg_order_id, the amount and the currency.

The same callback can come more than once: process it by pg_payment_id only once, and give the same answer.

Answer quickly: do the long work after the answer.

If a callback does not come, request the status: Get payment status for payments, Get payout status for payouts.

Callbacks#

Method and format#

Signature check#

Rules for your server#

Callbacks

Method and format

Signature check

Rules for your server