Introduction
This document describes the Electronic Deposit API. This API offers a REST service for:
- Create accounts
- Check accounts balance and transactional limits
- Transfer money between accounts
- Revert transactions
- Query transactions history for a given account
Environments
We have two independent environments for development and production applications.
- Staging:
https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/
- Production:
https://production.banking-gateway.tpaga.co/api/coopcentral/v1/
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:
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 |
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) |
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
- approved: The transaction was successful.
- rejected: The transaction was rejected by the bank.
- unknown: There was an error, please retry the request with the same unique_transfer_token to get a final status.
- created: There was an error, please contact Tpaga's support team.
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
- REVERTED: The transaction was reverted successfully.
- UNKNOWN_REVERT_STATUS: There was an error, please retry the request with the same idempotency_token to get a final status.
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"
},
{
"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"
},
{
"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"
}
]
}
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 |
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 |