Get started

API Endpoint
https://api.fonia.travel/res/v2.5/
                

The Fonia.travel API enables seamless programmatic access to manage eSIM cards. Retrieve a list of available packages, order new eSIM cards, recharge existing ones, and check the status of your eSIM cards. All operations are supported through a secure and flexible API, ensuring efficient management of your eSIM services.

To use this API, you need an API key. Please contact us at web-development@fonia.app to get your own API key.

GET PACKAGES LIST

# Here is a curl example
curl --location 'https://api.fonia.travel/res/v2.5/get_package_list' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [API_KEY]' \
--data-raw '{
    "test": true
}'
                

To get packages list you need to make a POST call to the following url :
https://api.fonia.travel/res/v2.5/get_package_list

Result example :

{
    "statusCode": 200,
    "statusMsg": "PACKAGES_LIST_GENERATED",
    "status": "success",
    "packages": [
        {
            "name": "Country-Xgb-Xday",
            "country": [
                "Austria"
            ],
            "region": [
                "Europe"
            ],
            "duration": 30,
            "size": "3",
            "package_id": "ft_country_Xd_Xgb",
            "price_net_ap": 10,
            "price_gross_ap": 12.3,
            "price_net_client": 20,
            "price_gross_client": 24.4
        }
    ]
}
                

HEADERS PARAMETERS

Field	Value
Content-Type	application/json
Authorization	Bearer [API_KEY]

QUERY PARAMETERS

Field	Type	Description
test	Boolean	(Optional) Run call in sandbox mode, by default false

RETURN RESULTS

Field	Value	Description
statusCode	Integer	Return call response code
statusMsg	String	Return simple error describe
status	String	Simple status call, success | error
packages	Array	Package list
|__name	String	Package name
|__country	Array	Package countries array
|__region	Array	Package region array
|__duration	Double	Package duration in days
|__size	String	Package size in GB
|__package_id	String	Package ID
|__price_net_ap	Double	Package price for API user in netto PLN
|__price_gross_ap	Double	Package price for API user in gross PLN
|__price_net_client	Double	Package price for client netto PLN
|__price_gross_client	Double	Package price for client gross PLN

ORDER - NEW CARD

# Here is a curl example
curl --location 'https://api.fonia.travel/res/v2.5/order' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [API_KEY]' \
--data-raw '{
    "test": true,
    "provider": "provider_name",
    "package_id": "ft_country_Xd_Xgb",
    "price": 12.34,
    "transaction_id": "XXXXXXXXX",
    "userDetails":{
        "name": "Jan",
        "surname": "Kowalski",
        "country": "Poland",
        "pesel": "123123123",
        "email": "mail@mail.com"
    }
}'
                

To make an order you need to make a POST call to the following url :
https://api.fonia.travel/res/v2.5/order

Result example :
{
    "statusCode": 200,
    "statusMsg": "CARD_CREATED",
    "status": "success",
    "esim_details": {
        "iccid": "1111111111111111111",
        "qrValue": "LPA:1$rty.url.com$XX-XXXXXX-XXXXXXX",
        "matchingId": "XX-XXXXXX-XXXXXXX",
        "smdpAddress": "url.com",
        "iosActivation": "url_activation"
    },
    "package_details": {
        "package_id": "ft_country_Xd_Xgb",
        "initialQuantity": 99999999,
        "remainingQuantity": 99999999,
        "unlimited": false
    },
    "order_id": "ft_XXXXXXXX"
}
                

HEADERS PARAMETERS

Field	Value
Content-Type	application/json
Authorization	Bearer [API_KEY]

QUERY PARAMETERS

Field	Type	Description
test	Boolean	(Optional) Run call in sandbox mode, by default false
provider	String	Provider name
price	String	Price API user
transaction_id	String	Transaction ID API user
package_id	String	Package ID
userDetails	Array	User details array
|__name	String	Client firstname
|__surname	String	Client lastname
|__country	String	Client country residence
|__pesel	String	(Optional) Client PESEL number
|__email	String	Client address e-mail

RETURN RESULTS

Field	Value	Description
statusCode	Integer	Return call response code
statusMsg	String	Return simple error describe
status	String	Simple status call, success | error
esim_details	Array	Esim card details
|__iccid	String	Iccid number esim card
|__qrValue	String	QR value to activate
|__matchingId	String	Matching ID necessary to manual card installation
|__smdpAddress	String	Smdp Address necessary to manual card installation
|__iosActivation	String	iOS link activation
order_id	String	Order ID
package_details	Array	Package details
|__package_id	String	Package ID
|__initialQuantity	Integer	Package initial size
|__remainingQuantity	Integer	Package current size
|__unlimited	Boolean	Is package unlimited size

ORDER - TOPUP CARD

# Here is a curl example
curl --location 'https://api.fonia.travel/res/v2.5/order' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [API_KEY]' \
--data-raw '{
    "test": true,
    "provider": "provider_name",
    "package_id": "ft_country_Xd_Xgb",
    "iccid": "111111111111111111111",
    "price": 12.34,
    "transaction_id": "XXXXXXXXX",
    "userDetails":{
        "name": "Joe",
        "surname": "Doe",
        "country": "Country",
        "pesel": "12345678901",
        "email": "mail@mail.com"
    }
}'
                

To make an order topup card you need to make a POST call to the following url:
https://api.fonia.travel/res/v2.5/order

Result example :
{
    "statusCode": 200,
    "statusMsg": "CARD_TOPUP_COMPLETED",
    "status": "success",
    "esim_details": {
        "iccid": "1111111111111111111",
        "qrValue": "LPA:1$rty.url.com$XX-XXXXXX-XXXXXXX",
        "matchingId": "XX-XXXXXX-XXXXXXX",
        "smdpAddress": "url.com",
        "iosActivation": "url_activation"
    },
    "package_details": {
        "package_id": "ft_country_Xd_Xgb",
        "initialQuantity": 99999999,
        "remainingQuantity": 99999999,
        "unlimited": false
    },
    "order_id": "ft_XXXXXXXX"
}
                

HEADERS PARAMETERS

Field	Value
Content-Type	application/json
Authorization	Bearer [API_KEY]

QUERY PARAMETERS

Field	Type	Description
test	Boolean	(Optional) Run call in sandbox mode, by default false
provider	String	Provider name
package_id	String	Package ID
price	String	Price API user
transaction_id	String	Transaction ID API user
iccid	String	Iccid card number
userDetails	Array	User details array
|__name	String	Client firstname
|__surname	String	Client lastname
|__country	String	Client country residence
|__pesel	String	(Optional) Client PESEL number
|__email	String	Client address e-mail

RETURN RESULTS

Field	Value	Description
statusCode	Integer	Return call response code
statusMsg	String	Return simple error describe
status	String	Simple status call, success | error
esim_details	Array	Esim card details
|__iccid	String	Iccid number esim card
|__qrValue	String	QR value to activate
|__matchingId	String	Matching ID necessary to manual card installation
|__smdpAddress	String	Smdp Address necessary to manual card installation
|__iosActivation	String	iOS link activation
order_id	String	Order ID
package_details	Array	Package details
|__package_id	String	Package ID
|__initialQuantity	Integer	Package initial size
|__remainingQuantity	Integer	Package current size
|__unlimited	Boolean	Is package unlimited size

CARD STATUS

# Here is a curl example
curl --location 'https://api.fonia.travel/res/v2.5/status' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [API_KEY]' \
--data '{
    "test": true,
    "provider": "provider_name",
    "iccid": "111111111111111111"
}'
                

To get esim card status you need to make a POST call to the following url:
https://api.fonia.travel/res/v2.5/status

Result example :
{
    "statusCode": 200,
    "statusMsg": "STATUS_UPDATED",
    "status": "success",
    "iccid": "11111111111111111111",
    "esim_bundles": [
        {
            "package_id": "ft_country_Xd_Xgb",
            "initialQuantity": 99999999,
            "remainingQuantity": 55857978,
            "unlimited": false,
            "startTime": "2024-08-21T07:29:07Z",
            "endTime": "2024-08-24T07:29:07Z",
            "assignmentDateTime": "2024-08-14T06:53:10.769839Z",
            "state": "active",
            "order_id": "ft_XXXXXX"
        },
        {
            "package_id": "ft_country_Xd_Xgb",
            "initialQuantity": 99999999,
            "remainingQuantity": 92363840,
            "unlimited": true,
            "startTime": null,
            "endTime": null,
            "assignmentDateTime": "2023-05-14T06:53:10.769839Z",
            "state": "queued",
            "order_id": "ft_XXXXXX"
        }
    ],
    "esim_status": [
        "status": "RELEASED",
        "firstInstallation": "2025-05-10T13:32:00.000Z",
        "firstConnectionNetwork": "2025-05-22T09:50:47.447Z"
    ]
}
                

HEADERS PARAMETERS

Field	Value
Content-Type	application/json
Authorization	Bearer [API_KEY]

QUERY PARAMETERS

Field	Type	Description
test	Boolean	(Optional) Run call in sandbox mode, by default false
provider	String	Provider name
iccid	String	Iccid card number

RETURN RESULTS

Field	Value	Description
statusCode	Integer	Return call response code
statusMsg	String	Return simple error describe
status	String	Simple status call, success | error
esim_bundles	Array	Esim card bundles list
|__package_id	String	Package ID
|__initialQuantity	Integer	Package initial size
|__remainingQuantity	Integer	Package current size
|__unlimited	Boolean	Is package unlimited size
|__startTime	String | null	Date of activate using package
|__endTime	String | null	Date of end activate using package
|__assignmentDateTime	String	Date of assignment to card
|__state	String	Package state at card
|__order_id	String	Fonia order number
esim_status	Array	Esim card status
|__status	String	Esim card status
|__firstInstallation	String|NULL	Date of first installation
|__firstConnectionNetwork	String|NULL	Date of first connection to the network or null

ESIM STATUS LIST

Name	Description
RELEASED	Esim issued, not yet downloaded
DOWNLOADED	Esim downloaded, not installed yet
INSTALLED	Esim installed and active
UNAVAILABLE	Esim unavailable or removed.

REVOKE PACKAGE

# Here is a curl example
curl --location 'https://api.fonia.travel/res/v2.5/revoke' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [API_KEY]' \
--data '{
    "test": true,
    "package_id": "ft_country_Xd_Xgb",
    "iccid": "111111111111111111"
}'
                

To revoke package from esim card you need to make a POST call to the following url:
https://api.fonia.travel/res/v2.5/revoke

NOTICE! To prevent the eSIM from being returned to the operator, ensure that the eSIM either:
- Is installed
- Has more than one bundle at the time of revocation

Result example :
{
    "statusCode": 200,
    "status": "success",
    "statusMsg": "PACKAGE_REVOKED"
}
                

HEADERS PARAMETERS

Field	Value
Content-Type	application/json
Authorization	Bearer [API_KEY]

QUERY PARAMETERS

Field	Type	Description
test	Boolean	(Optional) Run call in sandbox mode, by default false
package_id	String	Package ID
iccid	String	Iccid card number

RETURN RESULTS

Field	Value	Description
statusCode	Integer	Return call response code
statusMsg	String	Return simple error describe
status	String	Simple status call, success | error

Errors

The Fonia Travel API uses the following error codes:

Error Code	Meaning
200	Everything fine.
400	Wrong input data structure
401	Unknown or unvalid API_KEY. This error appears if you use an unknow API key or if your API key expired.
500	Timeout connections, max time out is 15s.