NAV
shell

Introduction

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

Environments

For publishing of these services Tpaga provides two environments:

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

  1. Get top up providers
  2. Make a mobile top up
  3. Transaction statuses
  4. Testing

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

  1. Get mobile package providers
  2. Get mobile packages
  3. Purchase a mobile package
  4. Get purchase information
  5. 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

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

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
shell