Introduction

This documentation enables the connection between your services and user’s financial services, identification tools and financial information. For more information visit https://floid.cl/

API protocols

The Floid API uses POST requests to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The API is served over HTTPS TLS v1.3+ to ensure data privacy; All requests must include a Content-Type of application/json and the body must be valid JSON.

API hosts

Floid has only the Production environment which is used for testing and demo as well because we operate with real data from banks.

Base URL

https://api.floid.cl/

Get access token

Once you’ve completed the signup process we’ll provide a live API Key for the Header request via Dashboard.

Authorization Header = API Key

Do not share your API Key with anyone!

Identification products

Floid has three APIs for users' identification using Rol Único Tributario (RUT). They provide information about users' name, address and bank information.

Bank ID & KYC

Use the RUT number to check bank login.

Method: POST
Endpoint: /api/identity/bankid_kyc

Request Parameters

Model
Key Type Description
rut string Rol Único Tributario
password string Bank password

Responses

code DESCRIPTION
200 Successfully checked bank login
Example Value
{
  "isValid": true,
  "isLoginSuccess": true,
  "firstName": "Mark Tomas",
  "middleName": "",
  "lastName": "Gonzalez Hose",
  "gender": "VAR",
  "address": {
    "careOf": "",
    "street": "Anibal Pinto 1891",
    "zip": "",
    "city": "Calama",
    "region": "",
    "country": "CL"
  }
}
Model
Key Type Description
isValid boolean True when service result is successful, else 'false'
isLoginSuccess boolean True if we managed to login the authority, else 'false'
firstName string User's first name
middleName string User's middle name
lastName string User's last name
gender string User's gender
careOf string Address through someone
street string Street name
zip string Zip code
city string City
region string Region
country string Country
error string Error message if any

ClaveUnica ID & KYC

Use the RUT number to obtain information direct/indirect debts.

Method: POST
Endpoint: /api/identity/claveunica_kyc

Request Parameters

Model
Key Type Description
rut string Rol Único Tributario
password string Bank password

Responses

code DESCRIPTION
200 Successfully checked direct/indirect debts
Example Value
{
  "isValid": true,
  "isLoginSuccess": true,
  "firstName": "Mark Tomas",
  "middleName": "",
  "lastName": "Gonzalez Hose",
  "gender": "VAR",
  "address": {
    "careOf": "",
    "street": "Anibal Pinto 1891",
    "zip": "",
    "city": "Calama",
    "region": "",
    "country": "CL"
  }
}
Model
Key Type Description
isValid boolean True when service result is successful, else 'false'
isLoginSuccess boolean True if we managed to login the authority, else 'false'
firstName string User's first name
middleName string User's middle name
lastName string User's last name
gender string User's gender
careOf string Address through someone
street string Street name
zip string Zip code
city string City
region string Region
country string Country
error string Error message if any

Name & address

Use the RUT number to obtain name and address.

Method: POST
Endpoint: /api/identity/name_address_lookup

Request Parameters

Example Value
{
  "rut": "9.999.999-9"
}
Model
Key Type Description
rut string Rol Único Tributario

Responses

code DESCRIPTION
200 Successfully checked name and address
Example Value
{
  "isValid": true,
  "firstName": "Mark Tomas",
  "middleName": "",
  "lastName": "Gonzalez Hose",
  "gender": "VAR",
  "address": {
    "careOf": "",
    "street": "Anibal Pinto 1891",
    "zip": "",
    "city": "Calama",
    "region": "",
    "country": "CL"
  }
}
Model
Key Type Description
isValid boolean True when service result is successful, else 'false'
firstName string User's first name
middleName string User's middle name
lastName string User's last name
gender string User's gender
careOf string Address through someone
street string Street name
zip string Zip code
city string City
region string Region
country string Country
error string Error message if any

Financial Information Products

Income check

The income check API used to evaluate paying capacity. It returns the income that comes in regularly, such as salary. Any other regular revenues presented as extra income. Obtain income information based on bank login credentials.
In this service, the request goes into a queue first.

Method: POST
Endpoint: /api/income_check

Request Parameters

Example Value
{
  "rut": "9.999.999-9",
  "password": "dummy password",
  "bankName": "bci",
  "callbackUrl": "https://example-site.com/callback",
  "caseId": "user case id"
}
Model
Key Type Description
rut string Rol Único Tributario
password string Bank password
bankName string [banco estado | bci | banco santander | scotiabank | banco bice | itau corpbanca | banco security | banco chile | banco ripley | banco falabella] Mandatory. Should be one of the following strings
callbackUrl string Mandatory. URL where to receive the result of operation after it’s processed by the queue
caseId string Mandatory. User’s identifier on the request that will be returned on the responses. Usually used for tracking purposes or ID of the request and response

Responses

code DESCRIPTION
200 Successfully added to the income check job queue. Please wait on the callback URL for the API response with the transaction list.
Example Value
{
  "isAccepted": true,
  "message": "Processing transactions for income check."
}
Model
Key Type Description
isAccepted boolean Display if the request was accepted or not into the queue
message string Message about job status
error string Error message if any

Callback Example
{
  "caseId": "estado income",
  "isValid": true,
  "regularity": "12/12",
  "totalAverage": 25000,
  "mainAverage": 20000,
  "extraAverage": 5000,
  "incomeByMonth": [
    {
      "month": "2020-06",
      "total": 25000,
      "main": 20000,
      "extra": 5000,
      "sources": [
        {
          "sender": "Company 1",
          "amount": 20000,
          "type": "main"
        },
        {
          "sender": "Company 2",
          "amount": 2000,
          "type": "extra"
        },
        {
          "sender": "Company 3",
          "amount": 3000,
          "type": "extra"
        }
      ]
    },
    {
      "month": "2020-05",
      "total": 75000,
      "main": 70000,
      "extra": 5000,
      "sources": [
        {
          "sender": "Company 1",
          "amount": 40000,
          "type": "main"
        },
        {
          "sender": "Company 2",
          "amount": 4000,
          "type": "extra"
        },
        {
          "sender": "Company 3",
          "amount": 6000,
          "type": "extra"
        }
      ]
    },
    {
      "month": "2020-04",
      "total": 35000,
      "main": 30000,
      "extra": 5000,
      "sources": [
        {
          "sender": "Company 1",
          "amount": 10000,
          "type": "main"
        },
        {
          "sender": "Company 2",
          "amount": 4000,
          "type": "extra"
        },
        {
          "sender": "Company 3",
          "amount": 6000,
          "type": "extra"
        }
      ]
    }
  ]
}
Model
Key Type Description
caseId string Mandatory. User’s identifier on the request that will be returned on the responses. Usually used for tracking purposes or ID of the request and response
isValid boolean True when service result is successful, else 'false'
regularity string Returns the amount of months user has the main income.
totalAverage number Average amount of total income per month.
mainAverage number Average amount of main income per month.
extraAverage number Average amount of extra income per month.
incomeByMonth incomeByMonth[]
Income by month
Key Type Description
month date Month of the calculation
total number Total income during the month
main number Total main income during the month
extra number Total extra income during the month
sources sources[] List of income sources
Source in month
Key Type Description
sender string The sender of the income
amount number Income amount
type string Main or Extra

Asset report

Evaluate the user's financial products using our algorithm to check for credit lines, account types, credit cards, overdraft used, and more.

Method: POST
Endpoint: /api/asset_report

Request Parameters

Example Value
{
  "bankName": "bci",
  "rut": "9.999.999-9",
  "password": "dummy password",
  "uiType": "mobile"
}
Model
Key Type Description
bankName string [banco estado | bci | banco santander | scotiabank | banco bice | itau corpbanca | banco security | banco chile | banco ripley | banco falabella] Mandatory. Should be one of the following strings
rut string Rol Único Tributario
password string Bank password
uiType string [mobile | desktop] Bank interface to use. Should be one of the following strings

Responses

code DESCRIPTION
200 Successfully obtained a fast credit score.
Example Value
{
  "isValid": true,
  "isLoginSuccess": true,
  "creditScore": 700,
  "creditScoreParams": {
    "accountNormal": true,
    "accountSpecial": false,
    "creditCardPresence": true,
    "fullCreditLine": true,
    "usedCreditLine": 0,
    "totalBalance": 4166935,
    "currentDay": 9
  }
}
Model
Key Type Description
isValid boolean True when service result is successful, else 'false'
isLoginSuccess boolean True if we managed to login the authority, else 'false'
creditScore number User's credit score
accountNormal boolean True if user has account normal
accountSpecial boolean True if user has account special
creditCardPresence boolean True if user has a credit card
fullCreditLine boolean True if user's credit line is full
usedCreditLine number Amount of credit line that is used
totalBalance number User's total balance
currentDay number Current day of month
error string Error message if any

Transaction history

Return a detailed list of incoming and outcoming transactions to the specified callback URL. The API will also return categorized amounts based on our proprietary algorithm. In this service, the request goes into a queue first.

Method: POST
Endpoint: /api/transaction_history

Request Parameters

Example Value
{
  "rut": "9.999.999-9",
  "password": "dummy password",
  "bankName": "bci",
  "duration": 3,
  "callbackUrl": "https://example-site.com/callback",
  "caseId": "user case id"
}
Model
Key Type Description
rut string Rol Único Tributario
password string Bank password
bankName string [banco estado | bci | banco santander | scotiabank | banco bice | itau corpbanca | banco security | banco chile | banco ripley | banco falabella] Mandatory. Should be one of the following strings
duration integer [3 | 12 | 24] Mandatory. Amount of months to return
callbackUrl string Mandatory. URL where to receive the result of operation after it’s processed by the queue
caseId string Mandatory. User’s identifier on the request that will be returned on the responses. Usually used for tracking purposes or ID of the request and response

Responses

code DESCRIPTION
200 Successfully added to transactions history job queue. Please wait on the callback URL for the API response with the transaction list.
Example Value
{
  "isAccepted": true,
  "message": "Processing transactions for transaction history."
}
Model
Key Type Description
isAccepted boolean Display if the request was accepted or not into the queue
message string Message about job status
error string Error message if any

Callback Example
{
  "caseId": "123456789",
  "isValid": true,
  "transactions": [
    {
      "date": "2020-06-05",
      "amount": 0,
      "amountIncome": 65000,
      "category": "Transferencias de fondos",
      "description": "TEF DE VAL",
      "sucursal": "PRINCIPAL",
      "operacionNumber": "7000000"
    },
    {
      "date": "2018-06-14",
      "amount": 25000,
      "amountIncome": 0,
      "category": "Servicios financieros/Portal de Pago",
      "description": "WWW MEGOGO CL",
      "sucursal": "STGO. ONE",
      "operacionNumber": "300000"
    }
  ],
  "totalSpentByCategory": {
    "Transferencias de fondos": 6789010,
    "Bank fees": 6000,
    "Unknown": 2000000,
    "Withdrawls": 250000,
    "Servicios financieros/Portal de Pago": 540000,
    "Supermarket": 8000,
    "Pharmacy": 14000
  },
  "totalIncomeByCategory": {
    "Unknown": 4139000,
    "Transferencias de fondos": 4197000,
    "Abonos/Depositos": 1902800
  }
}
Model
Key Type Description
caseId string Mandatory. User’s identifier on the request that will be returned on the responses. Usually used for tracking purposes or ID of the request and response
isValid boolean True when service result is successful, else 'false'
transactions transactionItem[] A list of all bank transactions.
totalSpentByCategory categoryAmount[] List of categorized spendings
totalIncomeByCategory categoryAmount[] List of categorized incomes
Transaction Item (values may depend on the bank)
Key Type Description
date date Transaction date
amount number Spending amount
amountIncome number Income amount
category string Transaction category
description string Transaction description
cucursal string Optional field
operacionNumber string Optional field
Category amount
Key Type Description
name string Name of the category
amount number Total amount of the category

Full Debt

Use the RUT number to obtain information direct/indirect debts.

Method: POST
Endpoint: /api/full_debt

Request Parameters

Model
Key Type Description
rut string Rol Único Tributario
password string Bank password

Responses

code DESCRIPTION
200 Successfully checked direct/indirect debts
Example Value
{
  "isValid": true,
  "isInvalidCredentials": false,
  "fullName": "Mark Tomas",
  "creditcheckDate": "31/01/2020",
  "accountsData": {
    "directDebt": [
      {
        "name": "Chile",
        "activeDebt": "12345678",
        "pastDueThirtyToNinetyDays": "0",
        "pastDueOverNinetyDays": "0",
        "total": "12345678"
      },
      {
        "name": "De Credito",
        "activeDebt": "1234567",
        "pastDueThirtyToNinetyDays": "0",
        "pastDueOverNinetyDays": "0",
        "total": "1234567"
      }
    ],
    "indirectDebt": [],
    "availableCredit": [
      {
        "name": "Scotiabank Chile",
        "directAvailableAmount": "1234567",
        "indirectAvailableAmount": "0"
      }
    ],
    "otherAvailableCredit": []
  },
  "error": "string"
}
Model
Key Type Description
isValid boolean True when service result is successful, else 'false'
fullName string User's full name
directDebt debtObject[]
indirectDebt debtObject[]
availableCredit creditObject[]
otherAvailableCredit otherAvailableCredit[]
error string Error message if any
Direct object
Key Type Description
name string
activeDebt number
pastDueThirtyToNinetyDays number
pastDueOverNinetyDays number
total number
Credit object
Key Type Description
name string
directAvailableAmount number
indirectAvailableAmount number

Payment Products

Payment Initiation Service by Floid has three APIs used to perform financial transactions. The money transfers from user’s account to the Floid’s account or merchant account. Please, be aware: the second and third APIs aren’t required for all banks.
Understand payment API

Transfer money from user account to Floid account

All Transactions independent of the bank, are initiated through this INITIAL Request.

Method: POST
Endpoint: /api/pis/transfer

Request Parameters

Example Value
{
  "rut": "9.999.999-9",
  "password": "dummy password",
  "bankName": "bci",
  "caseId": "99999",
  "moneyAmount": "1000",
  "callbackUrl": "https://example-site.com/callback",
  "callbackApiKey": "e02c5f371d0e4acc"
}
Model
Key Type Description
rut string Rol Único Tributario
password string Bank password
bankName string [banco estado | bci | banco santander | scotiabank | banco bice | itau corpbanca | banco security | banco chile | banco ripley | banco falabella] Mandatory. Should be one of the following strings
caseId string Mandatory. User’s identifier on the request that will be returned on the responses. Usually used for tracking purposes or ID of the request and response
moneyAmount string Quantity money for send to other card
callbackUrl string Mandatory. URL where to receive the result of operation after it’s processed by the queue
callbackApiKey string Callback api key

Responses

code DESCRIPTION
200 Successfully added to the money transfer job queue. Please wait on the callback URL for the API response with the final response OR returned data for the second step.
Example Responses
{
  "isAccepted": true,
  "message": "WAITING_FOR_APP_APPROVAL"
}
or
{
  "isAccepted": false,
  "message": "BANK_TRANSFER_FAILED"
}
or
{
  "isAccepted": true,
  "message": "BANK_TRANSFER_COMPLETED"
}
or
{
  "isAccepted": true,
  "message": "WAITING_FOR_SMS_CODE",
  "pageId": "c9dfc7c2ed3d34c2be415cfcadfd4e12043c002d"
}
or
{
  "isAccepted": true,
  "message": "WAITING_FOR_CARD_CODE",
  "cardCode": [
    "A1",
    "B1",
    "C1"
  ],
  "pageId": "c9dfc7c2ed3d34c2be415cfcadfd4e12043c002d"
}
or
{
  "isAccepted": true,
  "message": "WAITING_FOR_SMS_AND_CARD_CODE",
  "cardCode": [
    "A1",
    "B1",
    "C1"
  ],
  "pageId": "c9dfc7c2ed3d34c2be415cfcadfd4e12043c002d"
}
Model
null
RESPONSE message STATUS:
status description
WAITING_FOR_APP_APPROVAL Display a message to the consumer to approve the transaction on its Bank Approval App.
For some of the banks, where payments work fast we do not return this status. The request is waiting for the user to approve the transaction. And system returns BANK_TRANSFER_COMPLETED or BANK_TRANSFER_FAILED status.
WAITING_FOR_SMS_CODE Display a text field where the consumer will input the SMS code he receives.
WAITING_FOR_CARD_CODE Display 3 to 6 text fields each label with the information on cardCode[] object for consumer to input coordinate.
Please note, that for some of the bank system might return an array with empty values. In this case you need to show user the interface that contains the same amount of fields as in array to input the values from authentication device. These values have to be passed to the next step.
WAITING_FOR_SMS_AND_CARD_CODE Some bank like Itau may require SMS and Card code authentication. Display text fields to gother this input from the user
TRANSACTION_IS_NOT_EXIST Transaction is not created in the system. You can do it with get_iframe endpoint.
TRANSACTION_IS_EXPIRED Transaction created in system is expired and not valid anymore. Please create new one with get_iframe endpoint.
EXCEED_TRANSFER_LIMIT The bank transfer was failed due to the amount limit.
CHECK_REQUIRED_FIELDS Failed request - Please check required fields.
MINIMUM_MONEY_AMOUNT_1000 Minimum money amount is 1000.
RUT_PASSWORD_ARE_REQUIRED Please check rut and password field, because are required.
VERIFICATION_DATA_ACCEPTED Verification data is passed for the bank and you should wait for a callback with the result of the transactions.
This status usually returns when bank needs time to process the payment.

isAccepted: The transaction was included on the queue.
pageId: This is the id of the payment process. It has to be used in the next step. Please refer to payment status to understand which step is next.
cardCode: If this property is returned it means the bank is requesting Coordinate Card approval, you’ll need to display this codes and obtain the data display on each. Usually 3 codes will be displayed with 3 inputs.

Callback Example
{
  "isValid": "true",
  "bankName": "bici",
  "moneyAmount": "10000",
  "caseId": "12345678",
  "message": "BANK_TRANSFER_COMPLETED"
}
Model
Key Type Description
isValid boolean True when service result is successful, else 'false'
bankName string [banco estado | bci | banco santander | scotiabank | banco bice | itau corpbanca | banco security | banco chile | banco ripley | banco falabella] Mandatory. Should be one of the following strings
moneyAmount string Quantity money for send to other card
caseId string Mandatory. User’s identifier on the request that will be returned on the responses. Usually used for tracking purposes or ID of the request and response
message string Message about job status
RESPONSE callback STATUS:
status description
BANK_TRANSFER_COMPLETED The bank transfer was completed successfully.
BANK_TRANSFER_FAILED The bank transfer failed.

Second step for money transfer (not for all banks)

This second step is only required when the first step response requires information on smsCode or cardCode for bank transfer approval. The simplest way to know if a second or third step are required is by looking into the first step response property pageId which will allow you to connect to the second and/or third step of approval.

Method: POST
Endpoint: /api/pis/transfer_approval

Request Parameters

Example Request if SMS confirmation
{
  "pageId": "c9dfc7c2ed3d34c2be415cfcadfd4e12043c002d",
  "smsCode": "string"
}
Example Request if Multipass confirmation
{
  "pageId": "c9dfc7c2ed3d34c2be415cfcadfd4e12043c002d",
  "cardCode": [
    "11",
    "22",
    "33"
  ]
}
Example Request if SMS and Multipass confirmation
{
  "pageId": "c9dfc7c2ed3d34c2be415cfcadfd4e12043c002d",
  "smsCode": "string",
  "cardCode": [
    "11",
    "22",
    "33"
  ]
}
smsCode: should be value
cardCode: should be value
Model
Key Type Description
pageId string Id page, parameter from last step
smsCode string Access code from you phone
cardCode [] Access code

Responses

code DESCRIPTION
200 Successfully added to the money transfer job queue. Please wait on the callback URL for the API response with the final response OR returned data for the third step
Example Responses
{
  "isAccepted": true,
  "message": "VERIFICATION_DATA_ACCEPTED"
}
or
{
  "isAccepted": false,
  "message": "BANK_TRANSFER_FAILED"
}
or
{
  "isAccepted": true,
  "message": "BANK_TRANSFER_COMPLETED"
}
or
{
  "isAccepted": true,
  "message": "WAITING_FOR_SMS_CODE",
  "pageId": "c9dfc7c2ed3d34c2be415cfcadfd4e12043c002d"
}
or
{
  "isAccepted": true,
  "message": "WAITING_FOR_CARD_CODE",
  "cardCode": [
    "A1",
    "B1",
    "C1"
  ],
  "pageId": "c9dfc7c2ed3d34c2be415cfcadfd4e12043c002d"
}
Model
Key Type Description
isAccepted boolean Display if the request was accepted or not into the queue
message string Message about job status
data object

Third step for money transfer (not for all banks)

Method: POST
Endpoint: /api/pis/transfer_approval_optional

Request Parameters

Example Request if SMS confirmation
{
  "pageId": "c9dfc7c2ed3d34c2be415cfcadfd4e12043c002d",
  "smsCode": "string"
}
Example Request if Multipass confirmation
{
  "pageId": "c9dfc7c2ed3d34c2be415cfcadfd4e12043c002d",
  "cardCode": [
    "11",
    "22",
    "33"
  ]
}

Responses

code DESCRIPTION
200 Successfully transferred money
Example Responses
{
  "isAccepted": true,
  "message": "VERIFICATION_DATA_ACCEPTED"
}
or
{
  "isAccepted": false,
  "message": "BANK_TRANSFER_FAILED"
}
Model
null

Simple PIS Bank transfer iFrame solution

If you don’t want to handle each bank approval integration or you prefer to display a simpler iframe solution. This is the correct service.
With the Payment Initiation Service through iframe, you only need to send one initial request, display the URL on an iframe and prepare to receive the final callback. We’ll handle the flow for your consumer.

Method: POST
Endpoint: /api/pis/get_iframe

Request Parameters

Example Value
{
  "amount": "1000",
  "transactionId": "99999999",
  "comment": "test payment",
  "rut": "9.999.999-9",
  "callbackUrl": "https://example-site.com/callback",
  "redirectOnSuccessUrl": "http://floid.cl/es/",
  "redirectOnFailUrl": "https://example-site.com/fail"
}
Model
Key Type Description
amount string
caseId string Mandatory. User’s identifier on the request that will be returned on the responses. Usually used for tracking purposes or ID of the request and response
rut string Rol Único Tributario
callbackUrl string Mandatory. URL where to receive the result of operation after it’s processed by the queue
callbackApiKey string Callback api key
redirectOnSuccessUrl string Url for redirect when transaction is complete
redirectOnFailUrl string Url for redirect when transaction is fail

moneyAmount: Mandatory. Amount of money to be transferred (CLP).
callbackUrl: Mandatory. URL where to receive the transaction list after it’s processed by the Queue.

Responses

code DESCRIPTION
200 Successfully transferred money
Example Value
{
  "iframe": "<iframe src='https://api.floid.cl/money-transfer/iframe?transactionId=3852b423-7c2f-4913-a86a-29ba82264955' frameborder='0' width='375' height='667' ></iframe>"
}
Model
Key Type Description
iframe string Link to iframe page
RESPONSE iFRAME message STATUS:
status description
TRANSACTION_IS_IN_PROGRESS Please wait, transaction is in progress.
TRANSACTION_IS_NOT_STARTED Transaction is not started.
TRANSACTION_IS_FINISHED_SUCCESSFULLY Transaction is finished successfully.
TRANSACTION_IS_FINISHED_WITH_ERROR Transaction is finished with error.

Errors

code DESCRIPTION
400 Failed request - Please check required fields
Model
{
  "error": "string"
}

code DESCRIPTION
401 Unauthorized credentials
Model
{
  "error": "string"
}

code DESCRIPTION
500 Server error
Model
{
  "error": "string"
}