Overview

Tips: the client pays a tip on the Freedom Pay page, the money goes to the card of an employee or a courier.

The card of the recipient is saved in advance; the tip is created with Create.

The result comes as a notification to post_link.

Signature and request headers are the same as in Invoice API: see Invoice Overview.

How it works

Save the card of the recipient: Save card without a charge with pg_template = tips and the recipient ID in pg_user_id.

Create a tip with Create: pass the recipient and the card token, get redirect_url.

Open redirect_url for the sender: the sender pays on the tips page.

Freedom Pay charges the card of the sender, sends the money to the card of the recipient and sends a notification to post_link.

A tip is paid once: if the payment fails, the tip gets the status error — create a new tip with a new external_id.

Tip statuses

Status	Meaning	Final
`new`	The tip is created and waits for the sender to pay.	No
`process`	The sender started the payment: it is in progress.	No
`completed`	The tip is paid and sent to the recipient's card.	Yes
`error`	The payment failed.	Yes

Notifications

If post_link is passed in Create, Freedom Pay sends a POST request to it when the tip reaches a final status: completed or error.

Field	Type	Description
`token`	string	Tip ID: `id` from the response of Create.
`status`	string	`completed` or `error`.
`amount`	string	Tip amount, for example `500.00`.
`external_id`	string	Tip ID in the merchant system.
`error_code`	integer	Error code of the failed payment. Only for `status = error`.
`error_message`	string	Error text of the failed payment. Only for `status = error`.

{
    "token": "019a3b2c-7d4e-7f60-8a1b-2c3d4e5f6a7b",
    "status": "completed",
    "amount": "500.00",
    "external_id": "tip1001"
}

The notification is not signed.
Answer with HTTP 200 within 10 seconds: any other code counts as a failure, and the notification is sent again, up to 3 attempts.
The same notification can arrive more than once: process it by token and status.

How it works#

Tip statuses#

Notifications#

How it works

Tip statuses

Notifications