VERSION 1.1.1
JULY 4, 2024
ESIM
EXTERNAL INTERFACE SPECIFICATION
Confidential
CONTENTS
1.
M2M...................................................................................................................................................... 2
1.1 ES2 (MN0 – SM-DP) Interface Description .......................................................................................... 2
1.1.1 Getting eUICC Information........................................................................................................... 2
1.1.2 Download a Profile ....................................................................................................................... 3
1.1.3 Updating the Policy Rules of a Profile .......................................................................................... 4
1.1.4 Updating eUICC Information ........................................................................................................ 5
1.1.5 Profile Enabling ............................................................................................................................ 7
1.1.6 Profile Disabling ........................................................................................................................... 8
1.1.7 Delete a Profile............................................................................................................................. 9
1.1.8 Notify a Profile is Disabled ......................................................................................................... 10
1.1.9 Notify a Profile Enabling............................................................................................................. 11
1.1.10 Notify a SM-SR Change ............................................................................................................ 11
1.1.11 Notify a Profile Deletion........................................................................................................... 12
1. 2 SOAP WEBSERVICES ....................................................................................................................... 12
2.
CONSUMER ......................................................................................................................................... 14
2.1 Data Elements ................................................................................................................................ 14
2.1.1
MatchingID .......................................................................................................................... 14
2.2
Function: DownloadOrder ...................................................................................................... 15
2.3
Function: ConfirmOrder .......................................................................................................... 17
2.4
Function: CancelOrder ............................................................................................................ 19
2.5
Function: ReleaseProfile ......................................................................................................... 21
2.6
JSON Request Response Examples......................................................................................... 23
2.7
Notification............................................................................................................................. 24
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
1
Confidential
1. M2M
1.1 ES2 (MN0 – SM-DP) Interface Description
1.1.1 Getting eUICC Information
Function name: GetEIS
Related Procedures: Profile Download and Installation
Function group: Profile Management
Function Provider: SM-DP
Description: This function allows the MNO to retrieve up to date the EIS information. The SM-DP shall
forward the function request to the SM-SR “ES3.GetEIS”.
Additional Input Data:
Input data name
Description
Type
No
MOC
eid
Identification of the targeted eUICC to be audited.
EID
1
M
smsr-id
Identification of the SM-SR currently in charge of eUICC
management.
OID
1
M
Type
No
MOC
EID
1
M
Table 2.1: Get EIS Additional Input Data
Additional Output Data:
Output data name Description
The relevant eUICC Information Set of the eUICC
eis
See section 5.1.1.1 for type description.
The list of EIS data fields that shall be included is defined
in Annex E.
Table 2.2: Get EIS Additional Output Data
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
2
Confidential
Specific status codes
Subject
Code
Subject
Reason
code
Reason
Description
8.7
SM-SR
3.9
Unknown
Indicates that the SM-SR, identified by this smsr-id, is unknown to
or whose address cannot be solved by the SM-DP
Table 2.3: Get EIS Specific Status Codes
1.1.2 Download a Profile
Function name: DownloadProfile
Related Procedures: Profile Download and Installation
Function group: Profile Management
Function Provider: SM-DP
Description: This function allows the MNO to request that the SM-DP downloads a Profile, identified
by its ICCID, via the SM-SR identified by the MNO on the target eUICC, the eUICC being identified by its
EID.
Additional Input Data:
Input data name
Description
Type
No
MOC
eid
Identification of the targeted eUICC to be audited.
EID
1
M
smsr-id
Identification of the SM-SR currently in charge of eUICC
management.
OID
1
M
profileType
Identification of the Profile type to download and install
in the eUICC.
String
1
C
iccid
Identification of the Profile to download and install.
ICCID
1
C
enableProfile
Indicates if the Profile shall be enabled after
downloading and installation.
BOOLEAN
1
M
Table 2.4: Download Profile Additional Input Data
NOTE: MNO can either provide ICCID or the Profile type. In case the Profile type is provided, the
SM-DP is free to select one of the Profiles that matches the Profile type.
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
3
Confidential
Additional Output Data:
Output data name Description
Type
No
MOC
ICCID
1
C
1
O
iccid
Indicates the Profile ICCID that has been downloaded
and installed
euiccResponseData
Contains the detailed error returned by the eUICC in case
the function execution failed on eUICC. The response
Hex binary
data is defined in ES5 depending of the requested
function.
Table 2.5: Download Profile Additional Output Data
Specific status codes
Subject
Code
Subject
Reason
code
Reason
Description
8.1.1
EID
3.9
Unknown
Indicates that the eUICC, identified by this EID, is unknown
to the SM-SR.
8.2.1
Profile
ICCID
1.2
Not Allowed
(Authorisation)
Indicates that the Profile, identified by this iccid is unknown
to the SM-DP.
8.2.1
Profile
ICCID
3.3
Already in Use
Indicates that the function caller is not allowed to perform
this function on the target Profile.
8.2.5
Profile
Type
3.9
Unknown
Indicates that the Profile type identified by this profileType
is unknown to the SM-DP.
8.2.5
Profile
Type
1.2
Not Allowed
(Authorisation)
Indicates that the function caller is not allowed to perform
this function on the ProfileType.
8.4
ISD-R
4.2
Execution error
Error during execution of the enabling command on the
eUICC. The output data “euiccResponseData contains the
exact response coming from the eUICC except in case of
fallback.
8.7
SM-SR
3.9
Unknown
Indicates that the SM-SR, identified by this smsr-id, is
unknown to or whose address cannot be resolved by the
SM-SR.
Table 2.6: Download Profile Additional Output Data
1.1.3 Updating the Policy Rules of a Profile
Function name: UpdatePolicyRules
Related Procedures: Function group: Profile Management
Function Provider: SM-DP
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
4
Confidential
Description: This function allows the MNO to update POL2 of a Profile, identified by its ICCID, and
installed on an eUICC identified by its EID.
The SM-DP shall forward this function request to the identified SM-SR by calling the
ES3.UpdatePolicyRules function
Additional Input Data:
Input data name
Description
Type
No
MOC
eid
Identification of the targeted eUICC.
EID
1
M
iccid
Identification of the Profile
ICCID
1
M
smsr-id
Identification of the SM-SR currently in charge of eUICC
management.
OID
1
M
POL2
1
M
This information may change during the eUICC’s lifetime.
pol2
The POL2 to associate with the identified Profile.
Table 2.7: Update Policy Rules Additional Input Data
Additional Output Data:
None
Specific status codes
In addition to those returned by ES3.UpdatePolicyRules, this function may return:
Subject
Code
Subject
Reason
code
Reason
Description
8.7
SM-SR
3.9
Unknown
Indicates that the SM-SR, identified by this smsr-id, is unknown to
or whose address cannot be solved by the SM-DP
Table 2.8: Update Policy Specific Status Codes
1.1.4 Updating eUICC Information
Function name: UpdateSubscriptionAddress
Related Procedures: Profile Download and Installation, Profile Enabling, Profile Enabling via SM-DP
Function group: Profile Management
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
5
Confidential
Function Provider: SM-DP
Description: Description: This function enables the caller to update the Subscription Address for a
Profile in the eUICC Information Set (EIS) of a particular eUICC identified by the EID and ICCID. The
Subscription Address is the identifier, such as MSISDN and/or IMSI, through which the eUICC is
accessible from the SM-SR via the mobile network when the Profile is in Enabled state. The function
replaces the content of the Subscription Address. For consistency within the system, it is the
responsibility of the caller to ensure that all data is provided. The SM- DP shall forward the function
request to the SM-SR “ES3.UpdateSubscriptionAddress”
Additional Input Data:
Input data name
Description
Type
No MOC
eid
Identification of the targeted eUICC to be audited.
EID
1
M
iccid
Identification of the target Profile.
ICCID
1
M
Subscription
1
Address
M
OID
M
newSubscriptionAddress The new Subscription Address
Identification of the SM-SR currently in charge of eUICC
management.
smsr-id
1
This information may change during the eUICC’s
lifetime.
Table 2.9: Update Subscription Address Additional Input Data
NOTE: MNO can either provide ICCID or the Profile type. In case the Profile type is provided, the
SM-DP is free to select one of the Profiles that matches the Profile type.
Additional Output Data:
This function has no additional output data.
Specific status codes
Subject
Code
Subject
Reason
code
Reason
Description
8.7
SM-SR
3.9
Unknown
Indicates that the SM-SR, identified by this smsr-id, is unknown to
or whose address cannot be resolved by the SM-DP
Table 2.10: Update Subscription Address Specific Status Codes
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
6
Confidential
1.1.5 Profile Enabling
Function name: EnableProfile
Related Procedures: Profile Enabling via SM-DP
Function group: Profile Management
Function Provider: SM-DP
Description: This function allows the MNO owner of the Profile to request a SM-DP to enable a Profile
in a specified eUICC, eUICC being identified by its EID.
This function may return:
•
•
•
A ‘Function execution status’ with ‘Executed- Success’ indicating that the Profile has been
enabled on the eUICC.
A ‘Function execution status’ with ‘Expired’ with a status code as defined in section 5.1.6.4
A ‘Function execution status’ indicating ‘Failed’ with a status code as defined in section 5.1.6.4
or a specific status code as defined in the table here after.
Additional Input Data:
Input data name
Description
Type
No
MOC
eid
Identification of the targeted eUICC.
EID
1
M
smsr-id
Identification of the SM-SR currently in charge of eUICC
management.
OID
1
M
iccid
Identification of the Profile to enable.
ICCID
1
M
Table 2.11: Enable Profile Additional Input Data
Additional Output Data:
None
Specific status codes
Subject
Code
Subject
Reason
code
Reason
Description
8.1.1
EID
3.9
Unknown
Indicates that the eUICC, identified by this EID, is
unknown to the SM-SR.
8.2.1
Profile
ICCID
3.9
Unknown
Indicates that the Profile identified by this ICCID is
unknown to the SM-SR.
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
7
Confidential
8.2.1
Profile
ICCID
3.4
Invalid destination
Indicates that the Profile identified by this ICCID is known
to the SM-SR but installed on another eUICC than the one
identified by the function caller.
8.2.1
Profile
ICCID
1.2
Not Allowed
(Authorisation)
Indicates that the function caller is not allowed to
perform this function on the target Profile.
8.2.2
POL1
1.2
Refused
The POL1 of the impacted Profiles doesn’t allow this
operation.
8.2.3
POL2
1.2
Refused
The POL2 of the impacted Profiles doesn’t allow this
operation.
8.4
ISD-R
4.2
Execution error
Error during execution of the enabling command on the
eUICC.
8.7
SM-SR
3.9
Unknown
Indicates that the SM-SR, identified by this smsr-id, is
unknown to or whose address cannot be resolved by the
function provider.
Table 2.12: Enable Profile Specific Status Codes
1.1.6 Profile Disabling
Function name: DisableProfile
Related Procedures: Profile Disabling via SM-DP
Function group: Profile Management
Function Provider: SM-DP
Description: This function allows the MNO owner of the Profile to request an SM-DP to disable the
Profile in a specified eUICC; eUICC being identified by its EID.
This function may return:
•
A ‘Function execution status’ with ‘Executed-Success’ indicating that the Profile has been
disabled on the eUICC.
•
A ‘Function execution status’ with ‘Executed-WithWarning’, with a status code, indicating that
the Profile has been disabled on the eUICC, and deleted after application of a POL1 or POL2
rule.
•
A ‘Function execution status’ with ‘Expired’ with a status code.
•
A ‘Function execution status’ indicating ‘Failed’ with a status code.
Additional Input Data:
Input data name
Description
Type
No
MOC
eid
Identification of the targeted eUICC.
EID
1
M
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
8
Confidential
smsr-id
Identification of the SM-SR currently in charge of eUICC
management. This information may change during the
eUICC’s lifetime.
OID
1
M
iccid
Identification of the Profile to disable.
ICCID
1
M
Table 2.13: Disable Profile Additional Input Data
Additional Output Data:
None
Specific status codes
Subject
Code
Subject
Reason
code
Reason
Description
8.7
SM-SR
3.9
Unknown
Indicates that the SM-SR, identified by this smsr-id, is unknown to
or whose address cannot be solved by the SM-SR
Table 2.14: Get EIS Specific Status Codes
1.1.7 Delete a Profile
Function name: DeleteProfile
Related Procedures: Profile and ISD-P Deletion
Function group: Platform Management
Function Provider: SM-DP
Description: This function allows the MNO to request deletion of the target ISD-P with the Profile to
the SM-DP; eUICC being identified by its EID. The SM-DP shall forward the function request to the SMSR “ES3.DeleteISDP”.
Additional Input Data:
Input data name
Description
Type
No
MOC
eid
Identification of the targeted eUICC.
EID
1
M
iccid
Identification of the Profile to disable.
ICCID
1
M
smsr-id
Identification of the SM-SR currently in charge of eUICC
management.
OID
1
M
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
9
Confidential
This information may change during the eUICC’s lifetime.
Table 2.15: Delete Profile Additional Input Data
Additional Output Data:
None
Specific status codes
Subject
Code
Subject
Reason
code
Reason
Description
8.7
SM-SR
3.9
Unknown
Indicates that the SM-SR, identified by this smsr-id, is unknown to
or whose address cannot be resolved by the SM-DP
Table 2.16: Delete Profile Specific Status Codes
1.1.8 Notify a Profile is Disabled
Function name: HandleProfileDisabledNotification
Related Procedures: Profile Download and Installation, Profile Enabling via SM-DP, Profile Enabling,
Fall-back Activation Procedure
Function group: Platform Management
Notification handler/recipient: MNO
Description: This function shall be called to notify that the Profile identified by its ICCID has been
disabled on the eUICC identified by its EID. It is assumed that the ICCID is enough for the SM-DP to
retrieve the MNO to notify. This notification also conveys the date and time specifying when the
operation has done.
What is performed by the MNO receiving this notification is out of scope of this specification.
Additional Input Data:
Input data name
Description
Type
No MOC
eid
Identification of the targeted eUICC.
EID
1
M
iccid
Identification of the Profile that has been disabled.
ICCID
1
M
DATETIME
1
M
completionTimestamp Indication of the date/time when the operation has
been performed.
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
10
Confidential
Table 2.17: Handle Profile Disabled Notification Additional Input Data
1.1.9 Notify a Profile Enabling
Function name: HandleProfileEnabledNotification
Related Procedures: Profile Disabling and Profile Disabling via SM-DP, Fall-back Activation Procedure
Function group: Platform Management
Notification handler/recipient: MNO
Description: This function shall be called to notify that the Profile identified by its ICCID has been
enabled on the eUICC identified by its EID. It is assumed that the ICCID is sufficient for the SM-DP to
retrieve the MNO to notify.
This notification also conveys the date and time specifying when the operation has been done. What is
performed by the MNO receiving this notification is out of scope of this specification.
Additional Input Data:
Input data name
Description
Type
No MOC
eid
Identification of the targeted eUICC.
EID
1
M
iccid
Identification of the Profile that has been enabled..
ICCID
1
M
DATETIME
1
M
completionTimestamp Indication of the date/time when the operation has
been performed.
Table 2.18: Handle Profile Disabled Notification Additional Input Data
1.1.10 Notify a SM-SR Change
Function name: HandleSMSRChangeNotification
Related Procedures: SM-SR Change
Function group: eUICC Management
Notification handler/recipient: MNO
Description: This function shall be called for notifying each MNO owning a Profile hosted in the eUICC,
identified by its EID, that the SM-SR has changed. The notification is sent by the new SM-SR to the SMDP, which route this notification to the MNO.
This notification also conveys the date and time specifying when the operation has been done.
This notification is not related to a particular Profile. It is up to the notification recipient to perform any
action related to each Profile that is deployed on this eUICC.
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
11
Confidential
Additional Input Data:
Input data name
Description
Type
No MOC
eid
Identification of the targeted eUICC.
EID
1
M
iccid
Identification of the Profile that has been deleted.
ICCID
1
M
DATETIME
1
M
completionTimestamp Indication of the date/time when the operation has
been performed.
Table 2.19: Handle SM-SR Change Notification Additional Input Data
No output data is expected in response to this notification.
1.1.11 Notify a Profile Deletion
Function name: HandleProfileDeletedNotification
Related Procedures: Profile Enabling, Profile Enabling via SM-DP
Function group: Platform Management
Notification handler/recipient: MNO
Description: This function shall be called to notify that the Profile identified by its ICCID has been
deleted on the eUICC identified by its EID.
This notification also conveys the date and time specifying when the operation has been done. What is
performed by the MNO receiving this notification is out of scope of this specification.
Additional Input Data:
Input data name
Description
Type
No MOC
eid
The relevant part of the eUICC Information Set linked
with the MNO owning the Profile hosted in the eUICC.
EIS
1
M
iccid
Identification of the Profile that has been deleted.
ICCID
1
M
DATETIME
1
M
completionTimestamp Indication of the date/time when the operation has
been performed.
Table 2.19: Handle SM-SR Change Notification Additional Input Data
1. 2
SOAP WEBSERVICES
There is an example wsdl document here.
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
12
Confidential
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
13
Confidential
2. CONSUMER
The ES2+ interface is used by the Operator to order the Profile Package preparation for specific eUICC(s)
and the delivery of the Profile Package from the SM-DP+.
SM-DP+
Operator
ES2+
Figure 3.1: ES2+
The Operator communicates with the SM-DP+ through a secure connection. The level of security
requested on this interface and the level of data encryption is defined in GSMA SAS SM specification
[23].
The SM-DP+ MAY perform additional functions, which are out of scope of this specification.
2.1
Data Elements
2.1.1 MatchingID
The MatchingID is mandatory information (but MAY be zero-length) that SHALL be set-up between the
Operator and the SM-DP+, to identify the context of a specific management order given to the SM-DP+.
The MatchingID is equivalent to the "Activation Code Token" as defined is SGP.21 [4].
The format and content of the MatchingID is subject to the following constraints:
The MatchingID, when not a zero-length value, SHALL be a unique identifier in the context of the
Operator and the SM-DP+ to:
• Match a download order initiated by the Operator with a Profile Download request coming from
an LPD.
• As a protection for the SM-DP+: the SM-DP+ SHALL only process requests containing a
MatchingID known to the SM-DP+ (and therefore inherently valid).
It SHALL consist only of upper case alphanumeric characters (0-9, A-Z) and the "-" in any combination.
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
14
Confidential
2.2
Function: DownloadOrder
Related Procedures: Download initiation
Function Provider Entity: SM-DP+
Description: This function is used to instruct the SM-DP+ of a new Profile download request.
The EID is optional and MAY not be known at this stage. In this case the SM-DP+, with the Operator, MAY
verify if the EID acquired during the Download and installation procedure is compatible with the
requested Profile Type (see also Annex F). If the SM-DS or Default SM-DP+ is to be used for the Profile
download, then the EID SHOULD be present; if not present, the EID SHALL be provided later in
"ES2+.ConfirmOrder".
Upon reception of this function call, the SM-DP+ SHALL:
•
Reserve an ICCID in its inventory. If the ICCID was provided as input data, the reservation SHALL
use this value. Otherwise the reservation SHALL be done corresponding to the requested Profile
Type with a value available in the SM-DP+'s inventory.
•
If the EID is known, the ICCID is linked to this EID and the Profile state SHALL be set to "Linked".
Otherwise, the Profile state SHALL be set to "Allocated".
The SM-DP+ MAY perform additional operations, which are out of scope of this specification.
This function SHALL return one of the following:
•
A 'Function execution status' with 'Executed-Success' indicating that the ICCID has been
reserved.
•
A 'Function execution status' indicating 'Failed' with a status code as defined in table 24 or a
specific status code as defined in the following table.
Additional Input Data:
Input data name
Description
Type
No
MOC
eid
Identification of the targeted eUICC.
EID
1
O
iccid
Identification of the Profile to download and install in the ICCID
eUICC.
1
C
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
15
Confidential
Identification of the Profile Type to download and install
in the eUICC.
profileType
String
1
C
Table 3.1: DownloadOrder Additional Input Data
NOTE:
The Operator can provide the ICCID and/or the Profile Type. In case where the Profile
Type is provided, the SM-DP+ is free to select one of the Profiles that matches the
Profile Type.
Additional Output Data:
Output data name Description
Type
Identification of the Profile to download and install in
the eUICC. If ICCID was provided as an input data, the
returned value SHALL be the same. If not provided as an
input data the returned value SHALL be one of the
ICCID
values available in the SM-DP+ inventory and
corresponding to the Profile Type.
iccid
No
MOC
1
M
Table 3.2: DownloadOrder Additional Output Data
Specific status codes
Subject
Code
Subject
Reason
code
Reason
Description
8.2.1
Profile
ICCID
3.9
Unknown
Indicates that the Profile, identified by this ICCID is
unknown to the SM-DP+.
8.2.1
Profile
ICCID
1.2
Not Allowed
(Authorisation)
Indicates that the function caller is not allowed to
perform this function on the target Profile.
8.2.1
Profile
ICCID
3.3
Already in Use
Indicates that the Profile identified by the provided
ICCID is not available.
8.2.5
Profile
Type
3.9
Unknown
Indicates that the Profile Type identified by this Profile
Type is unknown to the SM-DP+.
8.2.5
Profile
Type
1.2
Not Allowed
(Authorisation)
Indicates that the function caller is not allowed to
perform this function on the Profile Type.
8.2.5
Profile
Type
3.7
Unavailable
No more Profile available for the requested Profile Type.
8.2.5
Profile
Type
3.8
Refused
Indicates that the Profile Type identified by this Profile
Type is not aligned with the Profile Type of Profile
identified by the ICCID.
Table 3.3: DownloadOrder Specific Status Codes
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
16
Confidential
2.3
Function: ConfirmOrder
Related Procedures: Download initiation
Function Provider Entity: SM-DP+
Description: This function is used to confirm a previously requested download order.
If the SM-DS or Default SM-DP+ is to be used for the Profile download and the EID has not been
provided within the DownloadOrder function, then the EID SHALL be present. If EID is not present,
the SM-DP+ SHALL return a 'Function execution status' indicating 'Failed' with a status code '8.1.1 EID
- 2.2 Mandatory Element Missing'.
If the EID is present in both the DownloadOrder and ConfirmOrder functions it SHALL be the same
value. If EID is different, the SM-DP+ SHALL return a 'Function execution status' indicating 'Failed'
with a status code '8.1.1 EID - 3.10 Invalid Association'.
On reception of this function call, the SM-DP+ SHALL:
•
•
•
•
•
•
Confirm the allocation of an ICCID in its inventory.
Generate a MatchingID if it is not provided by the Operator.
Store the MatchingID.
Store the EID if available.
If the Confirmation Code is provided by the Operator, calculate the hash of the Confirmation
Code and store the hash value together with the MatchingID, where the hash value is
SHA256(Confirmation Code).
If SM-DS address is provided:
•
•
•
Verify that the MatchingID is not a zero length value.
Store the SM-DS address with the Profile to be used later for Event Registration and
Event Deletion.
If the releaseFlag is set to true, perform Event Registration to the SM-DS address stored
with the Profile, where the MatchingID SHALL be used as the EventID. Otherwise the
Event Registration at this point in time is optional. If it is not done in this step, it will be
done during the ReleaseProfile function.
The SM-DP+ MAY perform additional operations.
This function SHALL return one of the following:
•
A 'Function execution status' with 'Executed-Success' indicating that the ICCID has been
reserved.
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
17
Confidential
•
A 'Function execution status' indicating 'Failed' with a status code or a specific status
code as defined in the following table.
Additional Input Data:
Input data name
Description
Type
No
MOC
iccid
Identification of the Profile to download and install in the ICCID
eUICC.
1
M
eid
Identification of the targeted eUICC.
EID
1
O
matchingId
The MatchingID as defined in section (4.1), when
generated by the Operator
String
1
O
confirmationCode
A code used to authorise the usage of the MatchingID to
confirm the download and installation of the Profile
String
1
O
smdsAddress
The SM-DS address to be used for Event Registration
FQDN
1
O
releaseFlag
If 'true', the Profile SHALL be immediately released for
Profile download and installation
Boolean
1
M
Type
No
MOC
Table 3.4: ConfirmOrder Additional Input Data
Additional Output Data:
Output data name Description
eid
Identification of the targeted eUICC. EID SHALL be
returned if bound to this order.
EID
1
C
matchingId
The MatchingID as defined in section ( 4.1)
String
1
M
smdsAddress
The SM-DP+ address to be used for this specific
download order.
FQDN
1
O
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
18
Confidential
Specific status codes
Subject
Code
Subject
Reason
code
Reason
Description
8.2.1
Profile
ICCID
3.9
Unknown
Indicates that the Profile, identified by this
ICCID is unknown to the SM-DP+.
8.2.1
Profile
ICCID
1.2
Not Allowed
(Authorization)
Indicates that the function caller is not allowed
to perform this function on the target Profile.
8.2.6
Matching
ID
3.3
Already in Use
(Uniqueness)
Conflicting MatchingID value.
8.9
SM-DS
5.1
Inaccessible
Indicates that the smdsAddress is invalid or not
reachable.
8.9
SM-DS
4.2
Execution Error
The cascade SM-DS registration has failed. SMDS has raised an error.
8.1.1
EID
2.2
Mandatory
Element Missing
Indicates that the EID is missing in the context
of this order (SM-DS address provided or
MatchingID value is empty).
8.1.1
EID
3.10
Invalid Association
Indicates that a different EID is already
associated with this ICCID.
Table 3.5: ConfirmOrder Additional Output Data
2.4
Function: CancelOrder
Related Procedures: Download initiation
Function Provider Entity: SM-DP+
Description: This function is used to cancel a pending download order request.
On reception of this function call, the SM-DP+ SHALL:
•
Confirm that the Profile identified by the provided ICCID is allocated and not yet
downloaded.
•
If there is a MatchingID already associated with the ICCID, then check that the
provided MatchingID is the one associated with the ICCID.
•
If there is an EID already associated with the ICCID, then check that the provided EID is the
one associated with the ICCID.
If any of these verifications fail, the SM-DP+ SHALL return a 'Function execution status'
indicating 'Failed' with the relevant status code.
Otherwise the SM-DP+ SHALL:
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
19
Confidential
•
Cancel the pending order if possible, and return the ICCID to inventory or mark it as not
available for future use, based on the provided final Profile status indicator.
•
If the order was previously linked to an event registration, the SM-DP+ SHALL
subsequently execute the event deletion procedure.
The SM-DP+ MAY perform additional operations.
This function SHALL return one of the following:
•
A 'Function execution status' with 'Executed-Success' indicating that the ICCID has been
released from the MatchingID and the associated profile will not be downloaded.
•
A 'Function execution status' indicating 'Failed' with a status code as defined or a
specific status code as defined in the table here after.
Additional Input Data:
Input data name
Description
Type
No
MOC
iccid
Identification of the Profile to be cancelled from
previously requested download order.
ICCID
1
M
eid
eUICC Identifier.
EID
1
C
matchingId
The MatchingID as generated in ConfirmOrder.
String
1
C
finalProfileStatusIndicator
An indicator uses to indicate to the SM-DP+ to
perform additional operations.
String
1
M
Table 3.6: CancelOrder Additional Input Data
The eid input data SHALL be provided if an EID has been associated for the download order to cancel.
The matchingId input data SHALL be provided if a MatchingID has been allocated for the
download order to cancel.
Final Profile Status
Description
Indicator
Available
Indicates that the download order for this Profile, identified by this ICCID will be
cancelled; and the ICCID is released back to the inventory and available for future use.
Unavailable
Indicates that the download order for this Profile, identified by this ICCID will be
cancelled; and the ICCID is not available for future use.
Table 3.7: Definition of Final Profile Status Indicator
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
20
Confidential
Additional Output Data:
No additional output data.
Specific Status Codes
Subject
Code
Subject
Reason
code
Reason
Description
8.2.1
Profile
3.9
Unknown
Indicates that the Profile, identified by this ICCID
is unknown to the SM-DP+.
8.2.1
Profile
ICCID
1.2
Not Allowed
Indicates that the function caller is not allowed to
perform this function on the target Profile.
8.2.1
Profile
ICCID
3.3
Already in Use The profile, identified by this ICCID, is already
downloaded.
8.2.1
Profile
3.10
Invalid
Association
Indicates that a different EID is associated with
this ICCID.
8.2.6
Matching
ID
3.10
Invalid
Association
Indicates that a different MatchingID is
associated with this ICCID.
Table 3.8: CancelOrder Specific Status Codes
2.5
Function: ReleaseProfile
Related Procedures: Download initiation
Function Provider Entity: SM-DP+
Description: This function is used to release the Profile in order to allow the End User to start the
download and installation procedure after the Operator performs any relevant operation on its backend (e.g. provisioning of HLR).
On reception of this function call, the SM-DP+ SHALL:
•
Verify that the Profile identified by the provided ICCID has been processed with
"ES2+.DownloadOrder" and "ES2+.ConfirmOrder", but not released yet. If this verification
fails, the SM-DP+ SHALL return error status "8.2.1 Profile ICCID - 3.5 Invalid transition"
•
Set the Profile state as 'Released' to allow the download.
•
If SM-DS address was stored with the Profile and if the Event Registration was not already
done, perform Event Registration to the SM-DS, where the MatchingID SHALL be used as the
EventID.
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
21
Confidential
The SM-DP+ MAY perform additional operations, which are out of scope of this
specification.
This function SHALL return one of the following:
•
A 'Function execution status' with 'Executed-Success' indicating that the Profile
identified by the provided ICCID has been released and is ready to download.
•
A 'Function execution status' indicating 'Failed' with a status or a specific status code as
defined in the table here after.
Additional Input Data:
Input data name
Description
Type
No
MOC
iccid
Identification of the Profile to be released from
previously requested download order.
ICCID
1
M
eid
eUICC Identifier.
EID
1
C
matchingId
The MatchingID as generated in ConfirmOrder.
String
1
C
finalProfileStatusIndicator
An indicator uses to indicate to the SM-DP+ to
perform additional operations.
String
1
M
Table 3.9: ReleaseProfile Additional Input Data
Additional Output Data:
No additional output data.
Specific Status Codes
Subject
Code
Subject
Reason
code
Reason
Description
8.2.1
Profile
ICCID
3.9
Unknown
Indicates that the Profile, identified by this
ICCID, is unknown to the SM-DP+.
8.2.1
Profile
ICCID
1.2
Not Allowed
(Authorization)
Indicates that the function caller is not
allowed to perform this function on the
target Profile.
8.2.1
Profile
ICCID
3.5
Invalid transition
Indicates that the target Profile cannot be
released.
Table 3.10: ReleaseProfile Additional Input Data
NOTE: If a Profile has already been released this function will return 'Executed-Success' and take
no other action.
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
22
Confidential
2.6
JSON Request Response Examples
An example for the "ES2+.DownloadOrder" function is shown as follows.
HTTP Request (from Operator to SM-DP+):
HTTP POST /gsma/rsp2/es2plus/downloadOrder HTTP/1.1
Host: smdp.gsma.com
X-Admin-Protocol: gsma/rsp/v2.2.0
Content-Type: application/json
Content-Length: XXX
{
"header":{
"functionRequesterIdentifier":"RequesterID",
"functionCallIdentifier":"TX-567"
},
"eid":"01020300405060708090A0B0C0D0EOF",
"iccid":"01234567890123456789",
"profileType":"myProfileType"
}
HTTP Response for a successful execution:
HTTP/1.1 200 OK
X-Admin-Protocol: gsma/rsp/v2.2.0
Content-Type: application/json
Content-Length: XXX
{
"header":{
"functionExecutionStatus" ":"RequesterID",
"functionCallIdentifier":"TX-567"
},
"eid":"01020300405060708090A0B0C0D0EOF",
"iccid":"01234567890123456789",
"profileType":"myProfileType"
}
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
23
Confidential
HTTP Response for a failed execution:
HTTP/1.1 200 OK
X-Admin-Protocol: gsma/rsp/v2.2.0
Content-Type: application/json
Content-Length: XXX
{
"header":{
"functionExecutionStatus":{
"status":"Failed",
"statusCodeData":{
"subjectCode":"8.2.5",
"reasonCode":"3.7",
"message":"No more Profile"
}
}
}
}
2.7
Notification
Each of the below statuses of notifications will be published to interfaces of MNO.
notificationInstall
notificationEnable
notificationDisable
notificationDelete
7/4/2024
EXTERNAL INTERFACE TECHNICAL SPECIFICATION
24