Introduction

This document describes the Ledger API. This API offers a REST service for:

Create accounts
Get account information
Transfer balance between accounts
Get transaction information
Query transactions history for a given account

Environments

We have two independent environments for development and production applications.

Staging: https://staging.apiv2.tpaga.co/api/ledger/v1/public
Production: https://production.apiv2.tpaga.co/api/ledger/v1/public

Quick Start Guide

Once you have an active api-key you can start to use our API to query and transfer funds for your customers.

Here is the detail of each service offered by the API:

Authentication
Create account
Get account information
Create transaction
Get transaction information
Get transactions history

Authentication

An example of a valid request sending the api key:

curl -X POST 'https://staging.apiv2.tpaga.co/api/ledger/v1/public/account' \
  --header 'X-Account-api-key: <Api-Key>'

Requests are authenticated using Api-Key Authentication scheme. The Api-Key is granted by the operations team of Tpaga.

The Api-Key granted by Tpaga should be sent in the X-Account-api-key header. Check an example of a valid request sending the api-key on the right column.

Create Account

Endpoint: /account

HTTP Method: POST

Description: This service allows to open a new account.

Example request:

curl --location --request POST 'https://staging.apiv2.tpaga.co/api/ledger/v1/public/account' \
--header 'X-Account-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "phone_number": "+573334444666",
    "owner_legal_id_type": "NIT",
    "owner_legal_id_number": "12333215",
    "owner_full_name": "test name",
    "owner_email": "test2@name.com"
}'

Example response:

{
    "token": "acc-sen2h7an42w2smdtpqhpscr6bwlh",
    "phone_number": "+573334444666",
    "balance": "0.00",
    "owner": {
        "token": "ow-5xmdi43z3b66c7l1doffwyibmdl19",
        "legal_id_type": "NIT",
        "legal_id_number": "12333215",
        "full_name": "test name",
        "email": "test2@name.com"
    }
}

Request parameters

Field	Description	Type	Required
phone_number	Phone number of the account owner	String	Yes
owner_legal_id_type	Identification type of the account owner. Accepted values:: CC, CE, NIT, TI, PA (passport) and PEP	String	Yes
owner_legal_id_number	Identification number of the account owner	String	Yes
owner_full_name	Full name of the account owner	String	Yes
owner_email	Email of the account owner	String	Yes

Response parameters

Field	Description	Type	Nullable
token	Internal identifier for the account	String	No
phone_number	Phone number of the account owner	String	No
balance	Current balance of the account	String	No
owner -> token	Internal identifier for the account owner	String	No
owner -> legal_id_type	Identification type of the account owner	String	No
owner -> legal_id_number	Identification number of the account owner	String	No
owner -> full_name	Full name of the account owner	String	No
owner -> email	Email of the account owner	String	No

HTTP responses

Code	Description
200	The account already exist
201	The account was created successfully
401	Invalid authorization token was provided
403	You do not have enough permissions to perform this action, please contact the support team
409	Account creation failed. Check response body for details
5XX	Internal sever error, it's safe to retry the request

Get account information

Endpoint: /account/account_token

HTTP Method: GET

Description: This service returns the updated account information.

Example request:

curl --location --request GET 'https://staging.apiv2.tpaga.co/api/ledger/v1/public/account/acc-sen2h7an42w2smdtpqhpscr6bwlh' \
--header 'X-Account-api-key: <api-key>'

Example response:

{
    "token": "acc-sen2h7an42w2smdtpqhpscr6bwlh",
    "phone_number": "+573334444666",
    "balance": "0.00",
    "owner": {
        "token": "ow-5xmdi43z3b66c7l1doffwyibmdl19",
        "legal_id_type": "NIT",
        "legal_id_number": "12333215",
        "full_name": "test name",
        "email": "test2@name.com"
    }
}

Request parameters

Field	Description	Type	Required
account_token	Unique identifier of the account. You receive this token during the account creation	String	Yes

Response parameters

Field	Description	Type	Nullable
token	Internal identifier for the account	String	No
phone_number	Phone number of the account owner	String	No
balance	Current balance of the account	String	No
owner -> token	Internal identifier for the account owner	String	No
owner -> legal_id_type	Identification type of the account owner	String	No
owner -> legal_id_number	Identification number of the account owner	String	No
owner -> full_name	Full name of the account owner	String	No
owner -> email	Email of the account owner	String	No
code	Internal code to identify the error	String	Yes
message	Detailed message related to returned error	String	Yes

HTTP responses

Code	Description
200	An account with the token sent exist and the information is displayed
401	Invalid authorization token was provided
403	You do not have enough permissions to perform this action, please contact the support team
422	The token does not exist
5XX	Internal sever error, it's safe to retry the request

Create Transaction

Endpoint: /transaction

HTTP Method: POST

Description: This service creates a transaction between two accounts.

Example request:

curl --location --request POST 'https://staging.apiv2.tpaga.co/api/ledger/v1/public/transaction' \
--header 'X-Account-api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "origin_account": "acc-sen2h7an42w2smdtpqhpscr6bwlh",
    "destination_account": "acc-ttwhmsaaw9in276w37ev04t66ho5",
    "amount": "1000",
    "description": "test tx",
    "unique_transfer_token": "unique_transfer_token"
}'

Example response:

{
    "token": "tx-56o13n99xglijvcg3rvgb8tuz0ryi",
    "date_created": "2022-12-21T11:26:46.621603Z",
    "origin_account": "acc-sen2h7an42w2smdtpqhpscr6bwlh",
    "origin_account_balance": 9000.0,
    "destination_account": "acc-ttwhmsaaw9in276w37ev04t66ho5",
    "amount": "1000.00",
    "description": "test tx",
    "unique_transfer_token": "unique_transfer_token"
}

Example error response:

{
    "code": "NoFunds",
    "message": "Not enough funds in the origin_account."
}

Request parameters

Field	Description	Type	Required
origin_account	Origin account token. You receive this token during the account creation	String	Yes
destination_account	Destination account token. You receive this token during the account creation	String	Yes
amount	Amount to transfer. Can be string or decimal with two decimal places (e.g. "1000.00")	String	Yes
description	Any description for the transaction	String	Yes
unique_transfer_token	A unique identifier for the transaction.	String	Yes

Response parameters

Field	Description	Type	Nullable
token	Internal identifier for the transaction	String	No
date_created	Date when the transaction was created in our system. Date is returned in ISO format	Date	No
origin_account	Token associated to the account used as origin for the transaction	String	No
origin_account_balance	Balance of the origin account after the transaction was performed	String	No
destination_account	Token associated to the account used as destination for the transaction	String	No
amount	Amount of the transaction	String	No
description	Description provided by the API client to create the transaction	String	No
unique_transfer_token	The token received in the unique_transfer_token field. Use this token to retry transactions safely	String	No
code	Internal code to identify the error	String	Yes
message	Detailed message related to returned error	String	Yes

HTTP responses

Code	Description
201	The transaction was processed successfully
208	Transaction with unique_transfer_token already exists
401	Invalid authorization token was provided
402	You have no funds. Please top up your account and contact our support team to keep operating
403	You do not have enough permissions to perform this action, please contact the support team
422	You did not provide valid data for this operation, please check response body for details
5XX	Internal sever error, it's safe to retry the request using the same unique_transfer_token

Get transaction information

Endpoint: /transaction/unique_transfer_token

HTTP Method: GET

Description: This service is useful to get the information about a specific transaction.

Example request:

curl --location --request GET 'https://staging.apiv2.tpaga.co/api/ledger/v1/public/transaction/<unique_transfer_token>' \
--header 'X-Account-api-key: <api-key>'

Example response:

{
    "token": "tx-56o13n99xglijvcg3rvgb8tuz0ryi",
    "date_created": "2022-12-21T11:26:46.621603Z",
    "origin_account": "acc-sen2h7an42w2smdtpqhpscr6bwlh",
    "origin_account_balance": 7000.0,
    "destination_account": "acc-ttwhmsaaw9in276w37ev04t66ho5",
    "amount": "1000.00",
    "description": "test tx",
    "unique_transfer_token": "unique_transfer_token"
}

Request parameters

Field	Description	Type	Required
unique_transfer_token	The `unique_transfer_token` that was used to create the transaction.	String	Yes

Response parameters

Field	Description	Type	Nullable
token	Internal identifier for the transaction	String	No
date_created	Date when the transaction was created in our system. Date is returned in ISO format	Date	No
origin_account	Token associated to the account used as origin for the transaction	String	No
origin_account_balance	Balance of the origin account after the transaction was performed	String	No
destination_account	Token associated to the account used as destination for the transaction	String	No
amount	Amount of the transaction	String	No
description	Description provided by the API client to create the transaction	String	No
unique_transfer_token	The token received in the unique_transfer_token field. Use this token to retry transactions safely	String	No
code	Internal code to identify the error	String	Yes
message	Detailed message related to returned error	String	Yes

HTTP responses

Code	Description
200	The transaction information was queried successfully
401	Invalid authorization token was provided
403	You do not have enough permissions to perform this action, please contact the support team
422	You did not provide valid data for this operation, please check response body for details
5XX	Internal sever error, it's safe to retry the request

Get transactions history

Endpoint: /account/account_token/transactions

HTTP Method: GET

Description: This service returns a list of transactions associated with the given account token.

Example request:

curl --location --request GET 'https://staging.apiv2.tpaga.co/api/ledger/v1/public/account/acc-sen2h7an42w2smdtpqhpscr6bwlh/transactions' \
--header 'X-Account-api-key: <api-key>'

Example response:

{
    "transactions": [
        {
            "token": "tx-e2eyf5h0nh5g8wpuqn1t9wpa7i1q7",
            "date_created": "2022-12-21T12:19:45.010925Z",
            "origin_account": "acc-sen2h7an42w2smdtpqhpscr6bwlh",
            "origin_account_balance": 7000.0,
            "destination_account": "acc-ttwhmsaaw9in276w37ev04t66ho5",
            "amount": "1000.00",
            "description": "test tx",
            "unique_transfer_token": "tx123456789"
        },
        {
            "token": "tx-icqag40m3cfyyx6hir6c3jcof27mj",
            "date_created": "2022-12-21T12:13:54.421678Z",
            "origin_account": "acc-sen2h7an42w2smdtpqhpscr6bwlh",
            "origin_account_balance": 7000.0,
            "destination_account": "acc-ttwhmsaaw9in276w37ev04t66ho5",
            "amount": "1000.00",
            "description": "test tx",
            "unique_transfer_token": "unique-transfer-token-id"
        },
        {
            "token": "tx-56o13n99xglijvcg3rvgb8tuz0ryi",
            "date_created": "2022-12-21T11:26:46.621603Z",
            "origin_account": "acc-sen2h7an42w2smdtpqhpscr6bwlh",
            "origin_account_balance": 7000.0,
            "destination_account": "acc-ttwhmsaaw9in276w37ev04t66ho5",
            "amount": "1000.00",
            "description": "test tx",
            "unique_transfer_token": "unique_transfer_token"
        }
    ]
}

Request parameters

Field	Description	Type	Required
account_token	Unique identifier of the account. You receive this token during the account creation	String	Yes

Response parameters

Field	Description	Type	Nullable
transactions	List of transactions associated with the given account	List	No
transactions -> token	Internal identifier for the transaction	String	No
transactions -> date_created	Date when the transaction was created in our system. Date is returned in ISO format	Date	No
transactions -> origin_account	Token associated to the account used as origin for the transaction	String	No
transactions -> origin_account_balance	Balance of the origin account after the transaction was performed	String	No
transactions -> destination_account	Token associated to the account used as destination for the transaction	String	No
transactions -> amount	Amount of the transaction	String	No
transactions -> description	Description provided by the API client to create the transaction	String	No
transactions -> unique_transfer_token	The token received in the unique_transfer_token field. Use this token to retry transactions safely	String	No
code	Internal code to identify the error	String	Yes
message	Detailed message related to returned error	String	Yes

HTTP responses

Code	Description
200	Account transactions history was queried successfully
401	Invalid authorization token was provided
403	You do not have enough permissions to perform this action, please contact the support team
422	The token provided does not exist
5XX	Internal sever error, it's safe to retry the request