Create

Creates a tip: the sender pays it on the Freedom Pay tips page, the money goes to the recipient's card.

Save the card of the recipient first: Save card without a charge with pg_template = tips.

Open redirect_url from the response for the sender.

Pass post_link: the result comes only as a notification, there is no method to get the status. See Tips Overview.

A tip is paid once: if the payment fails (status = error), create a new tip with a new external_id.

Sign the request with X-JWS-Signature: see Invoice Overview.

Tip flow

Result

HTTP	`status`	Meaning	Next step
`200`	`new`	The tip is created.	Open `redirect_url` for the sender.
`200`	any	A tip with this `external_id` already exists: it is returned with its current status, `redirect_url` only for `new`.	Use the returned tip.
`200`	`error` with `error_code`	Internal error.	Repeat the request later.
`401`, `404`, `422`	`error`	The request is rejected.	See «Errors» below.

Errors

HTTP	`error_code`	When	What to do
`401`	`12000`	The API user is not linked to a merchant.	Contact Freedom Pay support.
`401`	`9998`	The signature is invalid.	Check the signature: see Invoice Overview.
`404`	`12103`	The recipient card is not found: no approved card with this `card_token` is saved for `recipient.user_id`.	Check `recipient`; save the card with Save card without a charge.
`422`	`9403`	The X-JWS-Signature header is missing.	Pass the signature.
`422`	`0`	A field is missing or invalid. `error_description` names the field.	Fix the request.

Request

Header Params

Body Params application/jsonRequired

Example

{
    "amount": 500,
    "currency": "KZT",
    "external_id": "tip1001",
    "main_order": {
        "external_id": "order1001",
        "amount": 5000
    },
    "recipient": {
        "user_id": "courier-042",
        "card_token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    },
    "sender": {
        "user_id": "customer-777"
    },
    "back_url": "https://merchant.example.com/back",
    "post_link": "https://merchant.example.com/callback"
}

Responses

🟢200Success

application/json

Bodyapplication/json

Example

{
    "id": "019a3b2c-7d4e-7f60-8a1b-2c3d4e5f6a7b",
    "status": "new",
    "created_at": "2026-10-30T10:00:42+00:00",
    "redirect_url": "https://customer.freedompay.kz/tips?token=019a3b2c-7d4e-7f60-8a1b-2c3d4e5f6a7b",
    "dt": "2026-10-30T10:00:42+00:00"
}

🟠401Unauthorized

🟠404Not Found

🟠422Unprocessable Entity

Tip flow#

Result#

Errors#

Request

Responses

Tip flow

Result

Errors