Skip to main content
Version: v2.0

Using Codes

How to use voucher codes on Connect.

1. Placing the Order​

Since voucher codes are only created for new eSIM activation orders, the first step to start using voucher codes is to place an order through Connect's order API.

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": "ACTIVATION",
      "sim_type": "ESIM",
      "country": "GB",
      "product": {
        "id": "kn8etk9XBX0gG7pFP5KErXvWVNN4jOERTMVMNEkX-Ak="
      },
      "subscriber": {
        "email": "john@doe.com",
        "first_name": "John",
        "last_name": "Doe",
        "country_of_residence": "US",
        "device": {
          "operating_system": "ios",
          "model": "iPhone",
          "id": "1234567"
        }
      }
}'

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"
    }
  }
}

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. Once the order status is COMPLETED and the voucher service is enabled, an extra field called code is returned.

Example Request​

curl -X GET \
  https://services.truphone.com/connect-api/v2/orders/6d41c4ff-1877-4d13-82b0-7dad02c4b02a \
   -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": {
    "data": {
      "code": "A54G2W"
    },
    "matching_id": "6C-DA326D-K86D",
    "iccid": "8944000013283712983321",
    "subscription_id": "Q-hzHc6EErZPQcgw2L02_nDdruGtr6lDrM-jmja_xuE="
  },
  "_metadata": {
    "links": {
      "_lpa": "1$rsp.truphone.com$6C-DA326D-K86D",
      "_sim": "{BASE_URL}/v2/sims/8944000013283712983321",
      "_qrcode": "https://services.truphone.com/connect/qrcode/v1/esim/LPA:1$rsp.truphone.com$FDSAA-ASD",
      "_smdp": "rsp.truphone.com",
      "_subscription": "{BASE_URL}/v2/subscription/Q-hzHc6EErZPQcgw2L02_nDdruGtr6lDrM-jmja_xuE=",
      "_self": "{BASE_URL}/v2/orders/6d41c4ff-1877-4d13-82b0-7dad02c4b02a"
    }
  }
}

3. Check the voucher code​

The voucher code is designed to provide a new easy way to install an eSIM, being a secure way to share order information between different systems. For example, this would allow you to have a stand-alone system that creates orders and shares the codes with your customers via email or receipt. Your customers can then install the eSIM in a mobile application by providing the voucher code received.

The voucher code details can be fetched using the get voucher code details endpoint. Check the example request/response bellow.

Example Request​

curl -X GET \
  https://services.truphone.com/connect-api/v2/vouchers/A54G2W \
   -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​

{
  "code": "A54G2W",
  "tenant": "truphone_example",
  "created_on": "2021-05-01T19:05:05Z",
  "metadata": {
    "order_id": "6d41c4ff-1877-4d13-82b0-7dad02c4b02a",
    "matching_id": "6C-DA326D-K86D",
    "iccid": "8944000013283712983321",
    "product_id": "6h3BudA8aQGmJqRFKoHlsnkDy8LYn2c7s8wexZjKs93=",
  }
}

4. Redeem the voucher code​

Whenever a voucher code is used to install a new eSIM, the voucher should be marked as redeemed. The redeem voucher endpoint must be used for this, as shown in the example request/response shown below. Note that this step is not mandatory and It will only serve to identify vouchers that have already been redeemed.

Example Request​

curl -X PATCH \
  https://services.truphone.com/connect-api/v2/vouchers/A54G2W/redeem \
   -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​

202 Accepted

When the voucher is redeemed, the field redeemed_on is added to the voucher code details. This field has the date and time when the code was redeemed. In the example below is shown the details of a voucher already redeemed.

Example Response​

{
  "code": "A54G2W",
  "tenant": "truphone_example",
  "redeemed_on": "2021-05-02T07:26:19Z",
  "created_on": "2021-05-01T19:05:05Z",
  "metadata": {
    "order_id": "6d41c4ff-1877-4d13-82b0-7dad02c4b02a",
    "matching_id": "6C-DA326D-K86D",
    "iccid": "8944000013283712983321",
    "product_id": "6h3BudA8aQGmJqRFKoHlsnkDy8LYn2c7s8wexZjKs93=",
  }
}