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 available balance
  2. Get top up providers
  3. Make a mobile top up
  4. Transaction statuses
  5. Get top up information
  6. Get history Top Up
  7. 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

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: Basic <base64-encoded-api-key>' \
  --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: Basic <base64-encoded-api-key>' \
  --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

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

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

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: Basic <base64-encoded-api-key>' \
  --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
shell