# Self-employed

This service uses Oauth2 authorization and authentication. First you have to request an access_token with specific permissions using your application Oauth credentials. Then use this access_token as a Bearer token for authorization to the service.

# Entry points

Combat (production) environment for authorization: https://accounts.mandarinbank.com/ (opens new window) Production environment for requests: https://api.psp.io/ (opens new window)

Required permissions: - self-employed:cheques.register self-employed:tin.bind self-employed:cheques.cancel

Besides that you should pass your merchant_id to headers as MID (example MID: YOUR_MERCHANT_ID)

# Auth

# Auth credentials

Please request Support Service (opens new window) for your client_id and client_secret to get an access_token

# Scope

Required scopes: self-employed:cheques.register self-employed:tin.bind self-employed:cheques.cancel

OAuth Token Request:

POST https://accounts.mandarinbank.com/oauth/token/

This endpoint allows the client to obtain an access token by exchanging its credentials. It uses the HTTP POST method to https://accounts.mandarinbank.com/oauth/token/.

Request Body: The request body should be of form-data type.

# Request authentication

Each request must be authenticated using a token (access_token) obtained according to the OAuth 2.0 protocol for applications. The token is valid for 36,000 seconds (10 hours). If the validity period has expired, the token must be requested again.

Request for a token:

Includes the required form-data parameters that are passed in the request body (the application.client_id and application.client_secret parameters are unchanged for the application and are stored on the client side).

Parameter	Description	Example
grant_type	Authorization grant (always equal to `client_credentials`).	client_credentials
client_id	Client ID (equal to the `application.client_id` value provided by Mandarin).	VvPtlhcyldKtkuoUWY42 pErdrj4er2AwFoBWrn8n
client_secret	Client secret key-password (equal to `application.client_secret` value provided by Mandarin).	uQfOIMsltZYL8x3XMqUGP5 iFM59PyFnKlN0UmD3Ihre2 Ry3AGazUAv5jPdUI4dBJqV 0Of6b9GFvWvzGahYnq2aVV xkxn9n4qWF57FP0C01Kp6l EtajhfYv3UZ2f4pAZ7
scope	Requested scopes (access areas): for example, self-employed:cheques.register - “Registration”. The separator is a space. You can request any list of scopes, and the response will return the list of requested scopes, which may be provided for a given application.	self-employed:cheques.register

curl --location --request POST 'https://accounts.mandarinbank.com/oauth/token/' \
--form 'grant_type=client_credentials' \
--form 'client_id=VvPtlhcyldKtkuoUWY42pErdrj4er2AwFoBWrn8n' \
--form 'client_secret=uQfOIMsltZYL8x3XMqUGP5iFM59PyFnKlN0UmD3Ihre2Ry3AGazUAv5jPdUI4dBJqV0Of6b9GFvWvzGahYnq2aVVxkxn9n4qWF57FP0C01Kp6lEtajhfYv3UZ2f4pAZ7' \
--form 'scope=self-employed:cheques.register self-employed:tin.bind self-employed:cheques.cancel'

Answer:

Parameter	Description	Example
access_token	Token (access key).	VnuxZiW14mXBedDeZO7d W7GBmzPxMn
expires_in	Token validity period (in seconds). Always equal to 36,000 seconds (10 hours).	36000
token_type	Token type (always equal to `Bearer`).	Bearer
scope	Allowed scopes (access areas): for example, self-employed:cheques.register - “Registration”. The delimiter is a space. You can request any list of scopes, and the response will return the list of requested scopes that can be provided for this application.	self-employed:cheques.register self-employed:tin.bind self-employed:cheques.cancel

{
     "access_token": "VnuxZiW14mXBedDeZO7dW7GBmzPxMn",
     "expires_in": 36000,
     "token_type": "Bearer",
     "scope": "self-employed:cheques.register self-employed:tin.bind self-employed:cheques.cancel"
}

Token Usage:

Indicated in the headers of each request, in the Authorization field, after the reserved word Bearer.

Authorization:Bearer VnuxZiW14mXBedDeZO7dW7GBmzPxMn

# Binding

What needs to be done for the service to work:

The self-employed downloads the My Taxes app in AppStore (opens new window), Google Play (opens new window) or register on the FTS website (opens new window).
You use the API to send a request to Mandarin with the INN of the self-employed person in order to obtain consent from the self-employed person for the following actions:

"Correction of information about my income submitted by a partner" - transfer of information about the income received to the Federal Tax Service.
"Receiving information on my income" - receiving information from the Federal Tax Service on the total amount of income for the period to control the limit of 2.4 million rubles per year.
"Income reflection on my behalf" - transfer of a cash receipt from a self-employed person to you (the paying company).

The self-employed person in the "Partners" section approves your request for action from the previous paragraph.

# Connecting a self-employed person by TIN

Request Parameters:

Parameter	Mandatory	Description
`inn`	Yes	INN of the self-employed
`callback_url`	Yes	The URL to which the response will be sent.

Example Request:

curl --location 'https://api.psp.io/self-employed/v1/tin/bind' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data '{
    "inn": "123456789012",
    "callback_url": "https://webhook.site/28b30c34-9fbd-4e98-b1b7-e20a999d530b"
}'

If successful, the response will include:

Parameter	Description
`id`	Request ID
`inn`	INN of the self-employed

Response:

{
  "id": "3ab4e73d-a197-4a2f-9b92-69ef07468b04",
  "inn": "185796979287"
}

Callback:

{
   "id": "80cf6b02-795f-486f-a515-562a41a87429",
   "inn": "123456789012",
   "status": "ACTIVE"
}

Callback Parameters:

Parameter	Description
`id`	unique request ID
`inn`	INN of the self-employed
`status`	Self-employed status, see the list of statuses

# List of statuses

Status	Description
ACTIVE	Is an active verified self-employed person
NOT_SELF_EMPLOYEE	Not self-employed
REVOKED_EXPLICITLY	Self-employed person is untied
BINDING_IN_PROGRESS	In the process of confirming self-employed status and issuing permission to our system in "My Tax"
BINDING_IN_PROGRESS	In the process of revoking “self-employed status” and permissions from our system in “My Tax”

# Disconnecting a self-employed person by TIN

This endpoint allows you to unbind a self-employed taxpayer identification number (TIN).

Request Parameters:

Parameter	Mandatory	Description
`inn`	Yes	INN of the self-employed
`callback_url`	Yes	The URL to which the response will be sent.

Example Request:

curl --location 'https://api.psp.io/self-employed/v1/tin/unbind' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data '{
    "inn": "123456789012",
    "callback_url": "https://webhook.site/28b30c34-9fbd-4e98-b1b7-e20a999d530b"
}'

Example Response:

{
  "id": "1b45f664-337c-4441-8f9b-ad018a9508c6",
  "inn": "185796979287"
}

Callback:

{
    "id": "9a79c2a6-d9f7-4613-a1ae-c31981e61eb9",
    "inn": "185796979287",
    "status": "REVOKED_EXPLICITLY"
}

Response parameters

Parameter	Description
`id`	unique request ID
`inn`	INN of the self-employed
`status`	Self-employed status, see the list of statuses

# Check State

This endpoint retrieves self-employed details based on the Taxpayer Identification Number (TIN).

Example Request:

curl --location -g 'https://api.psp.io/self-employed/v1/tin/123456789012' \
--header 'MID: 1234' \
--header 'Authorization: Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data ''

Example Response:

{
  "id": "9a79c2a6-d9f7-4613-a1ae-c31981e61eb9",
  "inn": "123456789012",
  "status": "ACTIVE"
}

Response parameters:

Parameter	Description
`id`	unique request ID
`inn`	INN of the self-employed
`status`	Self-employed status, see the list of statuses

# Receipts

# Create a receipt

This API endpoint allows you to create a self-employed cheque.

Request Parameters:

Parameter	Mandatory	Description
`inn`	Yes	Self-employed person's INN
`price`	Yes	Price of the product/service
`title`	Yes	The name of the product/service in the receipt

Example Request:

curl --location 'https://api.psp.io/self-employed/v1/receipts' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data '{
    "inn": "123456789012",
    "price": 100,
    "title": "Purchase of goods"
}'

Example Response:

{
 "cheque_id": "20172zyc8z",
 "inn": "123456789012",
 "message": "",
 "session_id": "edccadd7-e5f9-4de2-8088-64e6adf0959b",
 "status": "success",
 "url": "https://lknpd.nalog.ru/api/v1/receipt/623406197779/20172zyc8z/print ",
 "title": "Purchase of goods"
}

Response parameters:

Parameter	Description
`cheque_id`	Unique identifier of the created receipt
`inn`	INN of the self-employed
`message`	Additional information or error message
`session_id`	id of the created receipt
`status`	Request status, see the list of statuses
`url`	The URL for printing the created receipt
`title`	The name of the product/service specified in the request

Status List receipt:

Status	Description
success	Receipt is created
failed	Failed to create a receipt, check message for details

# Receipts Cancel

A method for canceling a created receipt.

Example Request:

curl --location --request PATCH 'https://api.psp.io/self-employed/v1/receipts' \
--header 'MID: 1234' \
--header 'Authorization: Bearer Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data '{
    "cheque_id": "20172zyc8z",
    "inn": "123456789012",
    "code": "REFUND"
}'

Example Response:

{
  "cheque_id": "20172zyc8z",
  "inn": "123456789012",
  "status": "cancelled",
  "url": "https://lknpd.nalog.ru/api/v1/receipt/623406197779/20172zyc8z/print"
}

# Get information about the receipt

Request for check data by its ID, which was received during creation.

Example Request:

GET https://api.psp.io/self-employed/v1/receipts/<cheque_id>

Example Response:

{
    "cheque_id": "test-123456789012-cheque-id",
    "inn": "123456789012",
    "message": null,
    "session_id": "0c518aea-2807-406a-830d-959b55a05c3e",
    "status": "success",
    "url": null,
    "title": "Payment for the order №1234"
}

Response in case the receipt is not found

{
    "errors": [
        {
            "error_code": "NOT_FOUND",
            "parameter": "cheque_id",
            "description": "R\ne\nc\ne\ni\np\nt\n \nn\no\nt\n \nf\no\nu\nn\nd\n \nt\ne\ns\nt\n-\n1\n2\n3\n4\n5\n6\n7\n8\n9\n0\n1\n2\n-\nc\nh\ne\nq\nu\ne\n-\ni\nd"
        }
    ]
}

← Payouts Routing →