Pay by card token

Creates a payment with a saved card by its token and returns the result in the same response.

The token is returned by Pay by card with pg_save_card = 1: pass it in pg_card_token together with the same pg_user_id.

If the card requires 3DS authentication, the response contains pg_3d_acsurl: redirect the client to it; the payment is completed with Pay by card: complete 3DS.

Uniqueness can be enabled for the merchant: then a repeated request with the same pg_order_id is rejected with an error.

Result

`pg_status`	`pg_3ds`	Meaning	Next step
`ok`	`0`	The payment is authorized.	One-step payment: nothing else is needed. Two-step payment (`pg_auto_clearing` = 0): capture the amount with `clearing` or release it with `cancel`.
`ok`	`1`	3DS authentication is required.	Redirect the client to `pg_3d_acsurl` and complete the payment with Pay by card: complete 3DS: see «3DS authentication» in Pay by card.
`pending`	—	The payment system has not returned the result yet.	Request the status with `status_v2` until it is final.
`error`	—	The request is rejected or the payment is declined.	See «Errors» below.

Payment flow

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, for example `pg_card_token` is not found or `pg_card_cvc` is not passed.	Fix the request.
`1201`	`pg_user_id` is not passed or differs from the user the card was saved for.	Pass the `pg_user_id` the card was saved for.
`11005`	`pg_amount` is not a number, is less than 0.01 or more than 99999999.	Fix the amount.
`1380`	The amount is too small: the commission is greater than the amount. The payment is created with the `error` status, `pg_payment_id` is returned.	Increase the amount or contact Freedom Pay.
`1100`	The signature is missing or invalid.	Check the signature: see Sync API Overview.
`1101`	`pg_merchant_id` is not found. The response is not signed.	Check the merchant ID.
`99081`	A payment with this `pg_order_id` already exists: uniqueness of the order ID is enabled for the merchant.	Pass a new `pg_order_id`.
`10000`	The payment could not be performed.	Repeat the request later.
Other codes	The payment is declined by the issuer or the payment system. `pg_payment_id` is returned.	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

Examples

Success3DS authentication required

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>1020101501496</pg_payment_id>
    <pg_status>ok</pg_status>
    <pg_3ds>0</pg_3ds>
    <pg_secure_details>F</pg_secure_details>
    <pg_card_id>138</pg_card_id>
    <pg_card_token>1b1654e2-461a-41aa-9ece-57906fc9b686</pg_card_token>
    <pg_auth_code>100689</pg_auth_code>
    <pg_reference>261020115735</pg_reference>
    <pg_datetime>2026-10-20T11:57:36+00:00</pg_datetime>
    <pg_salt>6QFIRWo0ZvGU4yHK</pg_salt>
    <pg_sig>658c3d222ec598ca37746bc2634d9314</pg_sig>
</response>

🟢200Error

Result#

Payment flow#

Errors#

Request example#

Request

Responses

Result

Payment flow

Errors

Request example