Mandarin

# 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 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

# 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”

# Connecting a self-employed person by TIN

POST https://api.psp.io/self-employed/v1/tin/bind

In the process of fulfilling a request from a merchant to Mandarin, a request is made to the Self-Employed Service (SEM), in which the TIN is transmitted. The SMZ for this request returns an identifier (for asynchronous communication) of the request, which is stored in the Mandarin system. After the SMZ processes the request from Mandarin asynchronously, a callback is made from the SMZ to Mandarin with the results of processing. After processing the callback request on the Mandarin side, a callback request is generated to the merchant with the result of processing the transmitted TIN.

API Request Description This endpoint allows you to bind a Taxpayer Identification Number (TIN) for a self-employed individual.

Request Body

  • inn (string, required): The individual's Taxpayer Identification Number.
  • callback_url (string, required): The URL to which the response will be sent.

Response

Upon successful execution, the response will include:

  • id (string): The unique identifier for the request.
  • inn (string): The Taxpayer Identification Number that was bound.

Example Request

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

Example Response

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

# Disconnecting a self-employed person by TIN

POST https://api.psp.io/self-employed/v1/tin/unbind

Unbind Self-Employed TIN

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

Request Body

  • inn (string, required): The taxpayer identification number to unbind.
  • callback_url (string, required): The URL to receive the callback after unbinding.

Response

  • id (string): The identifier for the unbinding process.
  • inn (string): The taxpayer identification number that was unbound.

Example Request

curl --location 'https://api.psp.io/self-employed/v1/tin/unbind' \
--header 'MID: 123' \
--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"
}

Example Callback Response

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

# Check State

GET https://api.psp.io/self-employed/v1/tin/

Get Self-Employed Details by TIN

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

Request

  • Method: GET
  • URL: https://api.psp.io/self-employed/v1/tin/{inn}

Response

  • id (string): The identifier for the unbinding process.
  • inn (string): The taxpayer identification number that was unbound.
  • status (string): The status of the request

Example Request

curl --location -g 'https://api.psp.io/self-employed/v1/tin/{inn}' \
--header 'MID: 123' \
--header 'Authorization: Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--data ''

Example Response

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

# Receipts

# Create a check

POST https://api.psp.io/self-employed/v1/receipts

Create Self-Employed Cheque

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

Request Body

  • inn (string, required): The INN (Taxpayer Identification Number) associated with the cheque.
  • price (number, required): The price of the cheque.
  • title (string, required): The title of the cheque.

Response

  • cheque_id (string): The unique identifier for the created cheque.
  • inn (string): The INN associated with the cheque.
  • status (string): The status of the request, see status list below.
  • message (string): Additional information or error message.
  • url (string): The URL to print the created cheque.

Example Request

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

Example Response

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

Example Response

{
    "cheque_id": "20172zyc9z",
    "inn": "123456789012",
    "status": "success",
    "message": "",
    "url": "https://lknpd.nalog.ru/api/v1/receipt/623406196579/20172zyc9z/print"
}

Status List

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

# Receipts Cancel

PATCH https://api.psp.io/self-employed/v1/receipts

Example Request

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

Example Response

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

# Get information on a check

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

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"
        }
    ]
}

← Routing →