Accounts

Register Bank Account

Registers an external bank account for your company or for one of your users. The account is created with status in_review and can be used once Kravata approves it (accepted).

Request

Field	Type	Required	Description
Authorization	Header	Yes	`Bearer <access>` obtained from POST /api/token.
clientId	Query	Yes	Your client ID, from GET /api/infoClient. Requests without it are rejected with 401.
userId	Query	No	Register the account for one of your users instead of your company.

Request Body

Field	Type	Required	Description
accountNickname	string	Yes	Alias to identify the account (max 50 characters).
accountNumber	string	Yes	Account number (max 50 characters). For `breb`, the Bre-B key.
accountType	string	Yes	`ahorros` (savings), `corriente` (checking) or `breb` (Colombia’s Bre-B instant payment key).
accountHolderName	string	No	Name of the account holder. Defaults to `accountNickname`.
bankId	integer	Yes, except for `breb`	Bank ID from GET /api/parameters/banks. For `breb` it is resolved automatically from the key.
currencyId	string	Only if the currency is not COP	3-letter currency code, e.g. `MXN` or `USD`. Send it together with `countryId`.
countryId	integer	Only if the currency is not COP	Country of the account. Send it together with `currencyId`.
metadata	array	Depends on the currency	List of `('metadataName', 'metadataValue')`. MXN accounts require `CABLE` (CLABE number) and USD accounts require `ABBA` (ABA routing number). You can add `MEMO` as a transfer reference.

Response

The registered account: id, status (in_review), accountNickname, accountHolderName, accountType, accountNumber, bankId, bank, countryFiatId, metadata, isCustodial and registerDate.

Errors

Status	When
400	Invalid body, account already registered, or invalid country/currency combination.
401	Missing token or `clientId`.

POST

api

accounts

curl --request POST \
  --url https://testapi.kravata.co/api/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountHolderName": "ACME MEXICO SA DE CV",
  "accountNickname": "Main MXN account",
  "accountNumber": "1234567999",
  "accountType": "ahorros",
  "bankId": 1,
  "currencyId": "MXN",
  "countryId": 21,
  "metadata": [
    {
      "metadataName": "CABLE",
      "metadataValue": "100011010"
    },
    {
      "metadataName": "MEMO",
      "metadataValue": "cuenta1234"
    }
  ]
}
'

import requests

url = "https://testapi.kravata.co/api/accounts"

payload = {
    "accountHolderName": "ACME MEXICO SA DE CV",
    "accountNickname": "Main MXN account",
    "accountNumber": "1234567999",
    "accountType": "ahorros",
    "bankId": 1,
    "currencyId": "MXN",
    "countryId": 21,
    "metadata": [
        {
            "metadataName": "CABLE",
            "metadataValue": "100011010"
        },
        {
            "metadataName": "MEMO",
            "metadataValue": "cuenta1234"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountHolderName: 'ACME MEXICO SA DE CV',
    accountNickname: 'Main MXN account',
    accountNumber: '1234567999',
    accountType: 'ahorros',
    bankId: 1,
    currencyId: 'MXN',
    countryId: 21,
    metadata: [
      {metadataName: 'CABLE', metadataValue: '100011010'},
      {metadataName: 'MEMO', metadataValue: 'cuenta1234'}
    ]
  })
};

fetch('https://testapi.kravata.co/api/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://testapi.kravata.co/api/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountHolderName' => 'ACME MEXICO SA DE CV',
    'accountNickname' => 'Main MXN account',
    'accountNumber' => '1234567999',
    'accountType' => 'ahorros',
    'bankId' => 1,
    'currencyId' => 'MXN',
    'countryId' => 21,
    'metadata' => [
        [
                'metadataName' => 'CABLE',
                'metadataValue' => '100011010'
        ],
        [
                'metadataName' => 'MEMO',
                'metadataValue' => 'cuenta1234'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://testapi.kravata.co/api/accounts"

	payload := strings.NewReader("{\n  \"accountHolderName\": \"ACME MEXICO SA DE CV\",\n  \"accountNickname\": \"Main MXN account\",\n  \"accountNumber\": \"1234567999\",\n  \"accountType\": \"ahorros\",\n  \"bankId\": 1,\n  \"currencyId\": \"MXN\",\n  \"countryId\": 21,\n  \"metadata\": [\n    {\n      \"metadataName\": \"CABLE\",\n      \"metadataValue\": \"100011010\"\n    },\n    {\n      \"metadataName\": \"MEMO\",\n      \"metadataValue\": \"cuenta1234\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://testapi.kravata.co/api/accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountHolderName\": \"ACME MEXICO SA DE CV\",\n  \"accountNickname\": \"Main MXN account\",\n  \"accountNumber\": \"1234567999\",\n  \"accountType\": \"ahorros\",\n  \"bankId\": 1,\n  \"currencyId\": \"MXN\",\n  \"countryId\": 21,\n  \"metadata\": [\n    {\n      \"metadataName\": \"CABLE\",\n      \"metadataValue\": \"100011010\"\n    },\n    {\n      \"metadataName\": \"MEMO\",\n      \"metadataValue\": \"cuenta1234\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://testapi.kravata.co/api/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountHolderName\": \"ACME MEXICO SA DE CV\",\n  \"accountNickname\": \"Main MXN account\",\n  \"accountNumber\": \"1234567999\",\n  \"accountType\": \"ahorros\",\n  \"bankId\": 1,\n  \"currencyId\": \"MXN\",\n  \"countryId\": 21,\n  \"metadata\": [\n    {\n      \"metadataName\": \"CABLE\",\n      \"metadataValue\": \"100011010\"\n    },\n    {\n      \"metadataName\": \"MEMO\",\n      \"metadataValue\": \"cuenta1234\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "accountHolderName": "MXN ACCOUUNTS",
  "accountNickname": "MXN ACCOUNT",
  "accountNumber": "1234567999",
  "accountType": "ahorros",
  "bankId": 1,
  "clientId": "08597c65-c25b-4a7c-8c68-f1180bce65f4",
  "id": "181e4661-30bb-4c39-86f3-dd6fe98e4302",
  "metadata": [
    {
      "bankAccountId": "181e4661-30bb-4c39-86f3-dd6fe98e4302",
      "metadataName": "CABLE",
      "metadataValue": "100011010"
    },
    {
      "bankAccountId": "181e4661-30bb-4c39-86f3-dd6fe98e4302",
      "metadataName": "MEMO",
      "metadataValue": "cuenta1234"
    }
  ],
  "status": "in_review"
}

Authorizations

Authorization

string

header

required

Access token from POST /api/token (valid 5 minutes).

Query Parameters

clientId

string

required

userId

string

Optional: register it for one of your users.

Body

application/json

accountHolderName

string

accountNickname

string

accountNumber

string

accountType

string

bankId

integer

currencyId

string

countryId

integer

metadata

object[]

Show child attributes

Response

200 - application/json

accountHolderName

string

accountNickname

string

accountNumber

string

accountType

string

bankId

integer

clientId

string

metadata

object[]

Show child attributes

status

string

curl --request POST \
  --url https://testapi.kravata.co/api/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountHolderName": "ACME MEXICO SA DE CV",
  "accountNickname": "Main MXN account",
  "accountNumber": "1234567999",
  "accountType": "ahorros",
  "bankId": 1,
  "currencyId": "MXN",
  "countryId": 21,
  "metadata": [
    {
      "metadataName": "CABLE",
      "metadataValue": "100011010"
    },
    {
      "metadataName": "MEMO",
      "metadataValue": "cuenta1234"
    }
  ]
}
'

import requests

url = "https://testapi.kravata.co/api/accounts"

payload = {
    "accountHolderName": "ACME MEXICO SA DE CV",
    "accountNickname": "Main MXN account",
    "accountNumber": "1234567999",
    "accountType": "ahorros",
    "bankId": 1,
    "currencyId": "MXN",
    "countryId": 21,
    "metadata": [
        {
            "metadataName": "CABLE",
            "metadataValue": "100011010"
        },
        {
            "metadataName": "MEMO",
            "metadataValue": "cuenta1234"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountHolderName: 'ACME MEXICO SA DE CV',
    accountNickname: 'Main MXN account',
    accountNumber: '1234567999',
    accountType: 'ahorros',
    bankId: 1,
    currencyId: 'MXN',
    countryId: 21,
    metadata: [
      {metadataName: 'CABLE', metadataValue: '100011010'},
      {metadataName: 'MEMO', metadataValue: 'cuenta1234'}
    ]
  })
};

fetch('https://testapi.kravata.co/api/accounts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://testapi.kravata.co/api/accounts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'accountHolderName' => 'ACME MEXICO SA DE CV',
    'accountNickname' => 'Main MXN account',
    'accountNumber' => '1234567999',
    'accountType' => 'ahorros',
    'bankId' => 1,
    'currencyId' => 'MXN',
    'countryId' => 21,
    'metadata' => [
        [
                'metadataName' => 'CABLE',
                'metadataValue' => '100011010'
        ],
        [
                'metadataName' => 'MEMO',
                'metadataValue' => 'cuenta1234'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://testapi.kravata.co/api/accounts"

	payload := strings.NewReader("{\n  \"accountHolderName\": \"ACME MEXICO SA DE CV\",\n  \"accountNickname\": \"Main MXN account\",\n  \"accountNumber\": \"1234567999\",\n  \"accountType\": \"ahorros\",\n  \"bankId\": 1,\n  \"currencyId\": \"MXN\",\n  \"countryId\": 21,\n  \"metadata\": [\n    {\n      \"metadataName\": \"CABLE\",\n      \"metadataValue\": \"100011010\"\n    },\n    {\n      \"metadataName\": \"MEMO\",\n      \"metadataValue\": \"cuenta1234\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://testapi.kravata.co/api/accounts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"accountHolderName\": \"ACME MEXICO SA DE CV\",\n  \"accountNickname\": \"Main MXN account\",\n  \"accountNumber\": \"1234567999\",\n  \"accountType\": \"ahorros\",\n  \"bankId\": 1,\n  \"currencyId\": \"MXN\",\n  \"countryId\": 21,\n  \"metadata\": [\n    {\n      \"metadataName\": \"CABLE\",\n      \"metadataValue\": \"100011010\"\n    },\n    {\n      \"metadataName\": \"MEMO\",\n      \"metadataValue\": \"cuenta1234\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://testapi.kravata.co/api/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"accountHolderName\": \"ACME MEXICO SA DE CV\",\n  \"accountNickname\": \"Main MXN account\",\n  \"accountNumber\": \"1234567999\",\n  \"accountType\": \"ahorros\",\n  \"bankId\": 1,\n  \"currencyId\": \"MXN\",\n  \"countryId\": 21,\n  \"metadata\": [\n    {\n      \"metadataName\": \"CABLE\",\n      \"metadataValue\": \"100011010\"\n    },\n    {\n      \"metadataName\": \"MEMO\",\n      \"metadataValue\": \"cuenta1234\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "accountHolderName": "MXN ACCOUUNTS",
  "accountNickname": "MXN ACCOUNT",
  "accountNumber": "1234567999",
  "accountType": "ahorros",
  "bankId": 1,
  "clientId": "08597c65-c25b-4a7c-8c68-f1180bce65f4",
  "id": "181e4661-30bb-4c39-86f3-dd6fe98e4302",
  "metadata": [
    {
      "bankAccountId": "181e4661-30bb-4c39-86f3-dd6fe98e4302",
      "metadataName": "CABLE",
      "metadataValue": "100011010"
    },
    {
      "bankAccountId": "181e4661-30bb-4c39-86f3-dd6fe98e4302",
      "metadataName": "MEMO",
      "metadataValue": "cuenta1234"
    }
  ],
  "status": "in_review"
}

Guides

API reference

Register Bank Account

Request

Request Body

Response

Errors

Authorizations

Query Parameters

Body

Response