Introduction

This document describes the API for make mobile top ups and buy mobile packages. This API offers a REST service for:

Get top up providers
Make a mobile top up
List available providers for buy mobile packages
List available mobile packages
Buy a mobile package
Get a mobile package purchase status

Environments

For publishing of these services Tpaga provides two environments:

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

Authentication

An example of a valid request sending the authorization token:

curl -X GET 'https://staging.apiv2.tpaga.co/api/gateway_top-up/v1/service_providers' \
  --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-t9mn345n83ieqwrsz4xp8ztget, you should send YWstdDltbjM0NW44M2llcXdyc3o0eHA4enRnZXQ= in the Authorization header.

Once you have an active api-key you can start to use our API. Here is the detail of each service offered by the API:

Top up services

Get available balance
Get top up providers
Make a mobile top up
Transaction statuses
Testing

Get available balance

Endpoint: /merchant/balance

HTTP Method: GET

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

Example request:

curl -X GET 'https://staging.apiv2.tpaga.co/api/gateway_topup/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 top up providers

Example Request:

curl -X GET \
 https://staging.apiv2.tpaga.co/api/gateway_topup/v1/service_providers \
 -H 'Authorization: Basic <base64-encoded-api-key>'

Example Response:

{
    "service_providers": [
        {
            "slug": "movistar",
            "name": "Movistar",
            "icon_url": "https://some-icon-url.com"
        },
        {
            "slug": "claro-movil",
            "name": "Claro Móvil",
            "icon_url": "https://some-icon-url.com"
        },
        {
            "slug": "avantel",
            "name": "Avantel",
            "icon_url": "https://some-icon-url.com"
        },
        {
            "slug": "uff-movil",
            "name": "Uff Móvil",
            "icon_url": "https://some-icon-url.com"
        },
        {
            "slug": "etb",
            "name": "ETB",
            "icon_url": "https://some-icon-url.com"
        },
        {
            "slug": "tigo",
            "name": "Tigo",
            "icon_url": "https://some-icon-url.com"
        }
    ]
}

Endpoint: /service_providers

HTTP Method: GET

Description: This service returns the current available providers.

Request parameters

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

Response parameters

Field	Description	Type	Nullable
service_providers	List of available providers	List	No
service_providers -> slug	Unique internal identifier for the provider	String	No
service_providers -> name	Human-readable name for the provider	String	No
service_providers -> icon_url	Suggested icon for the provider	String	Yes

Make a mobile top up

Endpoint: /topup_account

HTTP Method: POST

Description: This service allows top up the given phone number

An example using a curl of the consumption of this endpoint::

curl -X POST \
 https://staging.apiv2.tpaga.co/api/gateway_topup/v1/topup_account \
 -H 'Authorization: Basic <base64-encoded-api-key>' \
 -H 'Content-Type: application/json' \
 -d '{
    "idempotency_token": "my-itempotency-token-8",
    "amount": 1000,
    "service_provider": "etb",
    "destination_number": "3110001111",
    "payment_token": "wallet-11233dafd",
    "payment_origin": "Tpaga wallet"
 }'

Request parameters

Field	Description	Type	Required
destination_number	Mobile phone number without country code	String - 20 length	yes
service_provider	Service provider slug. Use one of the returned by the "Get top up providers" service	String	yes
amount	Top up amount	Integer - 100.000	yes
idempotency_token	A unique identifier for the transaction. Use this token to retry transactions safely	String - 128 length	yes
payment_origin	Name of the system where the transaction was generated. Send your company's name here	String - 255 length	yes
payment_token	Unique identifier for the transaction in your system	String - 64 length	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
destination_number	Mobile phone number received in the request	String	No
service_provider	Service provider slug	String	No
amount	Top up amount	Integer	No
payment_token	payment_token received in the request	String	No
payment_origin	payment_origin received in the request	String	No
status	Status of the transaction. See Transaction statuses below for details	String	No
result_code	Internal status code	String	No

Transaction statuses

Status	Description
authorized	The top up was performed successfully
rejected	The top up failed, it's safe to retry the request with a new idempotency_token
in_progress	There was an error, please contact Tpaga's support
unknown	There was an error, please contact Tpaga's support
created	There was an error, please contact Tpaga's support

Testing

The API offers test phone numbers to assist you in the development and certification process. Send the following phone numbers in your requests to simulate different scenarios:

Phone number	Description	HTTP code
3110001111	The top-up was successful	200
3110002222	There was an internal error or timeout. In this case you should contact Tpaga's support and tell your user the top up is in process	502
3110003333	There was an internal error. In this case you should contact Tpaga's support and tell your user the top up is in process	500
3110004444	Two concurrent requests were received with the same idempotency_token, you will see the top up transaction on "in-progress" status	409
3110005555	The top-up could not be performed as the top-up provider rejected it. It is possible to retry the request	503

Mobile packages services

Get mobile package providers
Get mobile packages
Purchase a mobile package
Get purchase information
Test data

Get mobile package providers

Endpoint: /mobile_package_service_providers_list

HTTP Method: GET

Description: This service returns the current available service providers mobile that can be used to mobile packages for purchase.

Example request:

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

Example response:

{
    "service_providers": [
        {
            "name": "TIGO",
            "provider_code": "3",
            "operator_logo_url": "https://storage.googleapis.com/bucket-faas/suppliers/3.webp",
            "enabled": true
        },
        {
            "name": "CLARO PAQUETES",
            "provider_code": "58",
            "operator_logo_url": "https://storage.googleapis.com/bucket-faas/suppliers/58.webp",
            "enabled": true
        },
        {
            "name": "VIRGIN MOBILE PAQUETES",
            "provider_code": "72",
            "operator_logo_url": "https://storage.googleapis.com/bucket-faas/suppliers/72.webp",
            "enabled": true
        },
        {
            "name": "MOVISTAR PAQUETES",
            "provider_code": "30",
            "operator_logo_url": "https://storage.googleapis.com/bucket-faas/suppliers/30.webp",
            "enabled": true
        }
    ]
}

Request parameters

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

Response parameters

Field	Description	Type	Nullable
service_providers	List of available service providers	List	No
service_providers -> provider_code	Unique identifier for the provider on Tpaga's system	String	No
service_providers -> name	Name of provider	String	No
service_providers -> operator_logo_url	URL of the icon to be displayed on the apps	String	No
service_providers -> enabled	Indicate if the service provider is available	Boolean	No

HTTP responses

Code	Description
200	The service providers 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 mobile packages

Endpoint: /packages

HTTP Method: GET

Description: This endpoint returns the current packages mobile for purchase. This point can bring all the current mobile packages or can get the current mobile packages of a specific service provider

Example request:

curl --location --request GET 'https://staging.apiv2.tpaga.co/api/gateway_topup/v1/packages' \
  --header 'Authorization: Basic <base64-encoded-api-key>' \
  --header 'Content-Type: application/json'

Example request with specific service provider:

curl --location --request GET 'https://staging.apiv2.tpaga.co/api/gateway_topup/v1/packages?provider_identifier=58' \
  --header 'Authorization: Basic <base64-encoded-api-key>' \
  --header 'Content-Type: application/json'

Example response:

{
    "packages": [
        {
            "name": "200 MINUTOS A TODO OPERADOR",
            "description": "200 MNTS O 20DIAS",
            "amount": 9900,
            "validity": "20 DÍAS",
            "package_code": "024",
            "sku": "50015",
            "category_code": "9",
            "category_description": "HABLAR",
            "provider_code": "58"
        },
        {
            "name": "18 MINUTOS A VENEZUELA - $5.000",
            "description": "18MIN_A_VNZLA-30D",
            "amount": 5000,
            "validity": "30 DÍAS",
            "package_code": "353",
            "sku": "50050",
            "category_code": "9",
            "category_description": "HABLAR",
            "provider_code": "58"
        },
        {
            "name": "1.5 GB DE NAVEGACION + MUNUTOS Y MENSAJES ILIMI. + REDES SOCIALES (WHATSAPP FACEBOOK TWITTER) + 7 DIAS POR $7.500",
            "description": "1.5GB_MIN ILIMT+7D",
            "amount": 7500,
            "validity": "7 DIAS",
            "package_code": "767",
            "sku": "50130",
            "category_code": "7",
            "category_description": "TODO INCLUIDO",
            "provider_code": "58"
        },
        {
            "name": "TODO INCLUIDO CON MINUTOS ILIMITADOS CHAT DE WHATSAPP FACEBOOK Y TWITTER  12GB POR 30 DIAS",
            "description": "12GB/ILIMITADO_30D",
            "amount": 41000,
            "validity": "30 DIAS",
            "package_code": "939",
            "sku": "50148",
            "category_code": "7",
            "category_description": "TODO INCLUIDO",
            "provider_code": "58"
        }
    ]
}

Request parameters

With the parameter "provider_identifier" can get the current mobile packages of a specific service provider. With the parameters "page" and "per_page" can make a pagination of the request

Field	Description	Type	Required	Default
provider_identifier	Service provider identifier. Should be taken from `service_providers -> provider_code` of the Get available service providers service	String	No
page	Number of pages	Integer	No	1
per_page	Number of packages per page page	Integer	No	200

Response parameters

Field	Description	Type	Nullable
packages	List of current packages	List	No
packages -> name	Full package description	String	No
packages -> description	Short package description	String	No
packages -> amount	Package value	Integer	No
packages -> validity	The period of validity of the package - E.g, "30 DÍAS"	String	No
packages -> package_code	Unique identifier for the package on Tpaga's system	String	No
packages -> sku	A unique identification number	String	Yes
packages -> category_code	Identifier of the category from the package	String	No
packages -> category_description	Category description of package	String	No
packages -> provider_code	Unique identifier for the provider on Tpaga's system	Integer	No
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 list of packages 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 parameters
5XX	Internal sever error, it's safe to retry the request

Purchase a mobile package

Endpoint: /package_buy

HTTP Method: POST

Description: This service allows the client buy a mobile package.

Example request:

curl --location --request POST 'https://staging.apiv2.tpaga.co/api/gateway_topup/v1/package_buy' \
 --header 'Authorization: Basic <base64-encoded-api-key>' \
 --header 'Content-Type: application/json' \
 --data-raw '{
     "destination_number": "3024700057",
     "provider_code": 58,
     "amount": 7500,
     "idempotency_token": "2022111817513334794X305120",
     "payment_token": "wallet-11233dafd",
     "package_code": 767
 }'

Example response:

{
    "idempotency_token": "2022111817513334794X305121",
    "destination_number": "3024700057",
    "amount": 7500,
    "payment_token": "wallet-11233dafd",
    "package_code": "767",
    "provider_code": "58",
    "route": "PUNTORED",
    "external_gateway_auth_code": "526268936",
    "status": "AUTHORIZED",
    "result_code": 0
}

Request parameters

Field	Description	Type	Required
idempotency_token	A unique identifier for the transaction.	String	Yes
amount	Amount for buy the package	Integer	Yes
provider_code	Service provider identifier. Should be taken from `service_providers -> provider_code` of the Get available service providers service	Integer	Yes
destination_number	Mobile phone number to apply the package	String	Yes
payment_token	Identifier for the payment in the external system.	String	Yes
package_code	Package identifier. Should be taken from `packages -> package_code` of the Get available mobile packages service	Integer	Yes

Response parameters

Field	Description	Type	Nullable
idempotency_token	Idempotency token received in the request to purchase the package	String	No
destination_number	Mobile number received in the request to purchase the package	String	No
amount	Amount received in the request to purchase the package	Integer	No
payment_token	Payment token received in the request to purchase the package	String	No
package_code	Package code received in the request to purchase the package	String	No
provider_code	Service Provider received in the request to purchase the package	String	No
status	Status of the transaction. See Transaction statuses for details	String	No
result_code	Internal code representing transaction status	Integer	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 buy was paid 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

Transaction Statuses

CREATED: Implies that the reload could not be performed due to an internal error in the server. It is not safe to do request retry
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 purchase of package was performed successfully
REJECTED: The purchase of package 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.

Get purchase information

Endpoint: /package_buy/

HTTP Method: GET

Description: This service is useful to get the purchased package transaction.

Example request:

curl --location --request GET 'https://staging.apiv2.tpaga.co/api/gateway_topup/v1/package_buy/2022111817513334794X305122' \
  --header 'Authorization: Basic <base64-encoded-api-key>' \
  --header 'Content-Type: application/json'

Example response:

{
    "idempotency_token": "2022111817513334794X305122",
    "destination_number": "3024700057",
    "amount": 7500,
    "payment_token": "wallet-11233dafd",
    "package_code": "767",
    "provider_code": "58",
    "route": "PUNTORED",
    "external_gateway_auth_code": "526268939",
    "status": "AUTHORIZED",
    "result_code": 0
}

Request parameters

Field	Description	Type	Required
idempotency_token	The `idempotency_token` used to create the transaction in the "Purchase a mobile package" service	String	Yes

Response parameters

Field	Description	Type	Nullable
idempotency_token	Idempotency token received in the request to purchase the package	String	No
destination_number	Mobile number received in the request to purchase the package	String	No
amount	Amount received in the request to purchase the package	Integer	No
payment_token	Payment token received in the request to purchase the package	String	No
package_code	Package code received in the request to purchase the package	String	No
provider_code	Service Provider received in the request to purchase the package	String	No
status	Status of the transaction. See Transaction statuses for details	String	No
result_code	Internal code representing transaction status	Integer	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 purchase of the package 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
503	The purchase of the package rejected by the provider. Check response body for details
502	The purchase of the package is unknown. There was a communication issue with the payments provider
5XX	Internal sever error, it's safe to retry the request

Test data

Because third-party providers sometimes have problems with test environments, the API offers test phone numbers to assist in the development and certification process.

Destination Number	Description	HTTP code
3110001111	The mobile package was purchased successfully	200
3110007777	Two concurrent requests were received for the package purchase, you will see the purchase on "in-progress" status	200
3110006666	There was a communication issue with a provider, please contact Tpaga's support to check if the purchase was performed or not	503
3110000000	The package purchase was rejected by the provider, it's safe to retry the request	502