Introduction

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

Get your available balance to pay bills
Get the list of available agreements
Query a bill reference to be paid
Pay a bill
Get a bill payment status

Environments

We have two independent environments for development and production applications.

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

Quick Start Guide

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

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

Authentication
Get available balance
Get available agreements
Query a bill to pay
Pay bill
Get bill payment status

Authentication

An example of a valid request sending the authorization token:

curl -X GET 'https://staging.apiv2.tpaga.co/api/gateway_bill_payment/v1/merchant/balance' \
  --header 'Authorization: Basic <base64-encoded-api-key>'

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

The Api-Key granted by Tpaga should be encoded on base64 and sent in the Authorization header. For example, if the Api-Key is ak-t9mn345n83ieqwrsz4xp8ztgetznr, you should send YWstdDltbjM0NW44M2llcXdyc3o0eHA4enRnZXR6bnI= in the Authorization header.

Get available balance

Endpoint: /merchant/balance

HTTP Method: GET

Description: This service allows to query the available balance and the max loan to continue paying bills.

Example request:

curl -X GET 'https://staging.apiv2.tpaga.co/api/gateway_bill_payment/v1/merchant/balance' \
  --header 'Authorization: Basic YWstdDltbjM0NW44M2llcXdyc3o0eHA4enRnZXR6bnI='

Example response:

{
  "balance": 0,
  "max_loan_amount": 0
}

Request parameters

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

Response parameters

Field	Description	Type	Nullable
balance	The current balance that the merchant can use to pay bills	Integer	no
max_loan_amount	The max overdraft amount.	Integer	no
error_message	Detailed message related to returned error	String	yes

HTTP responses

Code	Description
200	The merchant balance 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
5XX	Internal sever error, it's safe to retry the request

Get available agreements

Endpoint: /utility_providers

HTTP Method: GET

Description: This service returns the current available agreements that can be used to query and pay bills. Includes pagination in case the number of agreements is greater than 500.

Example request:

curl -X GET 'https://staging.apiv2.tpaga.co/api/gateway_bill_payment/v1/utility_providers' \
  --header 'Authorization: Basic YWstdDltbjM0NW44M2llcXdyc3o0eHA4enRnZXR6bnI='

Example response:

{
  "service_providers": [
    {
      "id": "avantel",
      "name": "Avantel",
      "style": {
        "title": "Avantel",
        "icon_url": "https://s3.amazonaws.com/tpaga-wallet-resources/android/promotions/bill_payment_promotion/avantel_icono.png",
        "description": ""
      }
    },
    {
      "id": "claro_movil",
      "name": "Claro",
      "style": {
        "title": "Claro",
        "icon_url": "https://s3.amazonaws.com/tpaga-wallet-resources/android/promotions/bill_payment_promotion/claro_icono.png",
        "description": ""
      }
    },
    {
      "id": "dummy_provider",
      "name": "Dummy provider",
      "style": {
        "title": "Dummy provider",
        "icon_url": "https://s3.amazonaws.com/tpaga-wallet-resources/android/promotions/bill_payment_promotion/gas_natural_icono.png",
        "description": ""
      }
    }
  ],
  "categories": [
    {
      "id": "mobile",
      "style": {
        "title": "Celular",
        "icon_url": "https://tpaga-wallet-resources.s3.amazonaws.com/android/promotions/inscribed_bills/mobile.png",
        "description": "Recarga en línea: minutos y datos"
      },
      "service_providers": [
        "avantel",
        "claro_movil"
      ]
    },
    {
      "id": "phone",
      "style": {
        "title": "Teléfono",
        "icon_url": "https://tpaga-wallet-resources.s3.amazonaws.com/android/promotions/inscribed_bills/phone.png",
        "description": "Paga tu teléfono fijo"
      },
      "service_providers": [
        "dummy_provider"
      ]
    }
  ]
}

Request parameters

If the request parameters aren't sent, it returns the first 500 available agreements.

Field	Description	Type	Required
page	Page number that it's gonna be shown. Starts at 1. Default to 1	Integer	No
per_page	Number of items per page. Maximun number is 500. Default to 500	Integer	No

Response parameters

Field	Description	Type	Nullable
service_providers	List of available agreements	List	No
service_providers -> id	Unique identifier for the agreement on Tpaga's system	String	No
service_providers -> name	Human readable name for the agreement	String	No
service_providers -> style	Suggested icon, title and description for the agreement	Json	No
categories	Grouping of agreements suggested by Tpaga	List	No
categories -> id	Unique identifier for the agreement on Tpaga's system	String	No
categories -> style	Suggested icon, title and description for the category	Json	No
categories -> service_providers	Unique identifiers of the agreements of the category (list of `service_providers -> id`)	List	No

HTTP responses

Code	Description
200	The available agreements 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
5XX	Internal sever error, it's safe to retry the request

Query a bill to pay

Endpoint: /utility_providers//bills/

HTTP Method: GET

Description: This service returns the value for which the bill can be paid.

Example request:

curl -X GET 'https://staging.apiv2.tpaga.co/api/gateway_bill_payment/v1/utility_providers/etb/bills/111100005555/' \
  --header 'Authorization: Basic YWstdDltbjM0NW44M2llcXdyc3o0eHA4enRnZXR6bnI='

Example response:

{
  "utility_provider": "etb",
  "short_bill_reference": "111100005555",
  "amount": "12300.00",
  "payable_until": "2022-08-09"
}

Example error response:

{
  "error_message": "Bill has expired",
  "billcheck_error_code": "expired_bill"
}

Request parameters

Field	Description	Type	Required
service_provider_id	Agreement identifier. Should be taken from `service_providers -> id` of the "available agreements" service	String	Yes
bill_reference	Number printed on the bill used to identify it. `max 20 characters of length`	String	Yes

Response parameters

Field	Description	Type	Nullable
utility_provider	Service provider ID received in the request	String	No
short_bill_reference	Bill reference received in the request	String	No
amount	Amount for which the bill is available to be paid	String	No
payable_until	`DEPRECATED - This field will be removed and should not be used`	None	Yes
error_message	Detailed message related to returned error	String	Yes
billcheck_error_code	Internal code to identify an error, check Detailed error codes section	String	Yes
field	Name of the field that presents errors in the given request body	String	Yes

HTTP responses

Code	Description
200	The bill was queried successfully
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
412	There is no bill payment providers enabled for this bill, 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

Detailed error codes

bill_does_not_exist: There is no bill that matches the given service_provider_id and bill_reference
expired_bill: Bill has expired and can not be paid
already_paid_bill: This bill_reference has already been paid
dummy422-try-again: The bill payment provider is not available. Please try again later.
bill_cannot_be_paid: Tpaga is having issues with the bill payment service

Test data to query bills

Here are some values that you can send in the bill_reference field to generate many API responses.

For the service_provider_id field you can use any of the returned by the "available agreements" service

bill_reference	Description	HTTP response code
111100005555	Bill is available to be paid	200
000000	Bill is available to be paid and the amount is not fixed	200
dummy412	There is no bill payment providers enabled for this bill	412
dummy422-does-not-exist	Generates the `bill_does_not_exist` error code	422
dummy422-expired-bill	Generates the `expired_bill` error code	422
dummy422-already-paid-bill	Generates the `already_paid_bill` error code	422
dummy422-try-again	Generates the `dummy422- error code	422
dummy422-cannot-be-paid	Generates the `bill_cannot_be_paid` error code	422

Pay bill

Endpoint: /pay_bill

HTTP Method: POST

Description: This service allows the client to pay previously queried bills.

Example request:

curl -X POST 'https://staging.apiv2.tpaga.co/api/gateway_bill_payment/v1/pay_bill' \
  --header 'Authorization: Basic YWstdDltbjM0NW44M2llcXdyc3o0eHA4enRnZXR6bnI=' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "idempotency_token": "some-random-and-unique-token-12f12",
      "amount": 12300,
      "utility_provider": "etb",
      "short_bill_reference": "111100005555",
      "payment_token": "external_unique_token_12dd3",
      "payment_origin": "Test API client 1"
  }'

Example response:

{
  "token": "bpm-h1q2kyqdoshji95bm14fxfie3f7j",
  "idempotency_token": "some-random-and-unique-token-12f12",
  "short_bill_reference": "111100005555",
  "utility_provider": "etb",
  "amount": 12300,
  "payment_token": "external_unique_token_12dd3",
  "payment_origin": "Test API client 1",
  "route": "MOVILRED",
  "external_gateway_auth_code": null,
  "gateway_bill_payment_token": null,
  "status": "AUTHORIZED",
  "result_code": null,
  "bank_transaction_id": "dummy_bank_tx_id",
  "payment_provider_data": {}
}

Request parameters

Field	Description	Type	Required
idempotency_token	A unique identifier for the transaction. Use this token to retry transactions safely	String	Yes
amount	Amount for which the bill will be paid. This value must be the same received when querying the bill	Integer	Yes
utility_provider	Agreement identifier. Should be taken from `service_providers -> id` of the "available agreements" service	String	Yes
short_bill_reference	Number printed on the bill used to identify it. `max 20 characters of length`	String	Yes
payment_token	Identifier for the payment in the external system.	String	Yes
payment_origin	Identifier for the external system where the payment for this bill was performed	String	Yes

Response parameters

Field	Description	Type	Nullable
token	Internal identifier for the transaction	String	No
idempotency_token	Idempotency token received in the request	String	No
short_bill_reference	Bill reference received in the request	String	No
utility_provider	Utility_provider received in the request	String	No
amount	Amount received in the request	Integer	No
payment_token	Payment token received in the request	String	No
payment_origin	Payment origin received in the request	String	No
route	Payment provider used to pay the bill	String	No
external_gateway_auth_code	Authorization code for the bill payment issued by the payment provider	String	Yes
gateway_bill_payment_token	Internal transaction identifier	String	Yes
status	Status of the transaction. See Transaction statuses for details	String	No
result_code	Internal code representing transaction status	String	Yes
bank_transaction_id	Transaction identifier in the Bank's system	String	Yes
payment_provider_data	Additional information for the transaction related to the provider used	Json	Yes
error_message	Detailed message related to returned error	String	Yes
field	Name of the field that presents errors in the given request body	String	Yes

HTTP responses

Code	Description
200	The bill was paid successfully
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
409	There is another bill payment transaction with the same `idempotency_token`, their status will be returned
422	You did not provide valid data for this operation, please check response body for details
503	Bill payment rejected by the provider. Check response body for details
5XX	Internal sever error, it's safe to retry the request using de same `idempotency_token`

Transaction Statuses

IN_PROGRESS: This status is returned when two concurrent requests are received. The second request will receive this status while the first request ends with a final transaction status
AUTHORIZED: The bill payment was performed successfully
REJECTED: The bill payment failed. Check response body for details
UNKNOWN: There was a communication issue with the payments provider, please contact the support team to check if the payment was performed or not.

Test data to pay bills

Here are some values that you can send in the bill_reference field to generate many API responses.

For the utility_provider field you can use any of the service_provider_id returned by the "available agreements" service.

bill_reference	Description	Transaction status	HTTP response code
111100005555	The bill payment was performed successfully	AUTHORIZED	200
000000	The bill payment was performed successfully and the amount can be different from the returned by the "Query Bill" service	AUTHORIZED	200
111100001111	The bill payment is being processed in other request, try again later to get a final status	IN_PROGRESS	409
111100003333	The bill payment failed. It's safe to retry the transacion with a new `idempotency_token`	REJECTED	503
111100004444	There was an error processing the transactions. Contact Tpaga and do not retry the transaction to avoid duplicated payments	UNKNOWN	502

Get bill payment status

Endpoint: /bill_payment_transactions/

HTTP Method: GET

Description: This service is useful to get the updated status of a bill payment transaction on IN_PROGRESS or UNKNOWN status.

Example request:

curl -X GET 'https://staging.apiv2.tpaga.co/api/gateway_bill_payment/v1/bill_payment_transactions/some-random-and-unique-token-944' \
  --header 'Authorization: Basic YWstdDltbjM0NW44M2llcXdyc3o0eHA4enRnZXR6bnI='

Example response:

{
  "token": "bpm-0cj5j7d1blbygel2x97ez9hagtzw",
  "idempotency_token": "some-random-and-unique-token-944",
  "short_bill_reference": "111100005555",
  "utility_provider": "etb",
  "amount": 1300,
  "payment_token": "external_unique_token_12dd34",
  "payment_origin": "Test API client 1",
  "route": "MOVILRED",
  "external_gateway_auth_code": null,
  "gateway_bill_payment_token": null,
  "status": "AUTHORIZED",
  "result_code": null,
  "bank_transaction_id": "dummy_bank_tx_id",
  "payment_provider_data": {}
}

Request parameters

Field	Description	Type	Required
idempotency_token	The `idempotency_token` to create the transaction in the "Pay bill" service	String	Yes

Response parameters

The response body is the same to the "Pay Bill" service.

HTTP responses

Code	Description
200	The bill payment 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