Overview

Installment: the client buys now and pays in installments or with a loan from a partner bank.

You create an application, the client completes it on the Freedom Pay page by the link, the bank decides.

Signature and request headers are the same as in Invoice API: see Invoice Overview. The phone number of the client is passed encrypted: see «Phone encryption».

Installment is in development: the methods may change.

How it works

Get the banks and their programs with Get partners and show the terms to the client.

Create an application with Create application: the order, the encrypted phone number, callback_url. Get redirect_url.

Open redirect_url for the client: the client gives consent, chooses a bank offer and signs the agreement with the bank.

Follow the status with Get application status: when it is signed, hand over the goods and set delivered with Change application status.

To cancel an application or to request a refund, use Change application status.

Methods

Method	What it does
Get partners	Returns the banks, their amount limits and programs.
Create application	Creates an application and returns the link for the client.
Get application status	Returns the status of an application.
Change application status	Cancels an application, confirms the delivery or requests a refund.
Application status notification	Notification about the status of an application (in development).

Application statuses

Status	Meaning	Final
`new`	The application is created: the client has not opened the link yet or has not given consent.	No
`consent_signed`	The client gave consent to the data check.	No
`pre_scoring_approved`	The preliminary check is passed: the client chooses a bank offer.	No
`pre_scoring_rejected`	The preliminary check is failed.	Yes
`bank_selected`	The client chose a bank and a program: `approved_amount` and `bank_code` are returned.	No
`scoring_rejected`	The bank declined the application.	No
`signed`	The client signed the agreement with the bank: hand over the goods, then set `delivered`.	No
`delivered`	The merchant confirmed the delivery with Change application status.	No
`canceled`	The merchant cancelled the application with Change application status.	Yes
`canceled_customer`	The client cancelled the application.	Yes
`expired`	The application expired: the client did not complete it in time.	Yes
`refund`	The merchant requested a refund with Change application status.	No
`refunded`	The refund is completed.	Yes

The transitions between statuses: see Get application status.

Response headers

Header	Value
`X-Request-Status`	`success` or `error`.
`X-Datetime`	Response date and time, ISO 8601.

Errors

The body of an error: error_code and error_description. The texts of validation errors are in Russian.

HTTP	`error_code`	When
`400`, `422`	`1001`	The request is invalid: `X-Request-Id`, a field, or the encrypted phone number.
`401`	`3001`	The signature is invalid.
`401`	`3002`	`X-JWS-Signature` is missing.
`404`	`4001`	The application is not found.
`409`	`2001`	The status transition is not allowed.
`409`	`2002`	The application is in a final status.
`500`, `503`	`5000`	Internal error: repeat the request later.

Phone encryption

Pass customer.phone in Create application as a compact JWE:

Parameter	Value
Payload	Phone number, `998XXXXXXXXX`.
`alg`	`PBES2-HS512+A256KW`
`enc`	`A256GCM`
`p2c`	Number of iterations: from 1000 to 600 000.
Key	Your secret key: the key you sign requests with.

Only alg, enc, p2s, p2c, kid, typ and cty are allowed in the JWE header.

Python

Library: jwcrypto.

PHP

Libraries: web-token/jwt-library, spomky-labs/aes-key-wrap.

How it works#

Methods#

Application statuses#

Response headers#

Errors#

Phone encryption#

Python#

PHP#

How it works

Methods

Application statuses

Response headers

Errors

Phone encryption

Python

PHP