NAV Navbar
JavaScript (Socket.IO) PHP (REST)
  • Introduction
  • Supported APIs
  • Authentication
  • Sessions
  • Security
  • Profile
  • KYC/AML
  • Currencies
  • Wallets
  • Transactions
  • Withdrawals
  • Deposits
  • Contacts
  • EVouchers
  • Invoices
  • Enumerations
  • CapPay
  • IMTP
  • Introduction

    Welcome to Capitual's Developers Portal!

    Capitual offers different ways to integrate your business, application, IoT-connected device, smart vending machine or internal company procedures easily. The entire Core Banking system that powers Capitual is available to anyone through these APIs just on the same way that it is available for Capitual Team (therefore, our main interface also makes use of these APIs).

    We also offer IMTP, a protocol that runs at the top of TCP/IP and makes it easy and bandwidth-friendly to request actions that runs in Capitual accounts.

    We are available to help at Slack. We hope you enjoy developing with Capitual.

    The Developer Agreement

    In order to use our API, you must agree and follow our developers guidelines.

    Read our developers agreement here.

    Supported APIs

    When using the following APIs, you are required to generate a device fingerprint for your user's device. This argument is named "device", must be present in every request and must be a string. While we do not set up a standard for the fingerprint generation, we do participate on the process of recognizing the machine. Therefore, you should not supply the same device fingerprint in two different devices as it will most likely cause your session to close.

    Your application may access Capitual through one of the following methods. The same endpoints and variables apply for any of the platforms.

    REST

    We provide a HTTP REST API on the following base URL:

    https://api.capitual.com/1.0.0/

    It only accepts POST requests and URL-encoded or JSON-encoded arguments. Exceptions are thrown using different valid HTTP status code, but these are not as relevant as the actual exception message.

    Since our endpoints use object notation, you have to convert it to a HTTP path before calling any endpoint. This is done basically by replacing dots (".") into slashes ("/"). Say an endpoint, "members.login", this is how you would refer to it when using REST:

    https://api.capitual.com/1.0.0/members/login

    If the endpoint contains no dots, then no conversion is needed:

    https://api.capitual.com/1.0.0/profile

    Every REST response is a JSON object with the following structure:

    { "error": ErrorCode as string, "data": any }

    If no error occured, error property will be the boolean false, whereas data will contain the response from the endpoint you've called.

    If, however, some error occured, then error will contain a string with the error name (alphanumeric). Each endpoint contains its possible error code and you should check for them after receiving the response from the endpoint.

    WebSocket

    We provide a Socket.IO server at:

    https://api.capitual.com

    Every Socket.IO call is made up of:

    A basic example could be:

    socket.emit('members.login', {
        // ...arguments
        },
        (error, data) => {
            if (!error) {
                // use data
            } else {
                // something went wrong
            }
        }
    )
    
    <?php
    // Sorry, this example is not available for PHP
    

    Authentication

    This API allows you to authenticate users and, given one login/password combination, get a session ID that will allow you to perform actions on the user's behalf.

    Capitual requests require an additional sess_key with the session ID that your application received during the login process. A session ID is made up by 100 alphanumeric chars and, by default, does not expire.

    You cannot use the same session key in different applications, as it will most likely cause the system to close the session.

    A session key may also become unavailable if the user manually closes it on Active Sessions.

    Login

    Perform login.

    Request

    Endpoint

    members.login

    Parameters

    Name Type Description Example
    login string User's identification (email or telephone) [email protected]
    password string User's password (secure password here)
    otp_token (optional) string User's OTP or email token 123456

    Return Value

    Success

    A string containing the session ID.

    Failure

    Exception Description
    InvalidUsername The provided user identifier (email or telephone) could not be related to any user
    InvalidPassword The provided password is invalid
    RequestedOTPToken The otp_token argument is required and the user has set up a 2-factors authentication (2FA) app
    RequestEmailToken The otp_token argument is required and the login token has been sent by email to the user
    InvalidOTPToken The provided 2FA token is invalid
    InvalidEmailToken The provided email token is invalid
    UserIsDisabled The account has been disabled by the administration

    Logout

    Closes a session.

    Request

    Endpoint

    members.logout

    Arguments

    Name Type Description Example
    sess_key string Session ID (as returned by members.login abcdefghijkl...

    Return value

    This endpoint does not return any value.

    Check Sessions

    Checks if a session is active.

    Request

    Endpoint

    members.logout

    Arguments

    Name Type Description Example
    sess_key string Session ID (as returned by members.login abcdefghijkl...

    Return value

    Boolean (true or false).

    Registration

    This API provides resources for creating a new user.

    Request

    Endpoint

    members.register

    Arguments

    Name Type Description Example
    email or phone string User's email or phone number "[email protected]" or "+13239431020"
    password (optional) string User's password. If not provided, it will be requested later by email or SMS. "(secure password)"
    locale string User's locale (a IETF language code or a ISO 639-1 country code) "en-US", "en"

    Return value

    Success

    A string containing a new session ID for the newly created user.

    Failure

    Exception Description
    InvalidEmailAddress The provided email address is invalid
    EmailExists The provided email is already related to another account
    PhoneExists The provided phone number is already related to another account
    NeedEmailOrPhone Neither email or phone has been provided

    Remarks

    After the signup process, the user is able to perform several actions on his account. In parallel, the user has received instructions about how to continue by email or SMS: confirm the contact information and, if not provided yet, create a password.

    Re-send Signup Email

    The user may request a new signup email if the original email with signup instructions has not been received or has been lost.

    If you are implementing a login page, it's recommended to call this endpoint as soon as you receive the user's email address, regardless of it being already confirmed or not. In this case and only in this case, it is safe to ignore the "InvalidEmail" exception mentioned below.

    Request

    Endpoint

    members.resendSignupEmail

    Arguments

    Name Type Description Example
    email string User email address [email protected]

    Return value

    Success

    Boolean (true).

    Failure

    Exception Description
    InvalidEmail The provided email address is invalid, does not exist or has been confirmed, already
    MustWait90sInterval It's needed to wait 90 seconds after requesting an email, before requesting it again

    Re-send Signup SMS

    The user may request a new signup SMS if the original message with signup instructions has not been received or has been lost.

    If you are implementing a login page, it's recommended to call this endpoint as soon as you receive the user's phone number, regardless of it being already confirmed or not. In this case and only in this case, it is safe to ignore the "InvalidPhoneNumber" exception mentioned below.

    Request

    Endpoint

    members.resendSignupEmail

    Arguments

    Name Type Description Example
    phone string User phone number +13239431020

    Return value

    Success

    Boolean (true).

    Failure

    Exception Description
    InvalidPhoneNumber The provided phone number is invalid, does not exist or has been confirmed, already
    MustWait90sInterval It's needed to wait 90 seconds after requesting a SMS, before requesting it again

    Recover Password

    This endpoint controls the entire password recovering process.

    Request

    Endpoint

    members.recoverPassword

    Arguments

    Name Type Description Example
    email_or_phone string User's email or phone "[email protected]" or "+13239431020"
    token (Optional) string The token that has been sent to the user, if already provided "123456"
    sendTokenBy (Optional) string How to receive the token. By default, the system will send to the available method, or return the status MultipleMethods if multiple methods are available (in this case, you have to provide sendTokenBy) "email" or "sms"
    new_password (Optional) string New password (must be used with token) (secure password here)

    Return value

    Success

    { "status": "ok", "method": "sms" or "email" }

    { "status": "MultipleMethods", "methods": ["sms", "email"] }

    Failure

    Exception Description
    InvalidUsername The provided email_or_phone is invalid
    InvalidToken The provided token is invalid
    MustConfirmAccount The account has not been confirmed yet (and a new signup email has been sent)
    MustConfirmUseEmail The provided method is unavailable. Please use email as sendTokenBy
    InvalidReceivingMethod The provided sendTokenBy is invalid

    Sessions

    This is still to be written.

    Security

    This is still to be written.

    Privacy

    This is still to be written.

    Profile

    This is still to be written.

    KYC/AML

    This is still to be written.

    Currencies

    Currencies in Capitual are a dynamic and constantly changing list, due to new listings and features added.

    Capitual currencies are virtual internal tokens with values that follow the market price of each asset type they refer to. The reference assets' types are:

    Currencies are defined as a CurrencyInfo structure:

    CurrencyInfo {
        "id" : integer, // numeric ID
        "type" : string, // currency type
        "precision" : integer, // number of places after the decimal point
        "name" : string, // currency human-readable capitalized name
        "symbol" : string, // currency prepended symbol
        "iso_code" : string, // currency ISO-4217 or alike code
        "is_pivot" : integer, // 1 if this is the current pivot currency, 0 if not
        "separator" : string, // currency thousand separator symbol
        "decimal" : string, // currency decimal separator symbol
        "ask" : float, // ask price, in the pivot currency
        "bid" : float, // bid price, in the pivot currency
    }
    

    Capitual users are able to perform currency exchanges in multiple ways:

    Some currency exchanges are not possible due to law implications. For example, Brazilian Central Bank does not allow exchanging Brazilian Reais (BRL) to other fiat currencies, or the opposide way. Although Capitual is not a Brazilian entity, its partners are Brazilian entities and therefore could not be involved with operations that are considered illegal by Brazilian law.

    Listing available currencies

    This endpoint returns all supported currencies and meta data.

    This request does not need to be authenticated.

    Request

    Endpoint

    currencies.getCurrencies

    Test in browser

    Return Value

    Returns Array<CurrencyInfo>.

    Checking Currency Exchange

    This endpoint tests a currency exchange quote.

    This request does not need to be authenticated. However, if the context includes a logged-in user, it's important to pass the user's sess_key as there are special segments of users with a different quote pricing.

    Request

    Endpoint

    currencies.currencyExchange

    Name Type Description Example
    from_currency string or integer ISO-4217 or alike code or numeric ID for the origin currency "BTC", 1
    to_currency string or integer ISO-4217 or alike code or numeric ID for the destination currency "BTC", 1
    amount string Amount, with dot as decimal separator "1.50"

    Return value

    Success

    The data section of the return value contains a float with the resulting quote, in the to_currency currency.

    Failure

    Exception Description
    InvalidCurrency One or more used currencies are invalid (check its code or numeric ID)
    InvalidExchange Such exchange is not allowed by law

    Wallets

    Capitual accounts are multi-wallet. Users can store their funds in these wallets, as well as create new wallets, edit or delete the existing wallets.

    At the moment of the account creation, the system creates, automatically, one wallet per supported currency for the user. The user is, however, free to create new wallets or delete the wallets that were created by the system.

    Wallets Addresses

    Wallets are referenced by addresses, on the form:

    CAP-XXXXXXXX-XXXXXX-NN

    Where:

    Wallets Privacy

    Wallets have two basic privacy settings:

    The wallet's privacy flags are set through a PrivacyFlags structure.

    PrivacyFlags {
        isPublic : boolean,
        isOwnerInfoPublic : boolean
    }
    

    WalletInfo struct

    Wallets are referenced following the WalletInfo struct:

    WalletInfo {
        owner : integer, // owner UID
        wallet_name : string, // wallet name
        is_public : integer,
        is_owner_info_public : integer,
        ordering : integer,
        wallet_address : string,
        currency : CurrencyStruct
    }
    
    CurrencyStruct {
        type : string // "crypto", "fiat" or "metal"
        precision : integer, // how many decimals it uses
        name : string, // currency human-readable name
        symbol: : string, // currency symbol (e.g. $)
        iso_code : string // ISO-4217 code (e.g. USD)
    }
    

    Creating Wallets

    Creates a wallet under the user account.

    Request

    Endpoint

    wallets.createWallet

    Parameters

    Name Type Description Example
    currency string ISO-4217 code of the wallet currency or crypto-currency code (must be a supported currency) "USD", "BTC"
    name string Wallet name (user-provided). The maximum supported characters number is 255, but a shorter name is recommended. Supported characters are: A-Z a-z (including accented characters) 0-9 - _ # & and whitespace "My Bitcoins", "Funds for Vacations"
    data PrivacyFlags Wallet's privacy flags {"isPublic":true, "isOwnerInfoPublic":false}
    owner (optional) integer The owner account UID, if the user is creating the account on behalf of an organization 100034, null

    Return Value

    Success

    A string containing the wallet address.

    Failure

    Exception Description
    Unauthorized The user has no rights to create a wallet in behalf of owner
    InvalidName The wallet name is invalid or contains invalid characters
    InvalidCurrency Invalid or unsupported currency

    Modifying Wallets

    Edit the wallet's name and privacy flags

    Request

    Endpoint

    wallets.modifyWallet

    Parameters

    Name Type Description Example
    wallet_id string Wallet address "CAP-XXXXXXXX-XXXXXX-NN"
    name (optional) string Wallet name (user-provided). The maximum supported characters number is 255, but a shorter name is recommended. Supported characters are: A-Z a-z (including accented characters) 0-9 - _ # & and whitespace "My Bitcoins", "Funds for Vacations"
    data PrivacyFlags Wallet's privacy flags {"isPublic":true, "isOwnerInfoPublic":false}
    owner (optional) integer The owner account UID, if the user is creating the account on behalf of an organization 100034, null

    Return value

    Success

    true

    Failure

    Exception Description
    InvalidWallet A wallet which address is wallet_id does not exist
    Unauthorized The user has no rights to edit a wallet in behalf of owner
    InvalidName The wallet name is invalid or contains invalid characters

    Deleting Wallets

    Deletes a wallet.

    Wallets with funds cannot be deleted.

    Request

    Endpoint

    wallets.deleteWallet

    Parameters

    Name Type Description Example
    wallet_id string Wallet address "CAP-XXXXXXXX-XXXXXX-NN"

    Return Value

    Success

    true

    Failure

    Exception Description
    InvalidWallet A wallet which address is wallet_id does not exist
    Unauthorized The user has no rights to delete a wallet in behalf of owner
    WalletHasFunds Wallet's balance is not zero

    Listing User Wallets

    Lists the wallets belonging to the currently logged in user (identified by sess_key) or to an organization controlled by the logged in user.

    Note: this method cannot be used to list any user's public wallets. To do so, please see the next chapter.

    Request

    Endpoint

    wallets.getUserWallets

    Parameters

    Name Type Description Example
    wallet_id (optional) string Wallet address, if you want to get only one wallet's data
    user_id integer The owner account UID, if the user is listing wallets of an organization 100034, null

    Return value

    Success

    If wallet_id is set, it returns a WalletInfo struct. Otherwise, it returns Array<WalletInfo>.

    Failure

    Exception Description
    Unauthorized The user has no rights to list user_id's wallets

    Listing One's Public Wallets

    This is still to be written.

    Transactions

    This is still to be written.

    Withdrawals

    This is still to be written.

    Deposits

    This is still to be written.

    Contacts

    This is still to be written.

    EVouchers

    This is still to be written.

    Invoices

    This is still to be written.

    Enumerations

    This is still to be written.

    CapPay

    CapPay documentation is available in CapPay Merchants Central.

    Please refer to Merchants Central for all the information regarding the public API and available SDKs.

    IMTP

    This is still to be written.