Skip to main content

Top up a pSIM

How to add a new product to an already activated physical SIM via Connect.

1. Placing the Order

In order to add additional plan on a physical SIM, after the initial activation, use the order API. The order request will include the ID of the product that will be activated via the order, check the Product Catalogue guide in order to understand how to access the product catalogue. For physical SIMs (pSIM) the order also needs to reference which iccid will be activated in the order.

Example Request

curl -X POST \
https://services.truphone.com/connect-api/v2/orders \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'X-Correlation-ID: unique-id-from-requester-123' \
-d '{
"operation_type": "TOPUP",
"sim_type": "PSIM",
"country": "GB",
"product": {
"id": "kn8etk9XBX0gG7pFP5KErXvWVNN4jOERTMVMNEkX-Ak=",
"sold_price": 20,
"sold_currency": "EUR",
"activation_date": "2020-01-01T00:00:00Z"
},
"subscriber": {
"sim": {
"iccid": "8944472600000510740"
}
}
}'

Example Response

{
"id": "6d41c4ff-1877-4d13-82b0-7dad02c4b02a",
"status": "ACCEPTED",
"created_date": "2020-01-01T00:00:00Z",
"_metadata": {
"_links": {
"_self": "{BASE_URL}/v2/orders/6d41c4ff-1877-4d13-82b0-7dad02c4b02a"
}
}
}

When placing an order, you can set a customised activation and expiration date. If no activation date has been provided, the subscription will be created and activated automatically. On the other hand, if no expiration date has been provided, the subscription will be calculated based on the duration of the plan. Note that this expiration date cannot be longer than the duration of the selected plan and that making it shorter will not change any other plan settings, such as price or data allowance.

2. Checking the Order status

Order fulfilment is not synchronous, so after placing an order, the order status needs to be periodically checked until completion using a polling mechanism. For this your code can use the order API or just use the metadata links available in the response from order creation. You can find the full list of order status here.

Example Request

curl -X GET \
https://services.truphone.com/connect-api/v2/orders/3a6acf89-1ccf-4611-9424-453930f57ef1 \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'X-Correlation-ID: unique-id-from-requester-123'

Example Response

{
"id": "6d41c4ff-1877-4d13-82b0-7dad02c4b02a",
"status": "COMPLETED",
"created_date": "2021-02-24T09:00:00Z",
"output": {
"iccid": "8944000013283712983321",
"subscription_id": "Q-hzHc6EErZPQcgw2L02_nDdruGtr6lDrM-jmja_xuE="
},
"_metadata": {
"links": {
"_sim": "{BASE_URL}/v2/sims/8944000013283712983321",
"_subscription": "{BASE_URL}/v2/subscriptions/Q-hzHc6EErZPQcgw2L02_nDdruGtr6lDrM-jmja_xuE=",
"_self": "{BASE_URL}/v2/orders/6d41c4ff-1877-4d13-82b0-7dad02c4b02a"
}
}
}