Introduction
This document describes the API for make mobile top ups and buy mobile packages. This API offers a REST service for:
- Get available balance
- Get top up providers
- Make a mobile top up
- Get top up information
- Get history Top Up
- List available providers for buy mobile packages
- List available mobile packages
- Buy a mobile package
- Get a mobile package purchase status
- Get history purchases
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
cURL Example:
CLIENT_ID="neZi59dZrKaUdblk4LvbB391wuzXlzyc65aaBH8r"
CLIENT_SECRET="Ib5m6r0SqLqolkWM7yQ8aBitVRwypDonVcJ4fYn4gD3qIXIX5b683y3gUio9T8Ukau1QEZYvBnNrjoYWC8V0Z5Oag4XXc7P9ny21LD0D8n40fg3JVHH8mJiJf52sPKwh"
AUTH_STRING=$(echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64 | tr -d '\n')
curl -v --location POST 'https://staging.apiv2.tpaga.co/o/token/' \
--header "Authorization: Basic $AUTH_STRING" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials'
A successful response returns a JSON object in the following format:
{
"access_token": "<JWT token>",
"token_type": "Bearer",
"expires_in": 3600,
"scope":"read write"
}
An example of a valid request sending the Bearer token:
curl -X GET 'https://staging.apiv2.tpaga.co/api/gateway_topup/v1/merchant/balance' \
--header 'Authorization: Bearer <JWT token>'
Example to revoke an access token:
curl -X POST 'https://staging.apiv2.tpaga.co/o/revoke_token/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=<JWT token>' \
--data-urlencode 'client_id=<your-client-id>' \
--data-urlencode 'client_secret=<your-client-secret>'
This API uses OAuth 2.0 with JWT-based access tokens. Clients must first obtain an access token using the client credentials flow and then include it in subsequent API requests via the Authorization header.
Obtaining an Access Token
Endpoint: /o/token/
HTTP Method: POST
Description: To obtain an access token, send a POST request to the /o/token/ endpoint using HTTP Basic Authentication with your client credentials. Your CLIENT_ID and CLIENT_SECRET must be combined, base64-encoded, and included in the Authorization header.
Request Parameters
| Field | Description | Type | Nullable |
|---|---|---|---|
| grant_type | The OAuth2 grant type. Must be set to client_credentials. |
String | No |
Note: Client credentials are provided via the HTTP Basic Authentication header.
Response Parameters
| Field | Description | Type | Nullable |
|---|---|---|---|
| access_token | The generated JWT token | String | No |
| token_type | The type of token, e.g. "Bearer" | String | No |
| expires_in | The duration (in seconds) for which the token is valid | Integer | No |
HTTP Responses
| Code | Description |
|---|---|
| 200 | The access token was issued successfully. |
| 400 | The request is missing required parameters or includes invalid values. |
| 401 | Client authentication failed. |
Using the Access Token
Include the obtained JWT access token in the Authorization header for subsequent API requests
Token Expiration and Renewal
Access tokens are valid for a limited period (as specified by the expires_in value). We recommend caching your access token and reusing it until it is near expiration. Avoid requesting a new token on every API call. When the token is close to expiring, request a new one to maintain uninterrupted service.
Revoking an Access Token
Endpoint: /o/revoke_token/
HTTP Method: POST
Description: If you need to revoke an access token, send a POST request to the /o/revoke_token/ endpoint.
Request Parameters
| Field | Description | Type | Nullable |
|---|---|---|---|
| token | The access token to be revoked. | String | No |
| client_id | The client ID. | String | No |
| client_secret | The client secret. | String | No |
Response Parameters
The response body is empty if the token revocation is successful.
HTTP Responses
| Code | Description |
|---|---|
| 200 | The access token was revoked successfully. The response body will be empty. |
| 400 | The request is missing required parameters or is malformed. |
| 401 | Client authentication failed. |
| 404 | The provided token was not found. |
Environment Considerations
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
- Get top up information
- Get history Top Up
- 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: Bearer <JWT token>'
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: Bearer <JWT token>'
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: Bearer <JWT token>' \
-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 |
HTTP responses
You have no funds. Please top up your account and contact our support team to keep operating. Thank you.
| Code | Description |
|---|---|
| 200 | The buy 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. Thank you |
| 403 | You do not have enough permissions to perform this action, please contact the support team |
| 409 | Eally simultaneous top up request, skipping this one or top up request already answered |
| 422 | Invalid parameters sent to request top up |
| 500 | Internal sever error, it's safe to retry the request |
| 502 | Failure when performing mobile top up - top up in unknown status |
| 503 | The buy was rejected |
Error Details
When the response code is 422, the response body includes details about the invalid data provided. The response will follow this structure:
{
"error_message": "A descriptive message about the error.",
"field": "The specific field where the error occurred, or 'non_field_errors' for general validation issues.",
"value": "The invalid value that caused the error. Sometimes this field is not delivered"
}
Example Errors
| Field | Description | Example Value | Example Error Message |
|---|---|---|---|
| idempotency_token | A top up request is being sent with an idempotency that already exists | wb-n001dbfqc60t | Ya existe un/a topup transaction con este/a idempotency token. |
| service_provider | The mobile operator may be disabled or not really exist | invalid-operator | Objeto con slug=invalid-operator no existe. |
| destination_number | They send the field empty or blank | |
Este campo no puede estar en blanco |
| mobile_number | The number does not have 12 or 10 characters long. | 09516588 | Este valor no coincide con el patrón requerido. |
| payment_token | They send the field empty or blank. | |
Este campo no puede estar en blanco. |
| payment_origin | They send the field empty or blank. | |
Este campo no puede estar en blanco. |
| amount | The transaction amount is below the allowed minimum. | 600 | El monto de la recarga no puede ser menor a 1000.00. |
| amount | The transaction amount exceeds the allowed maximum. | 110000 | El monto de la recarga no puede ser mayor a 100000.00. |
| amount | The transaction amount is not divisible by 100. | 6548 | Ensure the given value (6548) is divisible by 100. |
Get top up information
Endpoint: /topup_account/
HTTP Method: GET
Description: This service is useful to get the top up transaction.
Example request:
curl --location --request GET 'https://staging.apiv2.tpaga.co/api/gateway_topup/v1/topup_account/pp-50cb4f8cfaab8b4' \
--header 'Authorization: Bearer <JWT token>' \
--header 'Content-Type: application/json'
Example response:
{
"token": "topup-ljc4yupgxcnr1d1pt342gwlpwh",
"idempotency_token": "idtk-29",
"destination_number": "30047729",
"service_provider": "slug31",
"amount": 1000,
"payment_token": "6075885727824813",
"payment_origin": "tpaga-wallet-tappsi",
"route": "MOVILRED",
"external_gateway_auth_code": None,
"gateway_topup_token": None,
"status": "CREATED",
"result_code": None,
"date_created": "2024-12-05 09:20:29"
}
Request parameters
| Field | Description | Type | Required |
|---|---|---|---|
| idempotency_token | The idempotency_token used to create the transaction in the "Make a mobile top up" service |
String | Yes |
Response parameters
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 code representing transaction status | Integer | Yes |
| external_gateway_auth_code | Authorization code for the package, if succesful issued by the external gateway operator. | String | Yes |
| gateway_topup_token | Identifier for the topup transaction in Tpaga\'s with gateway operator | String | Yes |
| route | The payment network used to pay for the mobile package. | String | 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 transaction top up 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 | The top up queried by the idempotency_token does not exist. |
| 5XX | Internal sever error, it's safe to retry the request |
Get history Top Up
Endpoint: /topup_account/transactions
HTTP Method: GET
Description: This endpoint returns the history of top up made by a client of the API. It supports paginated queries and date range filtering.
Example request:
curl --location --request GET 'https://staging.apiv2.tpaga.co/api/gateway_topup/v1/topup_account/transactions' \
--header 'Authorization: Bearer <JWT token>' \
--header 'Content-Type: application/json'
Example response:
{
"count": 3,
"transactions": [
{
"idempotency_token": "idtk-28",
"destination_number": "30047728",
"service_provider": "slug30",
"amount": 1000,
"payment_origin": "tpaga-wallet-tappsi",
"status": "CREATED",
"date_created": "2024-12-05 09:20:29"
},
{
"idempotency_token": "idtk-29",
"destination_number": "30047729",
"service_provider": "slug31",
"amount": 1000,
"payment_origin": "tpaga-wallet-tappsi",
"status": "CREATED",
"date_created": "2024-12-05 09:20:29"
},
{
"idempotency_token": "idtk-30",
"destination_number": "30047730",
"service_provider": "slug32",
"amount": 1000,
"payment_origin": "tpaga-wallet-tappsi",
"status": "CREATED",
"date_created": "2024-12-05 09:20:29"
}
]
}
Request parameters
With the parameters "page" and "per_page" can make a pagination of the request With the parameters start_date and end_date, you can set a search range based on the creation date. If one of the fields is provided, the other will be required, and start_date cannot be greater than end_date.
| Field | Description | Type | Required | Default |
|---|---|---|---|---|
| page | Number of page | Integer | No | 1 |
| per_page | Number of transactions per page | Integer | No | 200 |
| start_date | Start date of the search in YYYY-MM-DD format. | String | No | |
| end_date | End date of the search in YYYY-MM-DD format. | String | No |
Response parameters
| Field | Description | Type | Nullable |
|---|---|---|---|
| count | Total transactions made by the API Client or within the selected range. | Integer | No |
| transactions | List of current transactions | List | No |
| transactions -> idempotency_token | Idempotency token received in the request | String | No |
| transactions -> destination_number | Mobile phone number received in the request | String | No |
| transactions -> service_provider | Service provider slug | String | No |
| transactions -> amount | Top up amount | Integer | No |
| transactions -> payment_origin | payment_origin received in the request | String | No |
| transactions -> status | Status of the transaction. See Transaction statuses below for details | String | No |
| transactions -> created_at | Date when created transaction in format AAAA-MM-DD HH-MM-SS | String | 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 transactions 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 | Invalid parameters sent |
| 5XX | Internal sever error, it's safe to retry the request |
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
- Get history purchases
- 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: Bearer <JWT token>'
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: Bearer <JWT token>' \
--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: Bearer <JWT token>' \
--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: Bearer <JWT token>' \
--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 |
| 402 | You have no funds. Please top up your account and contact our support team to keep operating. Thank you. |
| 403 | You do not have enough permissions to perform this action, please contact the support team |
| 409 | Eally simultaneous top up request, skipping this one or top up request already answered |
| 422 | Invalid parameters sent to request top up |
| 500 | Internal sever error, it's safe to retry the request |
| 502 | Failure when performing mobile top up - top up in unknown status |
| 503 | The buy was rejected |
Error Details
When the response code is 422, the response body includes details about the invalid data provided. The response will follow this structure:
{
"error_message": "A descriptive message about the error.",
"field": "The specific field where the error occurred, or 'non_field_errors' for general validation issues.",
"value": "The invalid value that caused the error. Sometimes this field is not delivered"
}
Example Errors
| Field | Description | Example Value | Example Error Message |
|---|---|---|---|
| idempotency_token | A package request is being sent with an idempotency that already exists | wb-n001dbfqc60t | Ya existe un/a mobile package transaction con este/a idempotency token. |
| provider_code | The mobile operator does not match the package being sent | 58 | El service_provider se debe corresponder con el mobile_package. |
| provider_code | The mobile operator may be disabled | 58 | El operador móvil del paquete no está habilitado. |
| provider_code | The mobile operator not really exist | 58 | Objeto con provider_code=58 no existe |
| package_code | The package is disabled | 767 | El paquete móvil no está habilitado. |
| package_code | The package not exist | 767 | Objeto con package_code=767 no existe |
| destination_number | They send the field empty or blank | |
Este campo no puede estar en blanco |
| mobile_number | The number does not have 10 characters long. | 301486565 | Este valor no coincide con el patrón requerido. |
| payment_token | They send the field empty or blank. | |
Este campo no puede estar en blanco. |
| payment_origin | They send the field empty or blank. | |
Este campo no puede estar en blanco. |
| amount | The transaction amount is below the allowed minimum. | 600 | El monto del paquete no puede ser menor a 1000.00. |
| amount | The transaction amount exceeds the allowed maximum. | 110000 | El monto del paquete no puede ser mayor a 100000.00. |
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 retryIN_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 statusAUTHORIZED: The purchase of package was performed successfullyREJECTED: The purchase of package failed. Check response body for detailsUNKNOWN: 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: Bearer <JWT token>' \
--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 |
Get history purchases
Endpoint: /package_buy/transactions
HTTP Method: GET
Description: This endpoint returns the purchase history of packages made by a client of the API. It supports paginated queries and date range filtering.
Example request:
curl --location --request GET 'https://staging.apiv2.tpaga.co/api/gateway_topup/v1/package_buy/transactions' \
--header 'Authorization: Bearer <JWT token>' \
--header 'Content-Type: application/json'
Example response:
{
"count": 3,
"transactions": [
{
"idempotency_token": "idtk-28",
"destination_number": "30047728",
"amount": 1000,
"package_code": "68V",
"provider_code": "DC4",
"status": "IN_PROGRESS",
"created_at": "2024-12-05 11:20:02"
},
{
"idempotency_token": "idtk-28",
"destination_number": "30047728",
"amount": 1000,
"package_code": "68V",
"provider_code": "DC4",
"status": "REJECTED",
"created_at": "2024-12-05 11:20:02"
},
{
"idempotency_token": "idtk-29",
"destination_number": "30047729",
"amount": 1000,
"package_code": "EFF",
"provider_code": "JPX",
"status": "CREATED",
"created_at": "2024-12-05 11:20:02"
},
{
"idempotency_token": "idtk-30",
"destination_number": "30047730",
"amount": 1000,
"package_code": "HES",
"provider_code": "2MW",
"status": "AUTHORIZED",
"created_at": "2024-12-05 11:20:02"
}
]
}
Request parameters
With the parameters "page" and "per_page" can make a pagination of the request With the parameters start_date and end_date, you can set a search range based on the creation date. If one of the fields is provided, the other will be required, and start_date cannot be greater than end_date.
| Field | Description | Type | Required | Default |
|---|---|---|---|---|
| page | Number of page | Integer | No | 1 |
| per_page | Number of transactions per page | Integer | No | 200 |
| start_date | Start date of the search in YYYY-MM-DD format. | String | No | |
| end_date | End date of the search in YYYY-MM-DD format. | String | No |
Response parameters
| Field | Description | Type | Nullable |
|---|---|---|---|
| count | Total transactions made by the API Client or within the selected range. | Integer | No |
| transactions | List of current transactions | List | No |
| transactions -> idempotency_token | Idempotency token received in the request to purchase the package | String | No |
| transactions -> destination_number | Mobile number received in the request to purchase the package | String | No |
| transactions -> amount | Amount received in the request to purchase the package | Integer | No |
| transactions -> package_code | Package code received in the request to purchase the package | String | No |
| transactions -> provider_code | Service Provider received in the request to purchase the package | String | No |
| transactions -> status | Status of the transaction. See Transaction statuses for details | String | No |
| transactions -> created_at | Date when created transaction in format AAAA-MM-DD HH-MM-SS | String | 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 transactions 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 | Invalid parameters sent |
| 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 |