Introduction

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

• Get available banks
• Create transactions
• Get transaction information
• Get transactions history

We also can configure a webhook to notify the API clients when a transaction status has changed. See the Webhook section for details.

Environments

We have two independent environments for development and production applications.

• Staging: https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/interbanks/
• Production: https://production.banking-gateway.tpaga.co/api/coopcentral/v1/interbanks/

Quick Start Guide

Once you have an active access_token you can start to use our API to make interbank transactions.

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

1. Authentication

2. Get available banks

3. Create transaction

4. Get transaction information

5. Get transactions history

6. Webhook

Authentication

An example of a valid request sending the authorization token:

curl -X GET 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/interbanks/banks' \
  --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.

Get available banks

Endpoint: /banks

HTTP Method: GET

Description: This service allows to consult the list of available banks that can be used to create transactions.

Example request:

curl -X GET 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/interbanks/banks' \
  --header 'Authorization: Token <<access_token>>'

Example response:

{
  "banks": [
    {
        "name": "BBVA",
        "slug": "bbva"
    },
    {
        "name": "BANCO CAJA SOCIAL",
        "slug": "banco-caja-social"
    }
  ]
}

Request parameters

This endpoint does not need extra parameters to be sent in the request.

Response parameters

HTTP responses

Create transaction

Endpoint: /transactions/create

HTTP Method: POST

Description: This service allows to create an interbank transaction

Example request:

curl -X POST 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/interbanks/transactions/create' \
  --header 'Authorization: <<access_token>>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "dest_account_owner_full_name": "Jovita Ducuara Prieto",
      "dest_account_owner_identification_type": "CC",
      "dest_account_owner_identification_number": "11111158",
      "dest_account_type": "saving_account",
      "dest_account_number": "68653284571",
      "amount": 5211470,
      "dest_bank": "bbva",
      "origin_account": "<origin-account-token>",
      "idempotency_token": "some-random-and-unique-token8765",
      "description": "Some descriptive text"
  }'

Example response:

{
  "dest_account_owner_full_name": "Jovita Ducuara Prieto",
  "dest_account_owner_identification_type": "CC",
  "dest_account_owner_identification_number": "11111158",
  "dest_account_type": "saving_account",
  "dest_account_number": "68653284571",
  "amount": 5211470,
  "status": "pending",
  "fee_amount": 0,
  "dest_bank": "bbva",
  "origin_account_number": "891000845",
  "origin_account_type": "electronic_deposit",
  "origin_account_owner_identification_number": "589632154",
  "idempotency_token": "some-random-and-unique-token8765",
  "result_message": null,
  "description": "Transaction description",
  "created_at": "2024-03-13T18:37:52.000000Z"
}

Request parameters

Response parameters

Transaction statuses

• pending: The transaction was created within the Tpaga system and will be processed soon.
• in_progress: The transaction is being processed by the bank.
• approved: The transaction was successful.
• rejected: The transaction was rejected by the bank. Check the result_message field for details.
• unknown: There was an error, please retry the request with the same idempotency_token to get an updated status.
• created: There was an error, please contact Tpaga's support team.

HTTP responses

Get transaction information

Endpoint: /transactions/idempotency_token

HTTP Method: GET

Description: This service allows to consult the information of a transaction given its idempotency token.

Example request:

curl -X GET 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/interbanks/transactions/some-random-and-unique-token8765' \
  --header 'Authorization: <<access_token>>'

Example response:

{
  "dest_account_owner_full_name": "Jovita Ducuara Prieto",
  "dest_account_owner_identification_type": "CC",
  "dest_account_owner_identification_number": "11111158",
  "dest_account_type": "saving_account",
  "dest_account_number": "68653284571",
  "amount": 5211470,
  "status": "pending",
  "fee_amount": 0,
  "dest_bank": "bbva",
  "origin_account_number": "891000845",
  "origin_account_type": "electronic_deposit",
  "origin_account_owner_identification_number": "34568987",
  "idempotency_token": "some-random-and-unique-token8765",
  "result_message": null,
  "description": "transaction-description",
  "created_at": "2024-03-13T18:37:52.000000Z"
}

Request parameters

Response parameters

Transaction statuses

• pending: The transaction was created within the Tpaga system and will be processed soon.
• in_progress: The transaction is being processed by the bank.
• approved: The transaction was successful.
• rejected: The transaction was rejected by the bank. Check the result_message field for details.
• unknown: There was an error, please retry the request with the same idempotency_token to get an updated status.
• created: There was an error, please contact Tpaga's support team.

HTTP responses

Get transactions history

Endpoint: /transactions

HTTP Method: GET

Description: This service is intended to know your transactions history. For performance reasons, this endpoint only will return the last 20 transactions sorted by creation date.

Example request:

curl -X GET 'https://staging.banking-gateway.tpaga.co/api/coopcentral/v1/interbanks/transactions' \
  --header 'Authorization: <<access_token>>'

Example response:

{
  "transactions": [
    {
      "dest_account_owner_full_name": "Jovita Ducuara Prieto",
      "dest_account_owner_identification_type": "CC",
      "dest_account_owner_identification_number": "11111158",
      "dest_account_type": "saving_account",
      "dest_account_number": "68653284571",
      "amount": 5211470,
      "status": "pending",
      "fee_amount": 0,
      "dest_bank": "bbva",
      "origin_account_number": "891000845",
      "origin_account_type": "electronic_deposit",
      "origin_account_owner_identification_number": "32568987",
      "idempotency_token": "some-random-and-unique-token8765",
      "result_message": null,
      "description": "transaction-description",
      "created_at": "2024-03-13T18:37:52.000000Z"
    },
    {
      "dest_account_owner_full_name": "Jovita Ducuara Prieto",
      "dest_account_owner_identification_type": "CC",
      "dest_account_owner_identification_number": "11111158",
      "dest_account_type": "saving_account",
      "dest_account_number": "68653284571",
      "amount": 5211470,
      "status": "pending",
      "fee_amount": 0,
      "dest_bank": "bbva",
      "origin_account_number": "891000845",
      "origin_account_type": "electronic_deposit",
      "origin_account_owner_identification_number": "589546687",
      "idempotency_token": "another-random-and-unique-token8765",
      "result_message": null,
      "description": "another-transaction-description",
      "created_at": "2024-03-13T18:37:52.000000Z"
    }
  ]
}

Request parameters

Response parameters

HTTP responses

Webhook

This service allows the client API to receive notifications via HTTP requests when a transaction status has changed.

This is an example of the request that we will send to the configured API client endpoint:

curl -X POST 'https://clienthost.com/some/defined/endpoint' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "transaction_token": "some-random-and-unique-token8765"
  }'

How it works

When a transaction reaches a final status (approved or rejected) an HTTP POST request will be sent to a (previously configured) client endpoint. That request will have the following body:

When a webhook notification is sent, the API client should use the received idempotency_token along with the Get transaction information endpoint to get the complete information related to the transaction.

Help for implementers of this API.

In this section we are going to expose information that will help you to implement this API. For example, if we want to simulate an approved or rejected transaction, we would only need to include a keyword in the description field. Remember that it will only work in the staging environment, not in production In case of sending a description that is not within the list below, the API will work normally as it would in production. That is, the transaction will be sent to the bank and you will receive the webhook notification when the bank finish the transaction processing.

After receiving the webhook, you can check the status of the transaction on the endpoint Get transactions history