Ledger API

In this document the Ledger API is described. It allows users to manage funds in their Tpaga accounts.

Overview of the service

There are several actions available for the users:

  • Create or retrieve an Account (admins)
  • Query the balance of an Account
  • Transfer an amount from an origin account to a destination account

Creating an Account

In order to create a new account,

  • your back-end system performs a request to our API (/account) asking to create the account with the provided phone number and owner data, and
  • Tpaga validates the data, and creates the new account. If there is an inconsistency (e.g., the account already exists), it will be reported back,

following the sequence shown below:

@startuml title Creating a Ledger Account participant "Client" as client participant "Tpaga API\nLedger" as api #d3ffef client -> api : ""POST /api/ledger/v1/account/""\n**phone_number:** +573002559876\n**owner_legal_id_type:** CC\n**owner_legal_id_number:** 12345678\n**owner_full_name:** John Smith\n**owner_email:** john@smith.com alt the Account already exists api -> client : ""HTTP 200""\n**token:** 1234567\n**phone_number:** +573002559876\n**balance:** 1000.99\n**owner:**\n **token:** 345678\n **legal_id_type:** CC\n **legal_id_number:** 12345678\n **full_name:** John Smith\n **email:** john@smith.com\n**api_key:** 54321 ||| else the Account has been created api -> client : ""HTTP 201""\n**token:** 1234567\n**phone_number:** +573002559876\n**balance:** 0.0\n**owner:**\n **token:** 345678\n **legal_id_type:** CC\n **legal_id_number:** 12345678\n **full_name:** John Smith\n **email:** john@smith.com\n**api_key:** 54321 ||| else forbidden api -> client : ""HTTP 403"" ||| else Account not created; the Owner already has\n an Account with a different phone_number api -> client : ""HTTP 406""\n**token:** 1234567\n**phone_number:** +573002559876\n**balance:** 1000.99\n**owner:**\n **token:** 345678\n **legal_id_type:** CC\n **legal_id_number:** 12345678\n **full_name:** John Smith\n **email:** john@smith.com\n**api_key:** 54321 ||| else Account not created; there is already a\n different Owner with another Account\n with the same phone number api -> client : ""HTTP 409""\n**token:** 1234567\n**phone_number:** +573002559876\n**balance:** 1000.99\n**owner:**\n **token:** 345678\n **legal_id_type:** CC\n **legal_id_number:** 12345678\n **full_name:** John Smith\n **email:** john@smith.com\n**api_key:** 54321 ||| else Unprocessable Entity; you did not provide\n valid data for this operation api -> client : ""HTTP 422""\n**error_message:** <string>\n**field:** <string>\n**value:** <string> end @enduml

Consulting my Account Balance

You can query the balance of your account by passing its API key as a header; the following sequence of events takes place:

@startuml title Consulting a Ledger Account Balance participant "Client" as client participant "Tpaga API\nLedger" as api #d3ffef client -> api : ""GET /api/ledger/v1/my/balance/"" alt an account object containing\nthe balance information api -> client : ""HTTP 200""\n**token:** 1234567\n**phone_number:** +573002559876\n**balance:** 1000.99\n**owner:**\n **token:** 345678\n **legal_id_type:** CC\n **legal_id_number:** 12345678\n **full_name:** John Smith\n **email:** john@smith.com\n**api_key:** 54321 ||| else forbidden api -> client : ""HTTP 403"" end @enduml

Creating a Transfer

To perform a transfer from your account to another account, follow the steps shown below:

@startuml title Transferring funds to Another Account participant "Client" as client participant "Tpaga API\nLedger" as api #d3ffef client -> api : ""POST /api/ledger/v1/my/transfer/""\n**destination_account:** +573002559876\n**amount:** 1000.99\n**description:** "string"\n**unique_transfer_token:** "string" alt The Transfer has been\n created successfully. api -> client : ""HTTP 201""\n**token:** 1234567\n**date_created:** 2017-07-18T10:55:22-05:00\n**origin_account:** +573002559876\n**origin_account_balance:** 1100.99\n**destination_account:** +573002001122\n**amount:** 1000.99\n**description:** "string"\n**unique_transfer_token:** "string" ||| else There is already a Transfer with the same\n idempotency token. Its data is returned.\nNo new transfers were made. api -> client : ""HTTP 208""\n**token:** 1234567\n**date_created:** 2017-07-18T10:55:22-05:00\n**origin_account:** +573002559876\n**origin_account_balance:** 1100.99\n**destination_account:** +573002001122\n**amount:** 1000.99\n**description:** "string"\n**unique_transfer_token:** "string" ||| else Not enough funds in the origin_account. api -> client : ""HTTP 402"" ||| else Forbidden. api -> client : ""HTTP 403"" ||| else Unprocessable Entity; you did not provide\n valid data for this operation. api -> client : ""HTTP 422""\n**error_message:** "string"\n**field:** "string"\n**value:** "string" end @enduml

Authentication

To use this API you must have an API key, which Tpaga will provide you, both for our staging (sandbox) and production environments.

Once you have it, you can authenticate your requests by adding the Authorization HTTP header, and passing the API key as the value for that header. For example, if the API key is mak-1234512345, then you must send the HTTP header Authorization: mak-1234512345 with all of your requests to this API.

Endpoints

HTTP responses common to all endpoints

If you do not provide an authentication header, or send it with the wrong API Key, you will receive a response with an HTTP 401 code.

If there is any validation error in the data received, like a missing field or a field with a data type different from the one required, the endpoint will return an HTTP 422 code.

When there is a temporary failure in Tpaga’s systems, this endpoint will return an HTTP 503 code. It is possible to retry the request later.

/account

This endpoint creates an account, and its associated Owner. There can only be one Owner (identified by its legal id), and one Account per Owner (the account is identified by its phone number). You will require a special permission to use this endpoint.

Non-retryable failed requests

In the following situations, it makes no sense to retry the request:

  • When your API key does not have the necessary permission, HTTP 403 (forbidden) will be returned.
  • When the Account and Owner’s data conflicts with any other Account or Owner.
    • If the Owner already posses an account, HTTP 406 (Account not created; the Owner already has an Account with a different phone number) will be returned.
    • If the Account is already linked to an Owner, HTTP 409 (Account not created; there is already a different Owner with another Account with the same phone number)
  • When invalid data is provided, or there is a missing field, the endpoint will return HTTP 422.

Retryable failed requests

Under certain conditions, this endpoint might return an HTTP 503 code. In this situation, we can guarantee that we did not create the account, and it is safe to retry the request.

/my/balance

You can consult the current balance of your account using this endpoint, and its associated API key.

Non-retryable failed requests

In the following situations, it makes no sense to retry the request:

  • When your API key does not have the necessary permission, HTTP 403 (forbidden) will be returned.

Retryable failed requests

Under certain conditions, this endpoint might return an HTTP 503 code. In this situation, it is safe to retry the request.

/my/transfer

You can make a transfer to another account using this endpoint and the phone number associated with the destination account.

Non-retryable failed requests

In the following situations, it makes no sense to retry the request:

  • When you have insufficient funds to transfer, HTTP 402 (Not enough funds in the origin_account) will be returned.
  • When your API key does not have the necessary permission, HTTP 403 (forbidden) will be returned.
  • When invalid data is provided, or there is a missing field, the endpoint will return HTTP 422.

Retryable failed requests

Under certain conditions, this endpoint might return an HTTP 503 code. In this situation, we can guarantee that we did not modified the user funds, and it is safe to retry the request.