Mandarin

# Lender API

# End-to-end API

This scheme of interaction implies a full service of the borrower on Mandarin side - from registration and signing up to subsequent payment and work with delinquency

# Introduction

XML API Smart Contract Processor (aka SCP) provides the developer with applications the ability to automatically conclude unified contracts when through the Mandarin platform.

# - Entry point

SCP API entry point:

https://api.psp.io/life-backend/scpapi

The same entry points are used for development, testing, and production operation.
At the same time you need to request a test store setup to send requests during development and testing.

# - Partner software entry point

To integrate with the system, the partner company must create its own point input that provides the SCP API operation (opcodes 790-796).

When you start working together, the partner's software is registered with the SCP, which must be able to transmit an information request to the partner software. Information about The address of the entry point to the partner's software is transmitted to an authorized Mandarin employee for inclusion in the whitelist (range inclusion is possible).

# - Request sending method

XML requests are sent and received using the HTTP POST method, specifying Content-Type: application/xml. The body of the http-request contains the request to the API, which must represent a valid XML beginning with the descriptor <?xml version="1.0" encoding="utf-8"?>.

In case of sending a query from the PHP environment, it is recommended to use the following code sample:

\$url = (SCP server URL);
\$ch = curl_init();
curl_setopt(\$ch, CURLOPT_URL, \$url);
curl_setopt(\$ch, CURLOPT_POST, 1);
curl_setopt(\$ch, CURLOPT_POSTFIELDS, \$xml);
curl_setopt(\$ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt(\$ch, CURLOPT_HEADER, false);
curl_setopt(\$ch, CURLOPT_CONNECTTIMEOUT, 120);
curl_setopt(\$ch, CURLOPT_TIMEOUT, 120);
curl_setopt(\$ch, CURLOPT_HTTPHEADER, array('Content-Type: text/xml'));
\$response = curl_exec(\$ch);
curl_close(\$ch);
return \$response;

Where:

  • \$ch - cURL descriptor;

  • \$xml - the variable containing the generated XML query.

# - Interaction diagram

SCP Workflow Diagram - for creditor

# - Workflow of contract conclusion in SCP API

Currently, the SCP API implements a single type of conclusion process contract - consumer credit (contract_type=1). It involves the following components:

  1. Payment page (PS) - a frame on the online store's website (merchant), which opens with the "Pay on Credit" button and offers user (customer) to enter their email as a login to the following steps.

  2. a personal account (LC) on the Mandarin website, which allows you to fill out (and control) of the user questionnaire, selection of a suitable credit offer and Signing a loan agreement with the chosen creditor.

  3. payment gateway - the system server that provides for conducting and accounting payments (both from the buyer's card and the lender's current account).

  4. information gateway - the system server that provides storage and output Service information about all entities in the system (e.g., scoring parameters of the buyer or the current account of a particular creditor).

  5. contract gateway - the system server that supports the conclusion procedure contracts through the SCP API.

The process of processing consumer credit consists of the following steps:

1. Registration of the application for a consumer loan, filling out the borrower questionnaire

2. Collection of credit offers on the application

In the LOC the user checks the existing application (from which store, for which amount, etc.), fills in the missing fields (e.g., the maximum loan rate) and confirms his/her intention to obtain a loan (the "Get loan offers" button). The Personal Computer sends a request to the contract gateway (opcode 790) containing the supplemented information about the application. The request is transferred from the unconfirmed status to the active one, a notification is sent to the creditors (the same request, with opcode 790, but on behalf of the system) in order to collect credit offers. If the store has an activated online application, the application will include a photo or scans of documents (two pages of the passport and a photo of the borrower with the passport).

Then there is a pause during the period set in the system (from 30 seconds to 10 minutes), during which lenders have the opportunity to send packages of credit offers to the system (opcode 791). At the end of the collection period, the borrower chooses one of them, for which he or she signs a loan agreement.

If necessary, the lender can request scans of all documents ever uploaded for the application (including for previous attempts where the application was rejected on the grounds of "Unsatisfactory photo quality") by requesting opcode 796.

3. Signing the loan agreement

As part of the credit proposal there is a field "link to the text of the agreement". The text of the agreement is displayed on the screen, the user has the opportunity to sign it via SMS (to the phone number specified in the user questionnaire). By pressing the "Sign" button, the Personal Computer checks the user's solvency by Preauthorization of the initial payment amount (request to the payment gateway). If the initial payment is not stipulated in the credit offer, the amount of 1 ruble is preauthorized, followed by cancellation.

If the creditor, by virtue of the accepted order of the loan requires information about the successful preauthorization of the initial payment, the LC produces its notification (opcode 792 PutProposal, Result=Preauth).

If preauthorization is successful, the Personal Computer sends a request to the contract gateway (opcode 794, GetConfirm) to send the pin code via SMS. The contract gateway checks matches the request parameters (ContractorSiteID and ContractProposalID) with the available offers and, if matched, generates a unique contract identifier - ContractID - which is a concatenation of the request number, ContractorSiteID and ContractProposalID extended to 10 characters (example: 0000000123-999999-0001-9876). Note: *In the current version of SCP this code is for reference, in the future it will become the main identifier when working with signed contracts.

Having received an SMS with the pin-code, the user enters it in the corresponding screen form. The Personal Computer sends a request to the contract gateway (opcode 794, PutConfirm) containing the received pin code. In case of positive response (message=OK) of the contract gateway, the contract is considered signed.

The contract gateway can work in two modes: either it sends an SMS on its own, or it forwards the 794 request to the creditor to generate the pin code on his side. In the first case, after the pin code is matched, the contract gateway sends a notification to the creditor about signing the contract and waits for his confirmation (consent); in the second case, it sends the received pin code and also waits for confirmation. In both cases, the 794 PutConfirmation is the lender's consent to the issuance of the loan.

After signing the credit agreement, the contract gateway sends a collab to the payment gateway containing the payment transaction number and the success status, which means that the payment to credit the amount specified in the transaction is completed. The payment gateway receives information about the status change (by regular CheckState polling or via colback) and notifies the store about the payment.

4. Payment of the initial payment and the body of the loan

In case the initial payment was preauthorized at the previous stage, the LOC writes off this amount in favor of the store. Then the LOC writes off the credit amount from the creditor's account in the system.

View the current status of loan payments

# Description of the contract gateway API

# - List of contract gateway operations

Transaction (opcode) Actions of the contract gateway Actions of the SCP client subsystem (on the lender side)
790 ContractRequest Registers the loan application.
Combines the application with borrower data obtained from the information gateway. In case the store transmits online applications, stores photos of documents. Transmits the application including the loan parameters and the borrower questionnaire to the lenders.		 Accepts the request and calls the offer preparation procedure Required to meet the deadline specified in the ActualUntil field.
791 ContractProposals Accepts the request, saves the received offers in the information gateway Transmits loan offers or refusals. There can be several offers in one information packet. In the case of rejection, the reason for rejection is reported (RejectCause field)
794 ContractSign Accepts the request, generates a pin code and transmits it via SMS to sign the contract. After signing, notifies the lender that the borrower has signed the contract. Receives a message about signing the contract and synchronously confirms its conclusion. The response message=OK means that the contract comes into force and the loan funds can be transferred from the lender's account to the online store's account.
796 DocumentScan Upon request from the lender (i.e., optional), returns scans of all documents ever uploaded for the application. If necessary, uses this information to decide on a loan offer (791 request).

# - General format of SCP API requests and responses

Queries in the system are XML strings containing the standard headline:

<request>
    <Opcode>790</Opcode>
    <SiteID>111111-1111</SiteID>
    <timestamp>1471836223</timestamp>
    <hash>5b504cc034c09160fadc4950b287aed3</hash>
    <contract_type>1</contract_type>
    <Action>GetProposals</Action>
    ...
</request>

Here:

Opcode - one of the operating codes listed above

SiteID - identifier of the store and/or lender, in the format: six digits - customer/organization code, four digits - website (web service) code

timestamp - unix-timestamp of the moment the request was made on the calling system (i.e., the number of seconds elapsed since 1.01.1970) used to calculate hash and access authorizations

hash - check value for authorization, calculated by the formula:

hash = md5('secret-Opcode-SiteID-timestamp'), where secret is the secret code, assigned to a particular store (SiteID)

Action - symbolic code of the specific action performed within the operation

The header is followed by the changing elements of the query, as described below schemes.

The Responses in the SCP API follow the following format:

<response>
    <date>2016-11-15T05:08:43+00:00</date>
    <message>OK</message>
    <code>000</code>
    <result>
    ...
</result>
</response>

The code 000 and message=OK indicate successful completion of the operation. In the case of an error returns a code other than 000, and the message parameter returns an error message.

The result field contains a nested XML with the results of the operation, the contents which is different for different opcodes.

# - Request for Proposals (Opcode 790 ContractRequest)

In the first step, the main application forwards the call to the SCP, with the transfer of the borrower and the required conditions of the contract. In the second step, SCP sends out requests to the creditor systems, according to the available roster of partners.

[standard header, SiteID = seller]

Action = GetProposals

  1. ContractRequest

1.1. ContractType - classifier string, always equal to 1

1.2. MerchantSiteID - store ID in the system (duplicates SiteID from header in the case of a direct request from the store to the gateway, but in most cases, the request is made on behalf of the payment system, so its SiteID and MerchantSiteID do not match)

1.3. ContractRequestID - identifier of the contract request. Automatically assigned by the infogate (i.e., it is not passed in the request the store, and is transferred only to the creditor)

1.4. Created - the moment of request creation in the format yyyyy-MM-dd hh:mm:ss+hh:mm

1.5. ActualUntil - the deadline for the offer, in the same format

1.6. ReservedUntil - the deadline for reserving a good or service, including in the same manner

1.7. OrderID - unique order identifier within the store (optional)

1.8. OrderDescription - order description (list of goods, services, or other text; optional)

1.9. Status - classifier string (reserved)

1.10. TransactionSiteID - identifier of the site that initiated the credit payment

1.11. TransactionID - transaction identifier in the payment gateway

1.12. Repeated - sign of repeated request (in case it has already been disclaimer)

1.13. RegionIP - region of the applicant set by IP

1.14. LoanSpecification - specific parameters relevant to a particular of the contract; multiple sections, because one application may contain several different sets of conditions, for example, several different loan terms

1.14.1. Maturity - credit term in months; can be blank, in which case the creditor must send proposals for all acceptable terms

1.14.2. Amount - credit amount *)

1.14.3. MinimalFirstPayment - minimum initial payment in percent of amount (0 to 100). Optional.

1.14.4. MaximalYearPercent - the maximum total price of the loan in annual percentage

1.14.5. Purpose - credit purpose (optional)

1.14.6. ProductType - type of credit (optional)

1.15. Person - Information about the physical person - the borrower. Hereinafter is identified by PersonID. The fields are described in the schemas Person, Document and Address in Section 4.

1.16. Card - credit card information (optional)

1.16.1. Holder.

1.16.2. Number.

1.16.3. Expiration

1.17. ScanDocumentsAvailable - indicator if scans of the borrower's documents are uploaded (for online application).

1.18. DocumentScan - a section that stores scans of the borrower's documents (for online processing).

1.18.1. Type - document type. Possible values: passport_main (passport page with photo); passport_registration_address (passport page with permanent registration); selfie (borrower's selfies with the document).

1.18.2. Filename - file name and extension.

1.18.3. CreatedAt - date of file download.

1.18.4. AttemptsCount - counter of attempts to submit a document scan.

1.18.5. Data - an image (up to 7 MB in size) encoded in Base64.

Note. Credit amount in this document is the total cost of a good (service). It consists of:

  1. the initial payment coming from the buyer's card, and

  2. the loan coming from the lender's account.

In all specifications, the loan amount includes the initial payment, so it is necessarily accompanied by a second parameter - the amount of the initial payment as a percentage.

Example of a complete request sent by a contract gateway to creditors:

<request>
    <Opcode>790</Opcode>
    <SiteID>111111-1111</SiteID>
    <timestamp>1479178288</timestamp>
    <hash>22e636af803be898a79b68e23792d633</hash>
    <contract_type>1</contract_type>
    <Action>GetProposals</Action>
    <ContractRequest>
        <AttemptsCount>1</AttemptsCount>
        <ContractType></ContractType>
        <MerchantSiteID>111111-1111</MerchantSiteID>
        <ContractRequestID>59</ContractRequestID>
        <Created>2016-11-07 15:30:00+00:00</Created>
        <ActualUntil>2016-11-15 07:52:27.793000+00:00</ActualUntil>
        <ReservedUntil>2016-11-20 09:00:00+00:00</ReservedUntil>
        <OrderID>003</OrderID>
        <OrderDescription>something</OrderDescription>
        <Status></Status>
        <TransactionSiteID></TransactionSiteID>
        <TransactionID></TransactionID>
        <Repeated></Repeated>
        <RegionIP></RegionIP>
        <LoanSpecification>
            <Maturity>3</Maturity>
            <Amount>50000.0</Amount>
            <Purpose></Purpose>
            <ProductType></ProductType>
            <MinimalFirstPayment></MinimalFirstPayment>
            <MaximalYearPercent>60.0</MaximalYearPercent>
        </LoanSpecification>
        <Person>.
            <rucitizenship>True</rucitizenship>
            <OGRNIP>303456789012345</OGRNIP>
            <DocScan>
                <ScanNum>1</ScanNum>
                <scanFileID></scanFileID>
                <ScanName> first page</ScanName>
                <DocumentType>
                    <RFNSPDocid>21</RFNSPDocid>
                </DocumentType>
            </DocScan>
            <DocScan>.
                <ScanNum>2</ScanNum>
                <scanFileID></scanFileID>
                <ScanName> second page</ScanName>
                <DocumentType>
                    <RFNSPDocid>21</RFNSPDocid>
                </DocumentType>
            </DocScan>
            <fotoFileID></fotoFileID>
            <Document>.
                <Docnum>543987</Docnum>
                <Docissuingdate>2011-01-01</Docissuingdate>
                <Docissuercode>770-001</Docissuercode>
                <Docseria>7709</Docseria>
                <DocumentType>
                    <RFNSPDocid>21</RFNSPDocid>
                </DocumentType>
                <Docissuer> Department of the Federal Migration Service of Russia for
GORE. MOSCOW</Docissuer>.
            </Document>.
            <Document>.
                <Docnum>987654</Docnum>
                <Docissuingdate>2015-08-17</Docissuingdate
                <Docissuercode></Docissuercode>
                <Docseria>111</Docseria>
                <DocumentType>
                    <RFNSPDocid>22</RFNSPDocid>
                </DocumentType>
                <Docissuer></Docissuer>
            </Document>.
            <Email>sharikov\@narod.com</Email>
            <Agreement>
                <microcreditLiability>True</microcreditLiability
            </Agreement>
            <Phone>+79024731438</Phone>
            <FinanceInfo>
                <MainIncome>120000</MainIncome>
                <LivingStatus>
                    <Code>1</Code>
                </LivingStatus>
                <CreditExpenses> 150,000</CreditExpenses>
                <WageDate>2016-09-30</WageDate>
            </FinanceInfo>
            <CardInfo>
                <BIN>405060</BIN
                <Cardtype>
                    <Code>1</Code>
                </Cardtype>
                <Cardholder>POLIGRAF SHARIKOV</Cardholder>
                <Expiration>2018-05</Expiration>
                <PAN>1234</PAN
            </CardInfo>
            <Name> Polygraph</Name>
            <Car>.
                <Brand>Ford</Brand
                <RuCarNumber>A123AA199</RuCarNumber>
                <ProductionYear>2008</ProductionYear>
                <Model>Focus</Model>
            </Car>.
            <Car>.
                <Brand>Ford</Brand
                <RuCarNumber>A124AA199</RuCarNumber>
                <ProductionYear>2015</ProductionYear>
                <Model>Kuga</Model>
            </Car>.
            <Address>.
                <city_type> city</city_type>
                <state_name>-</state_name>
                <house> e. 10</house>.
                <street_name> Garden B.</street_name>
                <street> B. Sadovaya Street</street
                <np_type>-</np_type>
                <building_name>-</building_name>
                <city> Moscow</city>.
                <AddressType>
                    <Code>2</Code>
                </AddressType>
                <house_name>10</house_name>
                <reg_date>2010-01-01</reg_date>
                <state>-</state>
                <np>-</np>
                <flat> sq. 20</flat>.
                <region_name> Moscow</region_name>
                <flat_type> apartment</flat_type>
                <rupostindex>125047</rupostindex>
                <flat_name>20</flat_name>
                <street_type> street</street_type>
                <city_name> Moscow</city_name>
                <house_type> house</house_type>
                <building>-</building>
                <state_type>-</state_type>
                <region> Moscow</region>
                <BuildingClass>
                    <Code>3</Code>
                </BuildingClass>.
                <np_name>-</np_name>
                <rawaddress>Moscow, Bolshaya Sadovaya, 10, sq. 20</rawaddress>.
                <building_type>-</building_type>
                <region_type> city</region_type>
                <living_date>2011-07-25</living_date>
            </Address>.
            <Address>.
                <city_type> city</city_type>
                <state_name>-</state_name>
                <house> e. 10</house>.
                <street_name> Garden B.</street_name>
                <street> B. Sadovaya Street</street
                <np_type>-</np_type>
                <building_name>-</building_name>
                <city> Moscow</city>.
                <AddressType>
                    <Code>1</Code>
                </AddressType>
                <house_name>10</house_name>
                <reg_date>2010-01-01</reg_date>
                <state>-</state>
                <np>-</np>
                <flat> sq. 13</flat>
                <region_name> Moscow</region_name>
                <flat_type> apartment</flat_type>
                <rupostindex>125047</rupostindex>
                <flat_name>13</flat_name>
                <street_type> street</street_type>
                <city_name> Moscow</city_name>
                <house_type> house</house_type>
                <building>-</building>
                <state_type>-</state_type>
                <region> Moscow</region>
                <BuildingClass>
                    <Code>1</Code>
                </BuildingClass>.
                <np_name>-</np_name>
                <rawaddress>Moscow, Bolshaya Sadovaya, 10, apt. 13</rawaddress>.
                <building_type>-</building_type>
                <region_type> city</region_type>
                <living_date>2011-07-25</living_date>
            </Address>.
            <SNILS>13738699108</SNILS>
            <LoanInfo>.
                <AverageLoanMaturity>18.0</AverageLoanMaturity>
                <MinLoanPercent>14.0</MinLoanPercent>
                <AverageLoanPercent>16.0</AverageLoanPercent>
                <CreditHistoryUser>Mandarin</CreditHistoryUser
                <MaxLoanMaturity>24.0</MaxLoanMaturity>
                <MaxLoanAmount>100000.0</MaxLoanAmount>
                <PaidLoans>0</PaidLoans>
                <ActiveLoans>2</ActiveLoans>
                <DaysLeftReject>0</DaysLeftReject>
                <CreditHistoryConsent>True</CreditHistoryConsent>
                <InBlackList>False</InBlackList>
                <CreditHistoryExpireDate>2016-10-30</CreditHistoryExpireDate>
                <MaxLoanPercent>18.0</MaxLoanPercent>
                <CreditHistoryConsentDate>2016-09-30</CreditHistoryConsentDate>
                <MinLoanMaturity>12.0</MinLoanMaturity>
                <AverageLoanAmount>75000.0</AverageLoanAmount>
                <MinLoanAmount>50000.0</MinLoanAmount>
                <DaysLeftLast>100</DaysLeftLast
                <CreditHistoryPurpose>1</CreditHistoryPurpose>
            </LoanInfo>.
            <BirthPlace> Moscow</BirthPlace>
            <Citizenship>.
                <CountryCode>643</CountryCode>
            </Citizenship>
            <Family> Sharikov</Family>
            <PersonID>24</PersonID
            <Phones>.
                <PhoneCode>+7495</PhoneCode>
                <PhoneNumber>2504010</PhoneNumber>
                <PhoneType>
                    <Code>1</Code>
                </PhoneType>
            </Phones>.
            <Phones>.
                <PhoneCode>+7495</PhoneCode>
                <PhoneNumber>2501040</PhoneNumber>
                <PhoneType>
                    <Code>2</Code>
                </PhoneType>
            </Phones>.
            <FamilyInfo>
                <MaritalStatus>.
                    <Code>2</Code>
                </MaritalStatus>
                <DependentsNumber>2</DependentsNumber>
            </FamilyInfo>.
            <Sex> husband</Sex
            <BirthDay>1975-05-19</BirthDay>
            <isLivingOnRegistration>True</isLivingOnRegistration>
            <INNFL>123456789012</INNFL>
            <OKTMO>45320000</OKTMO>
            <JobInfo>.
                <OccupationType> catcher</OccupationType>
                <OccupationPost> manager</OccupationPost>
                <OccupationExperience>16</OccupationExperience>
                <ProfessionalExperience>16</ProfessionalExperience>
                <OccupationIndustry> service</OccupationIndustry>
                <EmployerType> State Enterprise</EmployerType>
                <EmployerIndustry> service</EmployerIndustry>
                <EmployerName> Cleanup</EmployerName>
            </JobInfo>.
            <Education>.
                <Code>1</Code>
            </Education>.
            <Patronim> Polygraphovich</Patronim
        </Person>.
        <Card>.
            <Holder></Holder>
            <Number></Number>
            <Expiration></Expiration>
        </Card>.
		<ScanDocumentsAvailable>True</ScanDocumentsAvailable>
		<DocumentScan>
			<Type>passport_main</Type>
			<Filename>scan1.jpg</Filename>
			<CreatedAt>2021-03-19T15:00:46.763336</CreatedAt>
			<AttemptsCount>1</AttemptsCount>
			<Data>QUFBCg==</Data>
		</DocumentScan>	
		<DocumentScan>
			<Type>passport_registration_address</Type>
			<Filename>scan2.jpg</Filename>
			<CreatedAt>2021-03-19T15:01:23.634684</CreatedAt>
			<AttemptsCount>1</AttemptsCount>
			<Data>YmJiCg==</Data>
		</DocumentScan>	
		<DocumentScan>
			<Type>selfie</Type>
			<Filename>scan3.jpg</Filename>
			<CreatedAt>2021-03-19T15:02:17.536733</CreatedAt>
			<AttemptsCount>1</AttemptsCount>
			<Data>ZaqiCg==</Data>
		</DocumentScan>	
    </ContractRequest>
</request>.

Response to the request from the lender's service:

<response>.
    <date>2016-11-15T05:08:43+00:00</date>
    <message>OK</message>
    <code>000</code>
    <result>
        <GetProposals>OK</GetProposals>
    </result>
</response>

# - Transmit Contract Proposals (Opcode 791 ContractProposal)

During the time of relevance of the contract request, the creditor's system can send a proposal (offer) for a loan. This is done by requesting the SCP next format:

[standard header, SiteID = creditor]

Action = PutProposals (the only option)

  1. ContractProposals - container for proposals

1.1. ContractProposal - proposal (several different options)

1.1.1. AttemptsCount - counter of repeated requests. For correct processing you should send the same value that was received in the last request "790 ContractRequest". The borrower sees in the personal profile only offers with the current AttemptsCount number.

1.1.2. ContractType - classifier string, always equal to 1

1.1.3. MerchantSiteID - identifier of the store in the system, for which indeed an offer

1.1.4. ContractRequestID - Contract request identifier

1.1.5. ContractorSiteID - identifier of creditor in gateway xxxxxx-yyyyy (may duplicate SiteID from the header, if the creditor works with the system directly, but may be different if the creditor uses an intermediate scoring system)

1.1.6. ContractProposalID - unique identifier of the proposal within creditor information system

1.1.7. Created - the moment of request creation in the format yyyyy-MM-dd hh:mm:ss+hh:mm

1.1.8. Status - classifier string (reserved)

1.1.9. ContractTextURL - link to the text of the credit agreement on this Offer

1.1.10. RejectCause - a detailed reason for refusal (for example, "the borrower is under 21 of the year")

1.1.11. LoanSpecification - specific parameters relevant for a particular Loan

1.1.11.1. LoanType - credit type; currently only supported Monthly annuity - AnnualMonth

1.1.11.2. PurchaseAmount - purchase amount (credit along with initial payment)

1.1.11.3. LoanAmount - credit amount. = * (1 - )

1.1.11.4. LoanFirstPayment - size of the initial payment in units (0.1, not 10%)

1.1.11.5. LoanYearPercent - annual percentage rate

1.1.11.6. ReturnDate - date of return of the loan (multiple of 30 days from the date of issue of the loan)

1.1.11.7. AnnualPayment - amount of annuity payment (in case of AnnualMonth type credit - monthly)

1.1.11.8. AnnualPeriods - number of periods for which the loan is issued (in case AnnualMonth - months)

1.1.11.9. LoanLimit - the limit (maximum amount) of credit available to this user according to the scoring (in case the requested in the application 790 the amount of the loan exceeds the limit, and the loan offer is put on maximum allowable amount, this field allows you to understand why the credit amount is not corresponds to the one requested)

1.1.11.10. PaymentsPlan - table in JSON format that contains payment calendar on the loan on the condition of its execution on the day of application.

1.1.11.11. LoanID - unique identifier of the offer within the creditor (optionally, the main identifier is ContractProposalID).

1.1.12. Person.

1.1.12.1. PersonID - identifier of the physical person for whom the this offer

In the absence of offers (refusal of a particular individual, or If it is not possible to satisfy the requested conditions) the LoanSpecification section can to be omitted, as well as unnecessary fields in this case.

Example query:

<request>
    <Opcode>791</Opcode>
    <SiteID>111111-1111</SiteID>
    <timestamp>1471836223</timestamp>
    <hash>37c6a6d390ba38bb28a02ffe5f44b58d</hash>
    <contract_type>1</contract_type>
    <Action>PutProposals</Action>
    <ContractProposals>
        <ContractProposal>
            <AttemptsCount>1</AttemptsCount>
            <ContractType>1</ContractType>
            <MerchantSiteID>111111-1111</MerchantSiteID>
            <ContractRequestID>60</ContractRequestID>
            <ContractorSiteID>999999-9991</ContractorSiteID>
            <ContractProposalID>1003</ContractProposalID>
            <Created>2016-11-16 17:38:00+05:00</Created>
            <Status>0</Status
            <ContractTextURL>http://localhost:8080/contract-1003.html</ContractTextURL>
            <RejectCause></RejectCause>
            <LoanSpecification>.
                <LoanID>1003</LoanID>
                <LoanType>AnnualMonth</LoanType>
                <PurchaseAmount>50000.00</PurchaseAmount>
                <LoanAmount>45000.00</LoanAmount>
                <LoanFirstPayment>0.1</LoanFirstPayment>
                <LoanYearPercent>45.0</LoanYearPercent>
                <AnnualPayment>16677.00</AnnualPayment>
                <AnnualPeriods>3</AnnualPeriods>
                <ReturnDate>2017-02-16</ReturnDate>
            </LoanSpecification>
            <Person>
                <PersonID>24</PersonID>
            </Person>
        </ContractProposal>
        <ContractProposal>
            <ContractType>1</ContractType>
            <MerchantSiteID>111111-1111</MerchantSiteID>
            <ContractRequestID>61</ContractRequestID>
            <ContractorSiteID>999999-9991</ContractorSiteID>
            <ContractProposalID>1004</ContractProposalID>
            <Created>2016-11-16 17:38:00+05:00</Created>
            <Status>0</Status
            <ContractTextURL>http://localhost:8080/contract-1003.html</ContractTextURL>
            <RejectCause></RejectCause>
            <LoanSpecification>.
                <LoanID>1004</LoanID>
                <LoanType>AnnualMonth</LoanType>
                <PurchaseAmount>50000.00</PurchaseAmount>
                <LoanAmount>45000.00</LoanAmount>
                <LoanFirstPayment>0.1</LoanFirstPayment>
                <LoanYearPercent>45.0</LoanYearPercent>
                <AnnualPayment>16677.00</AnnualPayment>
                <AnnualPeriods>3</AnnualPeriods>
                <ReturnDate>2017-02-16</ReturnDate>
            </LoanSpecification>
            <Person>
                <PersonID>24</PersonID
            </Person>
        </ContractProposal>
    </ContractProposals>
</request>

Example of a successful response:

<?xml version="1.0" encoding="utf-8"?
<response>.
    <external_result_info>
        <result_error>0</result_error>
        <result_status>0</result_status>
        <result_message>Accepted proposals from [u'004299-0004'] for
[u'27419']</result_message>
        <result_type>0</result_type>
        <result_source>0</result_source>
    </external_result_info>
    <date>2019-10-15T12:59:09+00:00</date>
    <message>OK</message>
    <code>000</code>
    <result>
        <proposal>
            <message>OK</message>
            <ContractProposalID>0000027419-004299-0002-2741641</ContractProposalID>
        </proposal>
    </result>
</response>

An example of an answer with an error:

<response>
    <date>2016-11-15T17:30:17+00:00</date>
    <message>OK</message>
    <code>000</code>
    <result>
        <proposal>
            <message>OK</message>
            <ContractProposalID>1003</ContractProposalID>
        </proposal>
        <proposal>
            <message>ContractRequestID 61 not found</message>
            <ContractProposalID>1004</ContractProposalID>
        </proposal>
    </result>
</response>

# - Sign the selected contract (opcode 794 ContractSign)

The issuance of credit to the user must be confirmed by the consent of that particular user, not the person working in the web interface; this is done by authorization by SMS sent to the phone number specified in the user profile. This authorization is considered the signing of the selected contract (credit of an offer) and is carried out with the help of operation 794 ContractSign.

The signing of the contract is done in synchronic mode: after sending in the contractual gateway of the request with the pin code is immediately notified of the the signing or non-signing of a contract.

[standard header, SiteID store]

Action:

GetConfirm - request to generate a pin code and send it via SMS to the user (fields ContractProposalPIN and ContractProposalSigned are not filled)

PutConfirm - transmits the pin code entered by the user and receives confirmation of its match (the ContractProposalPIN field is used); transfer notifying the lender of the contract signature and obtaining its consent (The ContractProposalSigned field is used)

ContractProposal - proposal (in the case of a store, a single

1.1. ContractType - classifier string, always equal to 1

1.2. MerchantSiteID - store ID in payment gateway xxxxxx-yyyyy

1.3. ContractRequestID - identifier of the contract request

1.4. ContractorSiteID - identifier of the creditor in the gateway xxxxxx-yyyyy

1.5. ContractProposalID - unique identifier of the proposal within creditor information system

1.6. Message - text of the SMS message to which the generated Pincode (the default is: "Your PIN code for signing the contract")

1.7. ContractProposalPIN - pin code entered by the user

1.8. ContractProposalSigned - notice of contract signature sent to the creditor; the creditor's response message=OK to the 794 PutConfirm request means confirmation of the signing and entry into force of the contract (is the basis of for payment)

Example request GetConfirm:

<request>.
    <Opcode>794</Opcode>
    <SiteID>111111-1111</SiteID>
    <timestamp>1471836223</timestamp>
    <hash>5b504cc034c09160fadc4950b287aed3</hash>
    <contract_type>1</contract_type>
    <Action>GetConfirm</Action>
    <ContractProposal>
        <ContractType>1</ContractType>
        <MerchantSiteID>111111-1111</MerchantSiteID>
        <ContractRequestID>60</ContractRequestID>
        <ContractorSiteID>999999-9991</ContractorSiteID>
        <ContractProposalID>1003</ContractProposalID>
        <Message>Your pin code for signing a loan agreement at 46% APR for 3
of the month in the amount of 24,000</Message>.
    </ContractProposal>
</request>.

The answer in case of any error:

<?xml version="1.0" encoding="utf-8"?
<response>.
    <date>2016-11-16T07:33:10+00:00</date>
    <message> ContractRequestID 60 has already signed Proposal 1003</message>
    <code>000</code>
</response>.

The answer in the case of a successful operation:

<response>.
    <date>2016-11-09T17:25:47+00:00</date>
    <message>OK</message>
    <code>000</code>
    <result>OK - send PIN to +79010010200</result>
</response>.

Example of a PutConfirm request from the LC to a contract gateway:

<request>.
    <Opcode>794</Opcode>
    <SiteID>111111-1111</SiteID>
    <timestamp>1471836223</timestamp>
    <hash>5b504cc034c09160fadc4950b287aed3</hash>
    <contract_type>1</contract_type>
    <Action>PutConfirm</Action>
    <ContractProposal>
        <ContractType>1</ContractType>
        <MerchantSiteID>111111-1111</MerchantSiteID>
        <ContractRequestID>60</ContractRequestID>
        <ContractorSiteID>999999-9991</ContractorSiteID>
        <ContractProposalID>1003</ContractProposalID>
        <ContractProposalPIN>16016</ContractProposalPIN>
    </ContractProposal>
</request>.

An example of the response in the case of a successful operation:

<response>.
    <date>2016-11-09T17:32:27+00:00</date>
    <message>OK</message>
    <code>000</code>
    <result>OK - sign contract 1003</result>
</response>.

An example of the answer in case of a PIN mismatch:

<response>.
    <date>2016-11-09T18:30:26+00:00</date>
    <message>PIN not match</message>
    <code>000</code>
</response>.

Example of a response in the case of a creditor's refusal to accept the signing of a contract:

<response>.
    <date>2016-11-16T07:47:20+00:00</date>
    <message>Contractor not accept sign: [contractor message]</message>
    <code>000</code>
</response>.

In case of a PIN-code error, you can enter the PIN-code again only through a new GetConfirm request, an attempt to resend the PIN code will cause an error:

<response>.
    <date>2016-11-16T07:51:48+00:00</date>
    <message>PIN not generate</message>
    <code>000</code>
</response>.

# Online checkout

# - General description of the online checkout

Online checkout functionality is enabled for a particular merchant (store). During the registration process, the user must upload scans of documents that are transmitted to the Mandarin server as part of the credit application (790 ContractRequest). If all three types of documents are uploaded (passport_main - passport page with photo, passport_registration_address - passport page with permanent registration, selfie - selfies with document), the server puts a sign ScanDocumentsAvailable = true in the application.

The lender, after receiving an application for credit (790 ContractRequest), determines whether scans of the borrower's documents are loaded, by the value of the attribute ScanDocumentsAvailable = true.

The lender can then query with opcode 796 DocumentScan, which returns for the application all available photos (up to 7 MB in size) encoded in Base64. Inside each document block there is a value AttemptsCount which is incremented by 1 with each new photo upload. This will allow you to see the historicity of the document package, even after rejection due to "Unsatisfactory photo quality" and resending the application with new documents. For each new loan application (790 ContractRequest), the borrower must attach new photos.

# - Request for Proposals (Opcode 790 ContractRequest)

The online loan application includes several DocumentScan sections:

<?xml version="1.0" encoding="utf-8"?
<request>.
	<Opcode>790</Opcode>
	<SiteID>000479-0001</SiteID>
	<timestamp>1584521686</timestamp>
	<hash></hash>
	<contract_type>1</contract_type>
	<Action>GetProposals</Action>
	<ContractRequest>
		<ContractRequestID>28058</ContractRequestID>
		<LoanSpecification>.
			<Amount>1000.00</Amount>
			<MaximalYearPercent>55.00</MaximalYearPercent>
		</LoanSpecification>.
		<Person>.
			<PersonID>35452</PersonID>
		</Person>.
		<ScanDocumentsAvailable>True</ScanDocumentsAvailable>
		<DocumentScan>
			<Type>passport_main</Type>
			<Filename>scan1.jpg</Filename>
			<CreatedAt>2021-03-19T15:00:46.763336</CreatedAt>
			<AttemptsCount>1</AttemptsCount>
			<Data>QUFBCg==</Data>
		</DocumentScan>	
		<DocumentScan>
			<Type>passport_registration_address</Type>
			<Filename>scan2.jpg</Filename>
			<CreatedAt>2021-03-19T15:01:23.634684</CreatedAt>
			<AttemptsCount>1</AttemptsCount>
			<Data>YmJiCg==</Data>
		</DocumentScan>	
		<DocumentScan>
			<Type>selfie</Type>
			<Filename>scan3.jpg</Filename>
			<CreatedAt>2021-03-19T15:02:17.536733</CreatedAt>
			<AttemptsCount>1</AttemptsCount>
			<Data>ZaqiCg==</Data>
		</DocumentScan>	
		...
	</ContractRequest>
</request>.

The number of DocumentScan sections is unlimited. The field Filename contains the file name and extension. The field CreatedAt contains the date the file was downloaded. The field AttemptsCount represents the count of attempts to submit a document scan. The field Data contains an image (up to 7 MB in size) encoded in Base64. The list of values for the Type field:

  • passport_main - passport page with photo;

  • passport_registration_address - passport page with permanent registration;

  • A `selfie'-selfie of the borrower with the document.

# - Request all scans of the borrower's documents (opcode 796 DocumentScan)

A query that can be used to get scans of every document ever uploaded for an application.

Example query:

<?xml version="1.0" encoding="utf-8"?
<request>.
	<Opcode>796</Opcode>
	<SiteID>000479-0001</SiteID>
	<timestamp>1584521686</timestamp>
	<hash></hash>
	<contract_type>1</contract_type>
	<Action>GetScanDocuments</Action>
	<ContractRequestID>28058</ContractRequestID>
</request>.

Example of a successful response:

<?xml version="1.0" encoding="utf-8"?
<response>.
	<external_result_info>
		<result_error>0</result_error>
		<result_status>0</result_status>
		<result_message>OK</result_message>
		<result_type>0</result_type>
		<result_source>0</result_source>
	</external_result_info>
	<date>2020-03-19T15:00:49+00:00</date>
	<message>OK</message>
	<code>000</code>
	<result>.
		<ContractRequest>
			<DocumentScan>
				<Data>QUFBCg==</Data>
				<AttemptsCount>10</AttemptsCount>
				<Type>passport_main</Type>
				<CreatedAt>2020-03-19T15:00:46.763336</CreatedAt>
				<Filename>scan1.jpg</Filename>
			</DocumentScan>
			<DocumentScan>
				<Data>YmJiCg==</Data>
				<AttemptsCount>10</AttemptsCount>
				<Type>passport_registration_address</Type>
				<CreatedAt>2020-03-19T15:00:46.763336</CreatedAt>
				<Filename>scan2.jpg</Filename>
			</DocumentScan>
			<ContractRequestID>28058</ContractRequestID>
		</ContractRequest>
	</result>.
</response>.

An example of an answer with an error:

<?xml version="1.0" encoding="utf-8"?
<response>.
	<date>2020-03-19T15:04:32+00:00</date>
	<message>Error: Scans not found</message>
	<code>001</code>
	<external_result_info>
		<result_error>1</result_error>
		<result_status>1</result_status>
		<result_message>Scans not found</result_message>
		<result_type>0</result_type>
		<result_source>0</result_source>
	</external_result_info>
</response>.

# Broker API

Under this interaction scheme Mandarin acts as a classical broker and brings the client to the signing. All further interaction on the servicing of loans and installments is carried out on the lender's side.

# Introduction

This section is under development.

← Basic principles →