NAV
shell

Introduction

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

Environments

We have two independent environments for development and production applications.

Quick Start Guide

Once you have an active access_token you can start to use our API to open and manage accounts for your customers.

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

  1. Authentication

  2. Create account

  3. Get account information

  4. Transfer funds

  5. Revert transaction

  6. Get transactions history

Authentication

An example of a valid request sending the authorization token:

curl -X POST 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/accounts/create' \
  --header 'Authorization: Token <<access_token>>'

Requests are authenticated using token-based HTTP Authentication scheme. The token is granted by the operations team of Tpaga. Check an example of a valid request sending the authorization token on the right column.

Create account

Endpoint: /accounts/create

HTTP Method: POST

Description: This service allows to create a new account.

Example request:

curl -X POST 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/accounts/create' \
  --header 'Authorization: Token <<access_token>>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "identification_number": "99945678",
      "identification_type": "CC",
      "identification_issued_at": "2019-03-19",
      "mobile_phone_number": "3528881234",
      "email": "testrandom1@gmail.com",
      "names": "Nigerio",
      "first_last_name": "Numa",
      "sex": "M",
      "date_of_birth": "1999-01-25"
  }'

Example response:

{
    "token": "coopacc-56165a6e86a14eaba2a771df2edc4b5a",
    "account_type": "deposito_electronico",
    "number": "891000823",
    "balance": "0.00",
    "expected_balance": "0.00",
    "awaited_amount": null,
    "overdraft_amount": "0.00",
    "deposited_this_month": null,
    "withdrawn_this_month": null
}

Request parameters

Field Description Type Required
identification_number Document number String yes
identification_type Document type (Allowed types: CC, CE) String yes
identification_issued_at Document issue date on YYYY-MM-DD format Date yes
mobile_phone_number Client mobile phone number without country code String yes
email Client email String yes
names Personal names String yes
first_last_name First last name String yes
second_last_names Other last names String no
sex Client sex String yes
date_of_birth Birth date on YYYY-MM-DD format String yes

Response parameters

Field Description Type Nullable
token Unique identifier for the new account String no
account_type Type of the new account. Only deposito_electronico is supported currently String no
number Number that identifies the account within the bank String no
balance Current balance of the account String no
expected_balance Total balance (may be outdated). Includes awaited balance String no
awaited_amount Awaited balance of the account String yes
overdraft_amount Overdraft allowed for the new account (default to 0) String no
deposited_this_month Total cashin received on the current month String yes
withdrawn_this_month Total cashout made on the current month String yes
error_code Internal code to identify the error String yes
error_message Detailed message related to returned error String yes
field Name of the field that presents errors in the give request body String yes

HTTP responses

Code Description
201 Account was created successfully
208 Account already exists in our system
401 Invalid authorization token provided
403 You do not have enough permissions to perform this action, please contact the support team
409 Account can not be created with the given data, check error_code and error_message in the response body for details
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

Test data to create accounts

This data should be used to create test accounts in the staging environment.

Field Accepted test values
identification_number Values ending in 45678 (eg. 11145678, asd45678, 45645678)
identification_type CC
identification_issued_at 2019-03-19
mobile_phone_number Any valid Colombian phone number (10 digits) starting with 352 (eg. 3523211234, 3528898765, 3528763456)
email This email must not exists in the database. Send any random email on each request to create new accounts
names Nigerio
first_last_name Numa
sex M/F
date_of_birth Any date before 2000-01-01 (eg. 1988-02-10, 1950-10-20, 1999-01-25)

Get account information

Endpoint: /accounts/balance

HTTP Method: GET

Description: This service returns updated information about the account such as balances and monthly transactional limits

Example request:

curl -X GET 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/accounts/balance?account_token=<<account_token>>' \
  --header 'Authorization: Token <<access_token>>'

Example response:

{
    "token": "coopacc-56165a6e86a14eaba2a771df2edc4b5a",
    "account_type": "deposito_electronico",
    "number": "891000823",
    "balance": "0.00",
    "expected_balance": "0.00",
    "awaited_amount": "0.00",
    "overdraft_amount": "0.00",
    "deposited_this_month": "0.00",
    "withdrawn_this_month": "0.00",
    "account_status": "active",
    "updated_at": "2023-03-22T20:28:17.777472-05:00",
    "updated_from_source": "True",

}

Request parameters

Field Description Type Required
account_token Unique identifier of the account String yes

Response parameters

Field Description Type Nullable
token Unique identifier for the new account String no
account_type Type of the new account. Only deposito_electronico is supported currently String no
number Number that identifies the account within the bank String no
balance Current balance of the account String no
expected_balance Total balance (may be outdated). Includes awaited balance String no
awaited_amount Awaited balance of the account String yes
overdraft_amount Overdraft allowed for the new account (default to 0) String no
deposited_this_month Total cashin received on the current month String yes
withdrawn_this_month Total cashout made on the current month String yes
error_code Internal code to identify the error String yes
error_message Detailed message related to returned error String yes
field Name of the field that presents errors in the give request body String yes
value Value received in the field that presents errors String yes
account_status Indicates account status, by default it is active. In case the account has been canceled or deleted, the status will be "cancelled" String no
updated_from_source Indicates if the account information was updated directly against the bank or if it was taken from the local database and may be out of date Boolean no
updated_at Last update date of account information Datetime no

HTTP responses

Code Description
200 Account information was queried successfully
401 Invalid authorization token provided
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

Transfer funds

Endpoint: /transactions/create

HTTP Method: POST

Description: This service allows to transfer funds between two accounts.

Example request:

curl -X POST 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/transactions/create' \
  --header 'Authorization: Token <<access_token>>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "origin_account": "coopacc-45114ed15621463f9b3063433f123bbf",
      "destination_account": "coopacc-c3b938a4762c440bb9c1a08ff694f976",
      "unique_transfer_token": "some-random-and-unique-token124",
      "amount": 100,
      "description": "Test transaction",
      "channel": "wallet"
  }'

Example response:

{
    "token": "cooptx-5a35c5dfdcbf4ae79f4759bd8d809460",
    "status": "approved",
    "idempotency_token": "some-random-and-unique-token124",
    "origin_account": "coopacc-45114ed15621463f9b3063433f123bbf",
    "destination_account": "coopacc-c3b938a4762c440bb9c1a08ff694f976",
    "amount": "100.00",
    "description": "Prueba exitosa",
    "created_at": "2022-06-20T20:28:17.777472-05:00",
    "result_message": "Proceso Exitoso",
    "error_code": null,
    "channel": "wallet"
}

Request parameters

Field Description Type Required
unique_transfer_token A unique identifier for the transaction. Use this token to retry transactions safely String yes
origin_account Origin account token identifier String yes
destination_account Destination account token identifier String yes
channel Identifier for external systems, please send external as value on this field. String yes
amount Amount of the transaction Float yes
description Description provided by the API client to create the transaction String yes
fee_amount Fee amount of the transaction, this value Float no

Response parameters

Field Description Type Nullable
token A unique identifier for the transaction at Tpaga's systems String no
status Status of the transaction. See Transaction statuses for details String no
idempotency_token The token received in unique_transfer_token from the client. Use this token to retry transactions safely String no
origin_account Origin account token identifier String no
destination_account Destination account token identifier String no
amount Amount of the transaction String no
description Description provided by the API client to create the transaction String no
created_at Date when the transaction was created in our system. Date is returned in ISO format Date no
result_message A message describing transaction result String yes
channel Identifier for external systems String no
error_code Internal code to identify the error String yes
error_message Detailed message related to returned error String yes
field Name of the field that presents errors in the give request body String yes

Transaction statuses

HTTP responses

Code Description
201 The transaction was processed successfully
208 There is already a transaction with the same unique_transfer_token. It's data will be returned. No new transfers were made.
401 Invalid authorization token provided
403 You do not have enough permissions to perform this action, please contact the support team
409 Transaction failed, it's safe to retry the transaction with a new unique_transfer_token
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

Revert transaction

Endpoint: /transactions/revert

HTTP Method: POST

Description: This service allows to revert a transaction

Example request:

curl -X POST 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/transactions/revert' \
  --header 'Authorization: Token <<access_token>>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "idempotency_token": "some-random-and-unique-token124"
  }'

Example response:

{
    "token": "cooptx-5a35c5dfdcbf4ae79f4759bd8d809460",
    "status": "reverted",
    "idempotency_token": "some-random-and-unique-token124",
    "origin_account": "coopacc-45114ed15621463f9b3063433f123bbf",
    "destination_account": "coopacc-c3b938a4762c440bb9c1a08ff694f976",
    "amount": "100.00",
    "description": "Prueba exitosa",
    "created_at": "2022-06-20T20:28:17.777472-05:00",
    "result_message": "Proceso Exitoso",
    "error_code": null,
    "channel": "wallet"
}

Request parameters

Field Description Type Required
idempotency_token The token received in unique_transfer_token from the client when the transaction was created String yes

Response parameters

Field Description Type Nullable
token A unique identifier for the transaction at Tpaga's systems String no
status Status of the transaction. See Transaction statuses for reversions for details String no
idempotency_token The token received in unique_transfer_token from the client. Use this token to retry transactions safely String no
origin_account Origin account token identifier String no
destination_account Destination account token identifier String no
amount Amount of the transaction String no
description Description provided by the API client to create the transaction String no
created_at Date when the transaction was created in our system. Date is returned in ISO format Date no
result_message A message describing transaction result String yes
channel Identifier for external systems String no
error_code Internal code to identify the error String yes
error_message Detailed message related to returned error String yes
field Name of the field that presents errors in the give request body String yes
value Value received in the field that presents errors String yes

Transaction statuses for reversions

HTTP responses

Code Description
200 The transaction was reverted successfully
401 Invalid authorization token provided
403 You do not have enough permissions to perform this action, please contact the support team
409 Transaction can't be reverted via API, please contact Tpaga's 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: /transactions

HTTP Method: GET

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

Example request:

curl -X GET 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/transactions?account_token=coopacc-45114ed15621463f9b3063433f123bbf' \
  --header 'Authorization: Token <<access_token>>'

Example response:

{
    "transactions": [
        {
            "status": "approved",
            "direction": "deposit",
            "idempotency_token": "891000822C20616000000",
            "channel": "external",
            "coopcentral_id": "891000822C20616000000",
            "amount": "200000.00",
            "description": "NC TRANSACCION ELECT",
            "created_at": "2022-06-16T11:47:13-05:00",
            "origin_bank": {
              "name": "SCOTIABANK COLPATRIA",
              "slug": "scotiabank-colpatria"
            },
            "sender_data": {
              "customer_name": "Alonso Herrera",
              "customer_id_number": "1089876456"
            }
        },
        {
            "token": "cooptx-e3e93af6eaf841fe93a54d40aa6b2f2c",
            "status": "approved",
            "direction": "deposit",
            "idempotency_token": "pp-e942c6e0306472ade2316dc8e3e2b30e8ce55842427032d9d9ffd1fc6cce38aa",
            "channel": "wallet",
            "coopcentral_id": "593922061611477391558683497084",
            "amount": "200000.00",
            "description": "Recarga de Depósito Tpaga por un valor de $200.000.",
            "created_at": "2022-06-16T11:47:13.354520-05:00",
            "origin_bank": {
              "name": "SCOTIABANK COLPATRIA",
              "slug": "scotiabank-colpatria"
            }
        },
        {
            "token": "cooptx-5a35c5dfdcbf4ae79f4759bd8d809460",
            "status": "reverted",
            "direction": "withdrawal",
            "idempotency_token": "some-random-and-unique-token124",
            "channel": "wallet",
            "coopcentral_id": "593922062020287248083114256809",
            "amount": "100.00",
            "description": "Prueba exitosa",
            "created_at": "2022-06-20T20:28:17.777472-05:00",
            "origin_bank": {
              "name": "SCOTIABANK COLPATRIA",
              "slug": "scotiabank-colpatria"
            }
        }
    ]
}

Request parameters

Field Description Type Required
account_token Account token Integer yes
initial_date Initial date to filter Date yes
final_date Final date to filter Date yes

Response parameters

Field Description Type Nullable
transactions List of transactions associated with the given account List no
transactions -> token A unique identifier for the transaction at Tpaga's systems String no
transactions -> status Status of the transaction. See Transaction statuses for details String no
transactions -> direction Can be deposit or withdrawal depending on the movement type String no
transactions -> idempotency_token The token received in unique_transfer_token from the client when the transaction was created String no
transactions -> channel Identifier for external systems String no
transactions -> coopcentral_id Identifier of the transaction in the bank 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 -> created_at Date when the transaction was created in our system. Date is returned in ISO format Date no
transactions -> origin_bank Object with the bank origin information, should be empty if the bank doesn't exist yet Json yes
transactions -> origin_bank -> name Transaction bank name String yes
transactions -> origin_bank -> slug Transaction bank slug String yes
transactions -> sender_data -> customer_name Originator's Name for the Transaction String yes
transactions -> sender_data -> customer_id_number Originator's Document Number for the Transaction String yes
error_code Internal code to identify the error String yes
error_message Detailed message related to returned error String yes
field Name of the field that presents errors in the give request body String yes
value Value received in the field that presents errors String yes

HTTP responses

Code Description
200 Transactions history was queried successfully
401 Invalid authorization token provided
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
shell