InitSession : Initializes the signature/validation session
Goal of the method
This method enables the creditor to initialize the signing / validation session and retrieve a secure URL in which he will redirect his client.
Two versions are user to identify the client:
Weak Debtor Identification : The SignerInfo parameters include the basic information from the Debtor.
Strong Debtor Identification : The SubjectInfo parameters are intended to provide and strengthen the definition of customer identification carried out by the creditor.
Parameters of the method
The creditor sends a request to SPS Signature Web Service. The details of the parameters are described in the xls document: « SPS-SIGN-WSDL Description ».
Precisions about the UMR
The UMR (Unique Mandate Reference) is an optional parameter of the InitSession Web Service request. The creditor can choose to handle UMR on his side and to provide it in the request, or to let SPS and SPS Signature generate it.
If the creditor provides the UMR in the initSession call, then, each time he creates a new initSession he must use a new UMR. If the creditor does not provide the UMR, then SPS will automatically compute it
Precisions about redirection URLs
To use SPS Signature, the creditor must define 3 types of URLs : urlOK, urlKO and urlCancel. The purpose of these URLs is to redirect the end user to the proper page on the creditor website, according to his behavior on the signature pages.
The urlOK will be used by SPS Signature to redirect the user after he ended the signature successfully and hits the button “Continue my subscription” (or directly after hitting “Sign the SEPA Mandate” if the creditor has activated the option “Skip summary page).
The urlKO will be used when the mandate signature does not succeed. For example, it can happen if the user does not fill the good OTP code or if the signature session is aborted because the user took too much time to enter it.
Finally, the urlCancel will be used when the user chooses himself to cancel the signature of the mandate (for example, if he wants to modify his subscription on the creditor website).
Those URLs must be valid and HTTPS is highly recommended for security reasons. Moreover, since some browsers like Chrome now mark the HTTP website as “not secure”, the end user will be less likely to subscribe anything on the creditor website if it is marked as “not secure” because of HTTP usage.
After the redirection urls are are returned by the webservice response, it is important not to integrate signature pages in iframes. It is highly recommended to redirect in a new page. This is a result of adding the HTTP header X-Frame-Options: sameorigin in all signature pages against “clickjacking” attacks.
Response and error codes of the method
The SPS-SIGNATURE signing / validation service checks the request and returns the response to the creditor. The response contains the necessary information to the creditor to redirect the client to the signing / validation pages.
SOAP message examples
Example to initiate the session
Request to initialize the session (SignerInfo).
<urn:InitSessionRequest>
<urn1:creditorId>Test1</urn1:creditorId>
<urn1:parameters>
<urn1:transactionId>12345</urn1:transactionId>
<urn1:validation>false</urn1:validation>
<urn1:agreementScheme>SMS</urn1:agreementScheme>
<urn1:language>fr</urn1:language>
</urn1:parameters>
<urn1:postalAddress>
<urn2:BldngNm>15</urn2:BldngNm>
<urn2:StrtNm>rue de Paris</urn2:StrtNm>
<urn2:PstCd>69003</urn2:PstCd>
<urn2:City>Lyon</urn2:City>
<urn2:Ctry>France</urn2:Ctry>
</urn1:postalAddress>
<urn3:SignerInfos>
<urn3:LastName>Dupont</urn3:LastName>
<urn3:FirstName>Pierre</urn3:FirstName>
<urn3:Gender>M</urn3:Gender>
<urn3:Phone>+33606060606</urn3:Phone>
<urn3:Email>dupont.pierre@gmail.com</urn3:Email>
</urn3:SignerInfos>
</urn:InitSessionRequest>
WS Request to initialize the session (SubjectInfo).
<soap:Body xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-utility-1.0.xsd" wsu:Id="id-15">
<ns7:InitSessionRequest xmlns:ns2="urn:net:awl:sps:sign:ws:xsd:common.v10"
xmlns:ns3="urn:com:mediacert:signer:otu:xsd:v10"
xmlns:ns4="urn:com:mediacert:signer:otu:xsd:v20"
xmlns:ns5="urn:com:mediacert:signer:otu:xsd:subject:pre-identified:v20"
xmlns:ns6="urn:net:awl:sps:sign:ws:xsd:Session.v10"
xmlns:ns7="urn:net:awl:sps:sign:ws.v10">
<ns6:creditorId>23</ns6:creditorId>
<ns6:parameters>
<ns6:transactionId>1447775199337</ns6:transactionId>
<ns6:validation>false</ns6:validation>
<ns6:agreementScheme>EMAIL</ns6:agreementScheme>
<ns6:SCI>
<ns6:country>FR</ns6:country>
<ns6:checkDigit>06</ns6:checkDigit>
<ns6:businessCode>ZZZ</ns6:businessCode>
<ns6:nationalIdentifier>8849141607</ns6:nationalIdentifier>
</ns6:SCI>
<ns6:language>en</ns6:language>
<ns6:firstPaymentAmount>10.00</ns6:firstPaymentAmount>
<ns6:mandateSeqType>RCUR</ns6:mandateSeqType>
<ns6:mandateType>CORE</ns6:mandateType>
</ns6:parameters>
<ns6:postalAddress>
<ns2:BldngNm>7</ns2:BldngNm>
<ns2:StrtNm>RUE DE LA GARE</ns2:StrtNm>
<ns2:PstCd>75000</ns2:PstCd>
<ns2:City>PARIS</ns2:City>
<ns2:Ctry>FR</ns2:Ctry>
</ns6:postalAddress>
<ns4:SubjectInfos xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
Id="S1" xsi:type="ns5:PreIdentifiedSubjectInfos">
<ns4:LastName>MENAGER</ns4:LastName>
<ns4:FirstName>Nathalie</ns4:FirstName>
<ns4:Gender>M</ns4:Gender>
<ns4:Email>thierry.voelker@atos.net</ns4:Email>
<ns5:IdentificationMethod
xmlns:ns9="urn:com:mediacert:signer:otu:xsd:identification:sepa-customer:v20"
xsi:type="ns9:SepaCustomerIdentification">
<DeliveryAddress>
<NumberAndStreet>7 RUE DE LA GARE-AdrLIV</NumberAndStreet>
<ZipCode>75000</ZipCode>
<City>PARIS-AdrLIV</City>
<Country>FR</Country>
</DeliveryAddress>
<PositiveDeliveryFlag>true</PositiveDeliveryFlag>
<FirstDeliveryDate>2014-06-15</FirstDeliveryDate>
</ns5:IdentificationMethod>
</ns4:SubjectInfos>
</ns7:InitSessionRequest>
</soap:Body>
</soap:Envelope>
WS Response OK
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns7:InitSessionResponse xmlns:ns7="urn:net:awl:sps:sign:ws.v10"
xmlns:ns6="urn:com:mediacert:signer:otu:xsd:subject:pre-identified:v20"
xmlns:ns5="urn:com:mediacert:signer:otu:xsd:v20"
xmlns:ns4="urn:com:mediacert:signer:otu:xsd:v10"
xmlns:ns3="urn:net:awl:sps:sign:ws:xsd:common.v10"
xmlns:ns2="urn:net:awl:sps:sign:ws:xsd:Session.v10">
<ns2:response>
<ns3:Sts>ACCT</ns3:Sts>
<ns3:StsCd>OK</ns3:StsCd>
<ns3:StsInf/>
</ns2:response>
<ns2:url>https://SSL-test-Atos.fr/?t=33d66caa-dc7-8a80-133776e-48d5-a161-
b53987445e6f&tCh=DKs%2BDWfkdt39gujOO41gqJoI8dIUCSq3iT9QJ2%2FgMGo%3D</ns2:url>
</ns7:InitSessionResponse>
</soap:Body>
</soap:Envelope>
Example that triggers a KO response
The same query as in the previous example but with creditor identifier not recognized.
WS Request that triggers a KO response of type AUTH_FAIL
<urn1:creditorId>CreditorIdNotRecoginzed</urn1:creditorId>
WS Response KO
<response>
<ns2:Sts>RJCT</ns2:Sts>
<ns2:StsCd>AUTH_FAIL</ns2:StsCd>
<ns2:StsInf>Authentication Error.</ns2:StsInf>
</response>