Loan

The process of emission of a loan is divided in two steps: authorization and capture.

Similar to billing operations, authorization is performed in order to see if the client can access a service, in this case a loan. If they qualify, you can present them with the information and, once they accept, you can confirm that (capture it) in order to emit the loan.

This flow permits an interactive experience in your platform where the users can see different options and choose to pick or not the deals offered to them.

Authorization

Authorization calls are done to the /v1/authorization/ URI with an HTTP POST method.

In those calls we include thee types of information:

Who is the user. Information that helps identify and contact the person.
What deal they want.
Any information collected by your platform that can help improve the inference about this user.

An example payload looks like this:

{
  "client": {
    "name": "",
    "document": "string",
    "email": "",
    "phone": "",
    "birth_date": "2022-04-29",
    "address": "",
    "address_number": "",
    "address_complement": "",
    "neighborhood": "",
    "city": "",
    "state": "",
    "zip_code": "",
    "quiz": {
      "lending_purpose": "uso_pessoal",
      "motive": "compras",
      "use_detail": "string",
      "use_detail_old": "",
      "education_level": "",
      "residence": "",
      "has_new_income": false,
      "monthly_income": "string",
      "occupation_type": "",
      "occupation": "",
      "work_start_year": 0,
      "has_other_loan": true,
      "other_loan_status": "na",
      "has_bank_account": false,
      "has_credit_card": false,
      "monthly_expenses": "string"
    },
  },
  "loan": {
    "loan_value": "string",
  },
  "information": [
    {"type": "operation", "payload": {}}
  ],
  "score": "string",
}

The values present in the client key is related to the user, address, and ways to communicate with. The client.quiz key is a survey that can be performed on the user requesting the loan in order to know about his or her background.

The loan key contains information about the loan requested. Right now we only ask for the amount the user is asking for.

information makes reference to custom information that is present in your platform and can be shared with us. During the onboarding process we help you research which information is available and shared in real time with us at the inference instance (ie: the call to /v1/authorization). In order to make the integration easier and quicker we propose a pre-defined format for that information:

{
  "type": "<category>.<specific name>",
  "payload": {
    "object": "with lot of values"
  }
}

This can be adapted to share things like expending operations, gamification activity in your app, transactions, etc. We include those in our data science pipeline in order to make the inference of loans more effective.

As for the response, it contains this information:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "result": "approved",
  "loan_value": "150.00",
  "installments": 3,
  "monthly_interest_rate": "0.00",
  "annual_interest_rate": "0.00",
  "total_value": "150.00",
  "fee": "5.00",
  "iof": "5.00",
  "loan_date": "2022-04-29",
  "loan_expiration_date": "2022-04-29",
  "installments_due_day": 14,
  "installment_value": "50.00",
  "monthly_ecd_rate": "0.00",
  "annual_ecd_rate": "0.00",
  "first_installment_due_date": "2022-05-13"
}

Possible values for the "result" key are:

Result	Meaning
approved	The response contains an offer for the user. The values might not be the same the user requested in the request authorization payload. The window where this offer depends on the configuration of the integration.
rejected	The response doesn't contain an offer for the user. You can use the information in the "reason" field to explain the reasons of the rejection to the client.

Capture

Capture calls are done to the /v1/capture/ URI with an HTTP POST method.

Capture calls are way simpler than authorization ones since they only include which offered is being accepted. An example payload looks like this:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

The only key, id, should contain the same id that was returned in the authorization call.

And the response is, in structure, similar to this one:

{
  "status": "success",
  "reason": "string"
}

The possible values for the status key are:

Status	Reason
success	The loan was emitted successfully.
failure	There was a problem emitting the loan. This shouldn't happen since all the information was validated in the "authorization" step. But since errors or problems can happen we communicate them with this field. The "reason" field includes information in those cases but it's usually not localized and we don't recommend showing that to end users.