Getting started with Prometeo

Here, you’ll find helpful and clear documentation to start using Prometeo API. If you have any queries, you can contact us at info@prometeoapi.com

Why could an API help you? (Application Programming Interface)

Developing software from scratch could be very complex, expensive and unnecessary. APIs are interfaces that help us connect already developed services, which have been created for other projects and following some standards, connect them with ours to create a bigger one.

How could Prometeo help you?

Using different APIs, Prometeo can accesses domain banks, bank accounts and their movements.
Prometeo can log in, show personal and multi-managed accounts, show account movements, bank transfers, detail data from different financial institutions and show data of them.
For each request you make to the API, Prometeo will return a JSON (code structure that we’ll explain later) with the information you need to continue developing your product. If the language you chose to develop isn’t in the examples, contact us and we’ll help you.

Important items to bare in mind:

Endpoint is the point which the API share the information.
Token is a device which makes the request safer.
Prometeo uses POST or GET as an HTTP method.
Prometeo supports these financial institutions:

BBVA - México
Banorte - México
Citi Banamex - México
Santander - México
Three private betas - Brazil
Banco de Crédito - Perú
Scotiabank - Perú
Banco Estado - Chile
Banco Nación - Argentina
Banco Nacional - Panamá
Banco General - Panamá
Caja de Ahorros - Panamá
Bancolombia - Colombia
Davivienda - Colombia
Banco del Pacífico - Ecuador
Banco Internacional - Ecuador
BCU - Uruguay
BROU - Uruguay
Edenred - Uruguay
Itaú - Uruguay
Mi dinero - Uruguay
Santander - Uruguay

For safer requests, our team will give you the API-key that you need. Even if the endpoint is with POST method, every request must include the given API-key, except the login to the financial institution. You can choose the way you use it using the header X-API-Key or the parameter api_key in the url.
Most endpoints return the field “status” and the rest of the data will be present only if it is “success”
Once you are logged in, the session won’t last more than five minutes, depending on the web banking.
Some requests could required the media type ‘application/x-www-form-urlencoded’.

To access our testing environment, contact us at info@prometeoapi.com

For the examples below we’ll use this test data:

User with a single account
- Username: 12345
- Password: gfdsa
Test institution: test

Login

Endpoint: `POST /login/`

Parameters	Description
provider	It’s the name of the bank or the financial institution. In lower case (test, brou, santander, edenred, santander_mx, banco_general).
username	Identification document or username for the login to the home banking.
password	password to the financial institution web for the user.

Response:

Status	Description
status	select_client It’s necessary to select a client. wrong_credentials Invalid user or password. missing_credentials Filling all the blanks is required. logged_in successful login. interaction_required An interactive login is required, it could be a captcha or a security question.
key	Authentication code. It must be used in all the requests. It isn’t present if the response is an error status.

User:

POST /login/? HTTP/1.1
Host: test.prometeo.qualia.uy
Accept: application/json
X-API-Key: X-API-Key: <api key>

provider=test&username=12345&password=gfdsa

Response:

{
   "status" : "logged_in"
   "key" : "163d06b2-3378-4383-9868-71c2b6fb28da",
}

Wrong response:

{"status": "wrong_credentials"}

Required interaction response:

To beef up the security system, some financial institutions need a user interaction as a otp token, security questions or 2FA.

{
    "context": "How many bathrooms my parent's house had?",
    "field": "personal_question",
    "key": "be612b0a-c972-4fb1-bb16-798956a3efa1",
    "status": "interaction_required"
}

Login with interaction:

POST /login/? HTTP/1.1
Host: test.prometeo.qualia.uy
Accept: application/json
X-API-Key: <api key>

provider=test&username=12345&password=asdfg&personal_question=uno

curl -X POST "https://test.prometeo.qualia.uy/login/?" -d 'provider=test&username=12345&password=gfdsa' -H "X-API-Key:  <api key>"

Response:

{
   "status" : "logged_in"
   "key" : "163d06b2-3378-4383-9868-71c2b6fb28da",
}

Wrong response:

{"status": "wrong_credentials"}

Required interaction response:

To beef up the security system, some financial institutions need a user interaction as a otp token, security questions or 2FA.

{
    "context": "How many bathrooms my parent's house had?",
    "field": "personal_question",
    "key": "be612b0a-c972-4fb1-bb16-798956a3efa1",
    "status": "interaction_required"
}

Login with interaction:

curl -X POST "https://test.prometeo.qualia.uy/login/?" -d 'provider=test&username=12345&password=asdfg&personal_question=uno' -H "X-API-Key: <api key>"

import requests

requests.post('https://test.prometeo.qualia.uy/login/', headers={'X-API-Key': '<api key>'}, data={
  "provider": "test",
  "username": "12345",
  "password": "gfdsa"
})

Response:

{
   "status" : "logged_in"
   "key" : "163d06b2-3378-4383-9868-71c2b6fb28da",
}

Wrong response:

{"status": "wrong_credentials"}

Required interaction response:

To beef up the security system, some financial institutions need a user interaction as a otp token, security questions or 2FA.

{
    "context": "How many bathrooms my parent's house had?",
    "field": "personal_question",
    "key": "be612b0a-c972-4fb1-bb16-798956a3efa1",
    "status": "interaction_required"
}

Login with interaction:

requests.post('https://test.prometeo.qualia.uy/login/', headers={'X-API-Key': '<api key>'}, data={
  "provider": "test",
  "username": "12345",
  "password": "asdfg",
  "personal_question": "uno"
})

var request = require('request');

request.post({
  "url": "https://test.prometeo.qualia.uy/login/",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "form": {
    "provider": "test",
    "username": "12345",
    "password": "gfdsa"
  }
});

Response:

{
   "status" : "logged_in"
   "key" : "163d06b2-3378-4383-9868-71c2b6fb28da",
}

Wrong response:

{"status": "wrong_credentials"}

Required interaction response:

To beef up the security system, some financial institutions need a user interaction as a otp token, security questions or 2FA.

{
    "context": "How many bathrooms my parent's house had?",
    "field": "personal_question",
    "key": "be612b0a-c972-4fb1-bb16-798956a3efa1",
    "status": "interaction_required"
}

Login with interaction:

var request = require('request');

request.post({
  "url": "https://test.prometeo.qualia.uy/login/",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "form": {
    "provider": "test",
    "username": "12345",
    "password": "asdfg",
    "personal_question": "uno"
  }
});

List clients

Endpoint: `GET /client/`

Points to consider
Clients are accounts associated to a user. A user could have more than one associated accounts. It’s frequent that an account has two owners.
The users without associated clients don’t show information. It isn’t necessary to ‘Select Client’ you can go straight to Endpoint /account/

Parameters	Description
key	Authentication code. It must be used in all the requests.

User:

GET /client/?key=959602df-d3ee-4898-b6d8-a28a2c7486fb HTTP/1.1
Host: test.prometeo.qualia.uy
Accept: application/json
X-API-Key: <api key>

curl -X GET "https://test.prometeo.qualia.uy/client/?key=959602df-d3ee-4898-b6d8-a28a2c7486fb"  -H "X-API-Key: <api key>"

import requests

requests.get('https://test.prometeo.qualia.uy/client/', headers={'X-API-Key': '<api key>'}, params={
  "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
})

{
   "status":"success",
   "clients":{
      "0":"First Client",
      "1":"Second Client"
   }
}

Response:

{
   "status":"success",
   "clients":{
      "0":"First Client",
      "1":"Second Client"
   }
}

Select client

Endpoint: `GET /client/ <id>/`

Parameters	Description
key	Authentication code. It must be used in all the requests.

Response	Description
status

User:

var request = require('request');

request.get({
  "url": "https://test.prometeo.qualia.uy/client/20727/",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "qs": {
    "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
  }
});

curl -X GET "https://test.prometeo.qualia.uy/client/20727/?key=959602df-d3ee-4898-b6d8-a28a2c7486fb"  -H "X-API-Key: <api key>"

import requests

requests.get('https://test.prometeo.qualia.uy/client/20727/', headers={'X-API-Key': '<api key>'}, params={
  "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
})

var request = require('request');

request.get({
  "url": "https://test.prometeo.qualia.uy/client/20727/",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "qs": {
    "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
  }
});

Successful response:

{
   "status" : "success"
}

List accounts

Endpoint: `GET /account/`

Parameters	Description
key	Authentication code. It must be used in all the requests.

Response	Description
status
accounts	accounts list.

The example shows a successful response of a Santander bank account that has four different accounts.

User:

GET /account/?key=959602df-d3ee-4898-b6d8-a28a2c7486fb HTTP/1.1
Host: test.prometeo.qualia.uy
Accept: application/json
X-API-Key: <api key>

curl -X GET "https://test.prometeo.qualia.uy/account/?key=959602df-d3ee-4898-b6d8-a28a2c7486fb"  -H "X-API-Key: <api key>"

import requests

requests.get('https://test.prometeo.qualia.uy/account/', headers={'X-API-Key': '<api key>'}, params={
  "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
})

var request = require('request');

request.get({
  "url": "https://test.prometeo.qualia.uy/account/",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "qs": {
    "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
  }
});

Response:

{
   "accounts":  [
          {
      "balance": 1234.95,
      "branch": "02 - 18 De Julio",
      "currency": "UYU",
      "id": "hash1",
      "name": "Cuenta total",
      "number": "001234567890"
    },
          {
      "balance": 12.01,
      "branch": "02 - 18 De Julio",
      "currency": "USD",
      "id": “hash2”,
      "name": "Cuenta total",
      "number": "005234567890"
    },
          {
      "balance": 4301,
      "branch": "61 - Ciudad Vieja",
      "currency": "UYU",
      "id": "hash3",
      "name": "Caja De Ahorro Atm",
      "number": "007234567890"
    },
          {
      "balance": 53.96,
      "branch": "61 - Ciudad Vieja",
      "currency": "USD",
      "id": "hash4",
      "name": "Caja De Ahorro Atm",
      "number": "007234567890"
    }
   ],
   "status": "success"
}

List transactions

Endpoint: `GET /movement/`

Parameters	Description
account	Account number (it’s the ‘number’ value in the endpoint /account/ response).
currency	currency in format ISO 4217 in UYU or USD.
date_start	start date of the transactions, format DD/MM/YYYY
date_end	finish date of the transactions, format DD/MM/YYYY
key	Authentication code. It must be used in all the requests.

Response	Description
status
movements	transactions list.

User:

GET /movement/?key=959602df-d3ee-4898-b6d8-a28a2c7486fb&account=12345¤cy=UYU&date_start=22%2F11%2F2017&date_end=23%2F11%2F2017 HTTP/1.1
Host: test.prometeo.qualia.uy
Accept: application/json
X-API-Key: <api key>

curl -X GET "https://test.prometeo.qualia.uy/movement/?key=959602df-d3ee-4898-b6d8-a28a2c7486fb&account=12345¤cy=UYU&date_start=22%2F11%2F2017&date_end=23%2F11%2F2017"  -H "X-API-Key: <api key>"

import requests

requests.get('https://test.prometeo.qualia.uy/movement/', headers={'X-API-Key': '<api key>'}, params={
  "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb",
  "account": "12345",
  "currency": "UYU",
  "date_start": "22/11/2017",
  "date_end": "23/11/2017"
})

var request = require('request');

request.get({
  "url": "https://test.prometeo.qualia.uy/movement/",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "qs": {
    "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb",
    "account": "12345",
    "currency": "UYU",
    "date_start": "22/11/2017",
    "date_end": "23/11/2017"
  }
});

Response:

{
   "final_balance": "undefined",
   "initial_balance": "undefined",
   "movements": [
          {
      "credit": "",
      "date": "12/01/2017",
      "debit": 3500,
      "detail": "RETIRO EFECTIVO CAJERO AUTOMATICO J.C. GOMEZ 1372, MONTEVIDEO TARJ: 4303090202018993",
      "id": -890185180,
      "reference": "000000005084"
    },
          {
      "credit": "",
      "date": "05/01/2017",
      "debit": 16000,
      "detail": "RETIRO EFECTIVO CAJERO AUTOMATICO J.H Y OBES 1389, MONTEVIDEO TARJ: 4303090202018993",
      "id": 1024917397,
      "reference": "000000002931"
    },
          {
      "credit": 98640,
      "date": "03/01/2017",
      "debit": "",
      "detail": "SUELDOS 123456TT RECIBIDA /Qualia Fintech S.R.L",
      "id": 1303899175,
      "reference": "TR0003858408"
    }
   ],
   "status": "success"
}

Transfer preprocess

Endpoint: `POST /transfer/preprocess`

Parameters	Description
origin_account	Account number from where it’s transferred.
destination_institution	Institution Id where it is transferred. (The id is in the response of the endpoint /account/).
destination_account	Destination account where it is transfered
currency	Code: ISO 4217 of the currency used for the transaction.
amount	Transfer amount.
concept	Concept or description of the transfer.
destination_owner_name	Name of the holder of the destination account (not required).
branch	Branch number of the destination account (not required).

Response

Description

status

result

approved Successfully approved
authorization_devices List of possible verification methods to confirm the transfer (pin number, coordinate card, token, etc). It will be empty if the transfer doesn’t required a verification method.
message Result description of the transfer. Only shown when an error has occurred.
request_id Transaction ID. It’s used to confirm the transaction.

User:

var request = require('request');

request.post({
  "url": "https://test.prometeo.qualia.uy/transfer/preprocess",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "form": {
    "origin_account": "002206345988",
    "destination_institution": 0,
    "destination_account": "001002363321",
    "currency": "UYU",
    "amount": 1.3,
    "concept": "descripcion de transferencia",
    "destination_owner_name": "John Doe",
    "branch": 62
  },
  "qs": {
    "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
  }
});

curl -X POST "https://test.prometeo.qualia.uy/transfer/preprocess?key=959602df-d3ee-4898-b6d8-a28a2c7486fb" -d 'origin_account=002206345988&destination_institution=0&destination_account=001002363321¤cy=UYU&amount=1.3&concept=descripcion+de+transferencia&destination_owner_name=John+Doe&branch=62' -H "X-API-Key: <api key>"

import requests

requests.post('https://test.prometeo.qualia.uy/transfer/preprocess', headers={'X-API-Key': '<api key>'}, params={
  "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
}, data={
  "origin_account": "002206345988",
  "destination_institution": 0,
  "destination_account": "001002363321",
  "currency": "UYU",
  "amount": 1.3,
  "concept": "descripcion de transferencia",
  "destination_owner_name": "John Doe",
  "branch": 62
})

var request = require('request');

request.post({
  "url": "https://test.prometeo.qualia.uy/transfer/preprocess",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "form": {
    "origin_account": "002206345988",
    "destination_institution": 0,
    "destination_account": "001002363321",
    "currency": "UYU",
    "amount": 1.3,
    "concept": "descripcion de transferencia",
    "destination_owner_name": "John Doe",
    "branch": 62
  },
  "qs": {
    "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
  }
});

Response:

{
    "result": {
        "approved": true,
        "authorization_devices": [
            {
                "data": ["F-4", "B-2", "G-7"],
                "type": "cardCode"
            },
            {
                "data": null,
                "type": "pin"
            }
        ],
        "message": null,
        "request_id": "0b7d6b32d1be4c11bde21e7ddc08cc36"
    },
    "status": "success"
}

Transfer confirmation

Endpoint: `POST /transfer/confirm`

Parameters	Description
request_id	Request Id (The id is in the response of the endpoint /transfer/preprocess).
authorization_type	Verification method. The verification method is in the response of the endpoint /transfer/preprocess. It’s not required.
authorization_data	Verification value (pin number, coordinate card, etc). In case of more than one value, they must be separated with commas.

User:

POST /transfer/confirm?key=959602df-d3ee-4898-b6d8-a28a2c7486fb HTTP/1.1
Host: test.prometeo.qualia.uy
Accept: application/json
X-API-Key: <api key>

request_id=0b7d6b32d1be4c11bde21e7ddc08cc36&authorization_type=cardCode&authorization_data=1%2C2%2C3

curl -X POST "https://test.prometeo.qualia.uy/transfer/preprocess?key=959602df-d3ee-4898-b6d8-a28a2c7486fb" -d 'origin_account=002206345988&destination_institution=0&destination_account=001002363321¤cy=UYU&amount=1.3&concept=descripcion+de+transferencia&destination_owner_name=John+Doe&branch=62' -H "X-API-Key: <api key>"

import requests

requests.post('https://test.prometeo.qualia.uy/transfer/preprocess', headers={'X-API-Key': '<api key>'}, params={
  "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
}, data={
  "origin_account": "002206345988",
  "destination_institution": 0,
  "destination_account": "001002363321",
  "currency": "UYU",
  "amount": 1.3,
  "concept": "descripcion de transferencia",
  "destination_owner_name": "John Doe",
  "branch": 62
})

var request = require('request');

request.post({
  "url": "https://test.prometeo.qualia.uy/transfer/confirm",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "form": {
    "request_id": "0b7d6b32d1be4c11bde21e7ddc08cc36",
    "authorization_type": "cardCode",
    "authorization_data": "1,2,3"
  },
  "qs": {
    "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
  }
});

Response:

{
    "status": "success",
    "transfer": {
        "message": "",
        "success": true
    }
}

Institutions for transfers

Endpoint: `POST /transfer/destinations`

User:

var request = require('request');

request.get({
  "url": "https://test.prometeo.qualia.uy/transfer/destinations",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "qs": {
    "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
  }
});

curl -X GET "https://test.prometeo.qualia.uy/transfer/destinations?key=959602df-d3ee-4898-b6d8-a28a2c7486fb"  -H "X-API-Key: <api key>"

import requests

requests.get('https://test.prometeo.qualia.uy/transfer/destinations', headers={'X-API-Key': '<api key>'}, params={
  "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
})

var request = require('request');

request.get({
  "url": "https://test.prometeo.qualia.uy/transfer/destinations",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  },
  "qs": {
    "key": "959602df-d3ee-4898-b6d8-a28a2c7486fb"
  }
});

Response:

{
  "destinations": [
    {
      "id": 0,
      "name": "SANTANDER"
    },
    {
      "id": 1,
      "name": "B.R.O.U."
    },
    {
      "id": 91,
      "name": "B.H.U."
    },
    {
      "id": 110,
      "name": "BANDES"
    }
  ],
  "status": "success"
}

Suppliers list

Endpoint: `GET /provider/`

Response	Description
status
providers	Suppliers list. A supplier is a source of financial data.

User:

GET /provider/? HTTP/1.1
Host: test.prometeo.qualia.uy
Accept: application/json
X-API-Key: <api key>

curl -X GET "https://test.prometeo.qualia.uy/provider/?"  -H "X-API-Key: <api key>"

import requests

requests.get('https://test.prometeo.qualia.uy/provider/', headers={'X-API-Key': '<api key>'})

var request = require('request');

request.get({
  "url": "https://test.prometeo.qualia.uy/provider/",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  }
});

Response:

{
    "providers": [
        {
            "code": "test",
            "country": "UY",
            "name": "Test Provider"
        },
        ...
    ],
    "status": "success"
}

Supplier details

Endpoint `GET /provider/{code}/`

Response	Description
status
providers	Supplier data

User:

GET /provider/test/? HTTP/1.1
Host: test.prometeo.qualia.uy
Accept: application/json
X-API-Key: <api key>

curl -X GET "https://test.prometeo.qualia.uy/provider/test/?"  -H "X-API-Key: <api key>"

import requests

requests.get('https://test.prometeo.qualia.uy/provider/test/', headers={'X-API-Key': '<api key>'})

var request = require('request');

request.get({
  "url": "https://test.prometeo.qualia.uy/provider/test/",
  "json": true,
  "headers": {
    "X-API-Key": "<api key>"
  }
});

Response:

{
    "provider": {
        "auth_fields": [
            {
                "interactive": false,
                "name": "username",
                "type": "text"
            },
            {
                "interactive": false,
                "name": "password",
                "type": "password"
            }
        ],
        "country": "UY",
        "name": "test"
    },
    "status": "success"
}

Questions?

Get in touch

Why could an API help you? (Application Programming Interface)

How could Prometeo help you?

Important items to bare in mind:

For the examples below we’ll use this test data:

Response:

User:

Response:

Wrong response:

Required interaction response:

Login with interaction:

Response:

Wrong response:

Required interaction response:

Login with interaction:

Response:

Wrong response:

Required interaction response:

Login with interaction:

Response:

Wrong response:

Required interaction response:

Login with interaction:

User:

Response:

User:

Successful response:

User:

Response:

User:

Response:

User:

Response:

User:

Response:

User:

Response:

User:

Response:

User:

Response:

Questions?

Get in touch