Create payment in a payment frame

Creates a payment and returns the link to the payment frame: pg_redirect_url. Show it in an iframe on your page: the frame contains the bank card form, the client pays without leaving your page.

The payment frame is available after Freedom Pay enables it for the merchant: contact your account manager. If it is not enabled, pg_payment_route is ignored and the payment opens on the standard payment page, see Create payment.

The look of the frame (colours, font, Apple Pay and Google Pay buttons, phone and email fields) is set for the merchant by Freedom Pay: contact your account manager.

If a template is enabled for the merchant or pg_template is passed, the payment opens on the template page, not in the frame, see Create payment with a payment page template.

The result of the payment comes to pg_result_url, see Result notify. After the payment the client is returned to pg_success_url or pg_failure_url, see «Return of the client» below.

If the payment result is not received, get it with Get payment status.

Parameters without the pg_ prefix are passed back to pg_check_url and pg_result_url unchanged. Give them unique names that do not start with pg_.

The frame accepts only card numbers that pass the Luhn check. Test cards for the frame: 4111111111111111 — success without 3DS, 4916307416334310 — success with 3DS, 5335215945367703 — declined.

pg_payment_method and pg_timeout_after_payment are not used in the frame.

Payment frame flow

Return of the client

After a successful payment the client is returned to pg_success_url with pg_order_id, pg_payment_id, pg_salt and pg_sig. pg_sig is calculated with the script name equal to the last segment of the pg_success_url path.

After a declined payment the client is returned to pg_failure_url with pg_order_id, pg_failure_code, pg_failure_description and your parameters without the pg_ prefix. These parameters are not signed: confirm the result with pg_result_url or Get payment status.

If pg_success_url or pg_failure_url is not passed, the URL from the merchant settings is used. If there is none, the result is shown in the frame.

A declined payment is closed: to let the client pay again, create a new payment.

The HTTP method of the return is set by pg_success_url_method and pg_failure_url_method.

Recurring payments

Recurring payments are repeat payments where a recurring profile is created during the first payment. Subsequent payments are made according to this profile.

To create a profile, the following parameters are passed in init_payment: pg_recurring_start — profile creation, pg_recurring_lifetime — validity period. If pg_recurring_lifetime exceeds the card's expiration date, the profile remains active until the card expires.

The profile number (pg_recurring_profile_id) is passed in the Result URL. It is also supported for Apple Pay and Google Pay.

For connection, please contact the manager.

Result

`pg_status`	Meaning	Next step
`ok`	The payment is created.	Show `pg_redirect_url` in an `iframe` and wait for the result at `pg_result_url`.
`error`	The request is rejected.	See «Errors» below.

Errors

The HTTP status is always 200; the error is returned in pg_error_code and pg_error_description. Error responses are not signed.
See Error codes.

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_status>ok</pg_status>
    <pg_payment_id>1023122203573</pg_payment_id>
    <pg_redirect_url>https://customer.freedompay.kz/v1/merchant/12345/card/payment?pg_payment_id=01a169e4-0f7d-72be-b225-19fed7fcfcba</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>qDuCuUT8UKAL6DXB</pg_salt>
    <pg_sig>a4951edf295f6b664383575f0f6ddddf</pg_sig>
</response>

🟢200Error

Create payment in a payment frame

Payment frame flow#

Return of the client#

Recurring payments#

Result#

Errors#

Request example#

Request